Skip to main content


JUnit 5 support for Pact consumer tests


The library is available on maven central using:

  • group-id =
  • artifact-id = junit5
  • version-id = 4.2.X


1. Add the Pact consumer test extension to the test class.#

To write Pact consumer tests with JUnit 5, you need to add @ExtendWith(PactConsumerTestExt) to your test class. This replaces the PactRunner used for JUnit 4 tests. The rest of the test follows a similar pattern as for JUnit 4 tests.

class ExampleJavaConsumerPactTest {

2. create a method annotated with @Pact that returns the interactions for the test#

For each test (as with JUnit 4), you need to define a method annotated with the @Pact annotation that returns the interactions for the test.

@Pact(provider="ArticlesProvider", consumer="test_consumer")
public RequestResponsePact createPact(PactDslWithProvider builder) {
return builder
.given("test state")
.uponReceiving("ExampleJavaConsumerPactTest test interaction")
.body("{\"responsetest\": true}")

3. Link the mock server with the interactions for the test with @PactTestFor#

Then the final step is to use the @PactTestFor annotation to tell the Pact extension how to setup the Pact test. You can either put this annotation on the test class, or on the test method. For examples see ArticlesTest and MultiTest.

The @PactTestFor annotation allows you to control the mock server in the same way as the JUnit 4 PactProviderRule. It allows you to set the hostname to bind to (default is localhost) and the port (default is to use a random port). You can also set the Pact specification version to use (default is V3).

@PactTestFor(providerName = "ArticlesProvider")
public class ExampleJavaConsumerPactTest {

NOTE on the hostname: The mock server runs in the same JVM as the test, so the only valid values for hostname are:

localhostbinds to the address that localhost points to (normally the loopback adapter) or ::1binds to the loopback adapter
host namebinds to the default interface that the host machines DNS name resolves to or ::binds to the all interfaces on the host machine

Matching the interactions by provider name#

If you set the providerName on the @PactTestFor annotation, then the first method with a @Pact annotation with the same provider name will be used. See ArticlesTest for an example.

Matching the interactions by method name#

If you set the pactMethod on the @PactTestFor annotation, then the method with the provided name will be used (it still needs a @Pact annotation). See MultiTest for an example.

Injecting the mock server into the test#

You can get the mock server injected into the test method by adding a MockServer parameter to the test method.

void test(MockServer mockServer) throws IOException {
HttpResponse httpResponse = Request.Get(mockServer.getUrl() + "/articles.json").execute().returnResponse();
assertThat(httpResponse.getStatusLine().getStatusCode(), is(equalTo(200)));

This helps with getting the base URL of the mock server, especially when a random port is used.

Changing the directory pact files are written to#

By default, pact files are written to target/pacts (or build/pacts if you use Gradle), but this can be overwritten with the pact.rootDir system property. This property needs to be set on the test JVM as most build tools will fork a new JVM to run the tests.

For Gradle, add this to your build.gradle:

test {
systemProperties['pact.rootDir'] = "$buildDir/custom-pacts-directory"

For maven, use the systemPropertyVariables configuration:


For SBT:

fork in Test := true,
javaOptions in Test := Seq("-Dpact.rootDir=some/other/directory")

Using @PactDirectory annotation#

You can override the directory the pacts are written in a test by adding the @PactDirectory annotation to the test class.

Forcing pact files to be overwritten#

By default, when the pact file is written, it will be merged with any existing pact file. To force the file to be overwritten, set the Java system property pact.writer.overwrite to true.

Having values injected from provider state callbacks#

You can have values from the provider state callbacks be injected into most places (paths, query parameters, headers, bodies, etc.). This works by using the V3 spec generators with provider state callbacks that return values. One example of where this would be useful is API calls that require an ID which would be auto-generated by the database on the provider side, so there is no way to know what the ID would be beforehand.

The following DSL methods all you to set an expression that will be parsed with the values returned from the provider states:

For JSON bodies, use valueFromProviderState.
For headers, use headerFromProviderState.
For query parameters, use queryParameterFromProviderState.
For paths, use pathFromProviderState.

For example, assume that an API call is made to get the details of a user by ID. A provider state can be defined that specifies that the user must be exist, but the ID will be created when the user is created. So we can then define an expression for the path where the ID will be replaced with the value returned from the provider state callback.

.pathFromProviderState("/api/users/${id}", "/api/users/100")

You can also just use the key instead of an expression:

.valueFromProviderState('userId', 'userId', 100) // will look value using userId as the key

Overriding the expression markers ${ and } (4.1.25+)#

You can change the markers of the expressions using the following system properties:

  • pact.expressions.start (default is ${)
  • pact.expressions.end (default is })

Using HTTPS#

You can enable a HTTPS mock server by setting https=true on the @PactTestFor annotation. Note that this mock server will use a self-signed certificate, so any client code will need to accept self-signed certificates.

Using own KeyStore#

You can provide your own KeyStore file to be loaded on the MockServer. In order to do so you should fulfill the properties keyStorePath, keyStoreAlias, keyStorePassword, privateKeyPassword on the @PactTestFor annotation. Please bear in mind you should also enable HTTPS flag.

Using multiple providers in a test (4.2.5+)#

It is advisable to focus on a single interaction with each test, but you can enable multiple providers in a single test. In this case, a separate mock server will be started for each configured provider.

To enable this:

  1. Create a method to create the Pact for each provider annotated with the @Pact(provider = "....") annotation. The provider name must be set on the annotation. You can create as many of these as required, but each must have a unique provider name.
  2. In the test method, use the pactMethods attribute on the @PactTestFor annotation with the names of all the methods defined in step 1.
  3. Add a MockServer parameter to the test method for each provider configured in step 1 with a @ForProvider annotation with the name of the provider.
  4. In your test method, interact with each of the mock servers passed in step 3. Note that if any mock server does not get the requests it expects, it will fail the test.

For an example, see MultiProviderTest.

Dealing with persistent HTTP/1.1 connections (Keep Alive)#

As each test will get a new mock server, connections can not be persisted between tests. HTTP clients can cache connections with HTTP/1.1, and this can cause subsequent tests to fail. See #342 and #1383.

One option (if the HTTP client supports it, Apache HTTP Client does) is to set the system property http.keepAlive to false in the test JVM. The other option is to set pact.mockserver.addCloseHeader to true to force the mock server to send a Connection: close header with every response (supported with Pact-JVM 4.2.7+).

Message Pacts#

Consumer test for a message consumer#

For testing a consumer of messages from a message queue using JUnit 5 and Pact V4, see AsyncMessageTest.

Matching message metadata#

You can also use matching rules for the metadata associated with the message. There is a MetadataBuilder class to help with this. You can access it via the withMetadata method that takes a Java Consumer on the MessagePactBuilder class.

For example:

.expectsToReceive("a test message with metadata")
.withMetadata(md -> {
md.add("metadata1", "metadataValue1");
md.add("metadata2", "metadataValue2");
md.add("metadata3", 10L);
md.matchRegex("partitionKey", "[A-Z]{3}\\d{2}", "ABC01");
Last updated on by Github Action