Arquillian Algeron

Obviously any Contract test is composed by two faces, one for the consumer and another one for the provider and a contract file that is sent from consumer to provider. Let’s see the steps to write contract tests using Pact.

These steps can be summarized in next diagram:

You can use in a test @StubServer annotation to inject URL where stub http server is started.

Arquillian has two modes of working In Container (which means having a @Deployment method) and Arquillian takes care of managing lifecycle of the server and deploy the archive, or Standalone (no @Deployment method) where Arquillian assumes that everything is already deployed.

Let’s see how to write the consumer part in In Container mode.

First thing to do is add typical Arquillian dependencies such as Arquillian bom and the dependency of the container you want to use. Nothing new here:

Then you need to add arquillian-pact-consumer dependency as well as pact-jvm-consumer dependency:

After dependencies you can write the test that defines the contract:

After this test is executed, contract is placed at target/pacts directory or build/pacts in case of using Gradle. Then you can send contract to provider side.

Notice that contract and/or mock responses are defined using Pact DSL. You can read more about this DSL at Using the Pact DSL directly.

Important things to retain from consumer part:

You can see the full example at: ftest-incontainer

Standalone mode (no @Deployment method), Arquillian assumes that everything is already deployed.

The only difference between previous example is that you only need arquillian-junit-standalone instead of arquilian-junit-container and don’t need to define any container adapter. Obviously no @Deployment method is required:

Code is pretty similar as previous test but now the consumer client/gateway object is instantiated as plain java object instead of container managed.

You can see the full example at: ftest

Arquillian Algeron Pact Consumer can be configured using Arquillian configuration mechanism (arquillian.xml file or system properties).

The attributes are:

Forge Arquillian Addon offers an integration with Arquillian Algeron Consumer.

To use it apart from having the Forge Arquillian Addon installed in Forge, you need to have arquillian dependencies registered on build tool.

To register Arquillian Consumer dependencies in build tool just run next command:

arquillian-algeron-setup-consumer --contracts-library pact

After that you can enrich a given Arquillian test with consumer annotations and contract scaffolding with next command:

arquillian-algeron-create-contract-fragment --consumer myconsumer --provider myprovider --fragment myFragment --test-class org.superbiz.MyContractTest

It is important to note that test class should be already created (for example using arquillian-create-test --named MyContractTest --target-package org.superbiz command).

See it alive in next terminal cast:

Folder publisher copies "pact" files from configured output directory (by default target/pacts) to another directory. To configure folder publisher you need to configure pactPublishConfiguration with next configuration:

You can set outputFolder value using Java system property ${name:defaultvalue} or environment variable `${env.name:defaultvalue}. For example `outputFolder: ${output:/mypacts} will first check if there is a Java system property with name output and get the value. If that is not defined it will use the default value i.e. /mypacts.

URL publisher sends a POST request to configured URL, appending at the end of the URL the "pact" filename and sending the contract content as body content. For example given http://myhost/pacts and a "contract" file called consumer_provider.json, the resulting URL would be: http://myhost/pacts/consumer_provider.json

You can set url value using Java system property ${name:defaultvalue} or environment variable ${env.name:defaultvalue}.

You can publish contracts to Pact Broker server.

Also you need to add org.arquillian.algeron:arquillian-algeron-consumer-pact-broker-publisher:${version} dependency. This is only supported in case of using Pact provider.

Possible attributes:

Notice that all these attributes can be set using system properties or environment variable as any other property in arquillian.xml.

Git publisher publishes contract files to a git repository. Optionally they can be committed into a branch or tag the commit.

This publisher just takes the generated contract files, copied to repository, commit them and push them to remote.

First of all you need to add git publisher dependency:

Any of the git attributes can be set using Java system property ${name:defaultvalue} or environment variable ${env.name:defaultvalue}.

You can also implement your own publisher. To make it so you need create a class that implements org.arquillian.algeron.consumer.spi.publisher.ContractsPublisher and register this service inside META-INF/services/org.arquillian.algeron.consumer.spi.publisher.ContractsPublisher.

You can see an example at https://github.com/arquillian/arquillian-algeron/tree/master/consumer/git-publisher.

Forge Arquillian Addon offers an integration with Arquillian Algeron Publishers.

To use it apart from having the Forge Arquillian Addon installed in Forge, you also need to have Arquillian Algeron Consumer dependencies registered on build tool (for example using command arquillian-algeron-setup-consumer --contracts-library pact JBoss Forge Arquillian Consumer Addon ).

Each of the publishers have its own command to be registered where you can set its specific configuration parameters.

See it alive in next terminal cast:

One real important thing in provider tests is where contract files are located and how the test should load it. To specify this, Arquillian Provider provides some class annotations, but of course you can implement your own as well:

It’s possible to use a custom Contracts retriever. For this, implement interface ContractsRetriever and annotate the test class with @ContractSource(MyOwnRetriever.class).

You can see an example at: ContractsUrlLoader java class.

As it happens with consumer part, Arquillian Algeron allows you to configure retrievers in arquillian.xml.

Forge Arquillian Addon offers an integration with Arquillian Algeron Retrievers.

To use it apart from having the Forge Arquillian Addon installed in Forge, you also need to have Arquillian Algeron Provider dependencies registered on build tool (for example using command arquillian-algeron-setup-provider --contracts-library pact JBoss Forge Arquillian Provider Addon ).

Each of the publishers have its own command to be registered where you can set its specific configuration parameters.

See it alive in next terminal cast:

Again you can write provider’s part using in container or standalone mode. In this section, an in container mode example is developed.

Apart from adding Arquillian bom dependencies as mentioned in consumer part, you need to add arquillian algeron pact dependencies:

After dependencies you can write the test that replies all contracts against provider:

When running this test Arquillian Algeron Pact Provider will do next things:

So as you can see the should_provide_valid_answers might be run several times depending on the number of consumers that depends on provider and the number of requests/responses defined. But this is something that it is managed automatically by Arquillian Algeron Pact.

You can see full example at: ftest-incontainer

The only difference between previous example is that you only need arquillian-junit-standalone instead of arquilian-junit-container and don’t need to define any container adapter. Obviously no @Deployment method is required:

You can see full example at: ftest

You can enrich your test with current consumer and current request/response interaction by using @CurrentConsumer and CurrentInteraction annotations.

Arquillian Algeron Pact Provider can be configured using Arquillian configuration mechanism (arquillian.xml file or system properties).

The attributes are:

Notice that in case of using incontainer tests you don’t need to configure any of these parameters (except if insecure is required) since you can use the URL injected by Arquillian. See this at provider in container example.

Each interaction in a pact should be verified in isolation, with no context maintained from the previous interactions. Provider states allow you to set up data on the provider by injecting it straight into the datasource before the interaction is run, so that it can make a response that matches what the consumer expects.

Provider states also allow the consumer to make the same request with different expected responses.

Provider state is all about the state of the provider, not about the state of the consumer, or about what is in the request.

In consumer side you set an state using given section.

For example:

builder.given("test state")…​ sets state as plain String.

Or in case you want to set some parameters you can do:

which in this case sets an state name with some key/value pairs.

But in Arquillian Algeron Pact Provider we also give support for states in the form of Cucumber expression. You can define an state with the form:

builder.given("I have 36 cukes in my belly")…​

So the next question is how can I respond to states in provider side? Let’s see an example in each case:

In first example you only set a state with a name, without any parameter, so in your provider side you are going to do:

This method is executed if and only if given interaction has defined the state test state.

Obviously in previous example you have no way to pass parameters from consumer to provider. In second example you are passing a map with some parameters. To recover them you need to add as method parameter a Map.

This method is executed if and only if given interaction has defined the state test state and injects the defined parameters in consumer as method parameter.

Also the third case uses Cucumber-lik expression, so you need similar way to take parameters.

Notice that now as happens with Cucumber you need to specify the regular expression and you get the values as method parameters. Native values and list are supported. Lists are set in consumer side as comma-separated values and scanned as \\s+.

Arquillian Algeron Pact Provider implements custom matcher of AssertJ for validating contracts against provider.

First thing to do to use AssertJ matcher is add arquillian-algeron-pact-provider-assertj dependency, and the AssertJ you want to use.

Finally in your test you can use the overloaded assertThat static method receiving a Target type.

Notice that now instead of writing target.testInteraction(webapp); you are using a more readable way of asserting test.

Currently pact generates report from contract tests in several formats, including Markdown or JSON. You can also report using Arquillian Recorder Reporter (https://github.com/arquillian/arquillian-recorder) extension.

To use it you need to annotate at test class level with VerificationReports and set type to recorder and add Arquillian Recorder Reporter dependency org.arquillian.extension:arquillian-recorder-reporter-impl:<version>.

Forge Arquillian Addon offers an integration with Arquillian Algeron Provider.

To use it apart from having the Forge Arquillian Addon installed in Forge, you need to have arquillian dependencies registered on build tool.

To register Arquillian Provider dependencies in build tool just run next command:

arquillian-algeron-setup-provider --contracts-library pact

After that you can enrich a given Arquillian test with provider annotations:

arquillian-algeron-create-provider-test --provider myprovider --test-class org.superbiz.MyContractTest

It is important to note that test class should be already created (for example using arquillian-create-test --named MyContractTest --target-package org.superbiz command).

See it alive in next terminal cast: