spring-cloud-contract/tests/spring-cloud-contract-stub-runner-amqp

=== Stub Runner Spring AMQP

Spring Cloud Contract Verifier Stub Runner's messaging module provides an easy way to
integrate with Spring AMQP's Rabbit Template. For the provided artifacts, it
automatically downloads the stubs and registers the required routes.

The integration tries to work standalone (that is, without interaction with a running
RabbitMQ message broker). It expects a `RabbitTemplate` on the application context and
uses it as a spring boot test named `@SpyBean`. As a result, it can use the mockito spy
functionality to verify and inspect messages sent by the application.

On the message consumer side, the stub runner considers all `@RabbitListener` annotated
endpoints and all `SimpleMessageListenerContainer` objects on the application context.

As messages are usually sent to exchanges in AMQP, the message contract contains the
exchange name as the destination. Message listeners on the other side are bound to
queues. Bindings connect an exchange to a queue. If message contracts are triggered, the
Spring AMQP stub runner integration looks for bindings on the application context that
match this exchange. Then it collects the queues from the Spring exchanges and tries to
find message listeners bound to these queues. The message is triggered for all matching
message listeners.

==== Adding the Runner to the Project

You can have both Spring AMQP and Spring Cloud Contract Stub Runner on the classpath and
set the property `stubrunner.amqp.enabled=true`. Remember to annotate your test class
with `@AutoConfigureStubRunner`.

IMPORTANT: If you already have Stream and Integration on the classpath, you need
to disable them explicitly by setting the  `stubrunner.stream.enabled=false` and
`stubrunner.integration.enabled=false` properties.

Assume that you have the following Maven repository with a deployed stubs for the
`spring-cloud-contract-amqp-test` application.

[source,bash,indent=0]
----
└── .m2
    └── repository
        └── com
            └── example
                └── spring-cloud-contract-amqp-test
                    ├── 0.4.0-SNAPSHOT
                    │   ├── spring-cloud-contract-amqp-test-0.4.0-SNAPSHOT.pom
                    │   ├── spring-cloud-contract-amqp-test-0.4.0-SNAPSHOT-stubs.jar
                    │   └── maven-metadata-local.xml
                    └── maven-metadata-local.xml
----

Further assume that the stubs contain the following structure:

[source,bash,indent=0]
----
├── META-INF
│   └── MANIFEST.MF
└── contracts
    └── shouldProduceValidPersonData.groovy
----

Consider the following contract:

[source,groovy]
----
include::src/test/groovy/org/springframework/cloud/contract/stubrunner/messaging/amqp/AmqpStubRunnerSpec.groovy[tags=amqp_contract,indent=0]
----

Now consider the following Spring configuration:

[source,yaml]
----
include::src/test/resources/application.yml[]
----

===== Triggering the message

To trigger a message using the contract above, use the `StubTrigger` interface as
follows:

[source,groovy]
----
include::src/test/groovy/org/springframework/cloud/contract/stubrunner/messaging/amqp/AmqpStubRunnerSpec.groovy[tags=client_trigger,indent=0]
----

The message has a destination of `contract-test.exchange`, so the Spring AMQP stub runner
integration looks for bindings related to this exchange.

[source,java]
----
include::src/main/java/org/springframework/cloud/contract/stubrunner/messaging/amqp/AmqpMessagingApplication.java[tags=amqp_binding,indent=0]
----

The binding definition binds the queue `test.queue`. As a result, the following listener
definition is matched and invoked with the contract message.

[source,java]
----
include::src/main/java/org/springframework/cloud/contract/stubrunner/messaging/amqp/AmqpMessagingApplication.java[tags=amqp_listener,indent=0]
----

Also, the following annotated listener matches and is invoked:
[source,java]
----
include::src/main/java/org/springframework/cloud/contract/stubrunner/messaging/amqp/MessageSubscriberRabbitListener.java[tags=amqp_annotated_listener,indent=0]
----

NOTE: The message is directly handed over to the `onMessage` method of the
`MessageListener` associated with the matching `SimpleMessageListenerContainer`.

===== Spring AMQP Test Configuration

In order to avoid Spring AMQP trying to connect to a running broker during our tests
configure a mock `ConnectionFactory`.

To disable the mocked ConnectionFactory, set the following property:
`stubrunner.amqp.mockConnection=false`

[source,yaml]
----
stubrunner:
  amqp:
    mockConnection: false
----