Skip to content

Run the conformance suite

The adapter is held to go/messaging's conformance suite, conformance.RunDurable, against a real Artemis in a container. The suite is the core's, described in the backend reference; this page is how to run the adapter's.

What you need

  • A checkout of messaging-amqp.
  • A Docker daemon. The fixture starts apache/artemis:2.57.0-alpine through testcontainers-go.
  • Network access to pull the image and modules, and time: CI allows 25 minutes, because the suite restarts and kills the container.

Run it

$ just test-integration

which is:

$ INT_TEST_INTEGRATION=1 go test ./test/integration/... -v

Without INT_TEST_INTEGRATION=1 the package prints integration tests skipped; set INT_TEST_INTEGRATION=1 (needs a Docker daemon) and exits 0, so a plain go test ./... needs no Docker. Set INT_TEST_LOG=1 as well to send the backend's own log to stderr.

The unit gate, just test (go test ./... -cover), needs nothing. It includes a dependency guard, TestDependencyFootprint, that fails if the module's graph reaches a config framework, a CLI framework, telemetry, another broker's client or a cloud SDK.

What it runs

TestConformance runs conformance.RunDurable once per format, as subtests named binary, structured, masstransit and nservicebus. Binary is the unset default, so its run also proves the default. Each run uses the options WithKillable, WithSlowPublishes and WithForeign, and destroys its queues afterwards, because they would otherwise receive the next run's messages. WithSlowPublishes lightens the volume rows, because every send waits on Artemis's journal.

Beside it are tests of this adapter's own behaviour:

Test Proves
TestAPublishIsWrittenWithTheFormat Publish honours Settings.Format.
TestAnInteropFormatIsWhatGoesOut the MassTransit and NServiceBus writers are what reach the wire.
TestAPropertyNoFormatTakesIsForeign a string property no format takes arrives as Delivery.Foreign().
TestFeaturesAreReadFromTheBroker Features reports the fixture's broker-global settings.
TestAtMostOnceIsSettledBeforeHandOff a competing member that retires without a word leaves nothing for the next.
TestCreditIsReplenishedOnSettlement a bound of two still delivers five.
TestAQueueWithoutADeadLetterQueueIsRefused a dead-letter address with no queue is refused by name.
TestACrashKeepsTheDeliveryCount a broker killed with a delivery in hand keeps the count.

What the fixture does

The fixture is the operator. In test/integration:

  • main_test.go starts the broker with testdata/broker.xml mounted as its override, waits for both the listening port and the log line Server is now (live|active), then dials until the broker answers.
  • fixture_test.go implements conformance.Durable (Open, and Restart, which stops and starts the same container so it keeps its data), Immutable (the Pattern is the only field the adapter refuses to change on reopen) and Killable (Kill destroys the queue and its consumers through management, the only form Artemis accepts while a consumer is attached). It is also the adapter's Topology: on the first resolve of a durable name it creates the multicast queue with Artemis{}.Create, and it never changes one it already made.
  • unreadable_test.go implements conformance.Foreign. SendUnreadable sends one message to the subject's address with its own AMQP client, past the bus's writer, in each of the three kinds the suite asks for: unclaimed, ambiguous and malformed. Every run reads both CloudEvents formats, so the same three messages fail for each.

Restart is an orderly stop. A broker asked to stop flushes on the way down, so it proves nothing about what is on disk when it is not asked. TestACrashKeepsTheDeliveryCount kills the broker outright for that.

Reading a failure

Run with INT_TEST_LOG=1 and the subtest name, for example:

$ INT_TEST_INTEGRATION=1 INT_TEST_LOG=1 go test ./test/integration/... -run 'TestConformance/binary' -v

A failure that only shows under masstransit or nservicebus is a format rule: those formats refuse what they cannot carry. The suite's IDs are UUIDs and its payloads are JSON for that reason.

Running it for another Management

A new Management is held to the same suite with a fixture of its own: a conformance.Durable whose Open calls amqp.New with the new Management, a Restart, and a Topology that makes the queues. No other Management has been run through it: see Limits and gaps.