# Pact junit runner ## Overview Library provides ability to play contract tests against provider service in JUnit fashionable way. Supports: - Out-of-the-box convenient ways to load pacts - Easy way to change assertion strategy - **org.junit.BeforeClass**, **org.junit.AfterClass** and **org.junit.ClassRule** JUnit annotations, that will be run once - before/after whole contract test suite - **org.junit.Before**, **org.junit.After** and **org.junit.Rule** JUnit annotations, that will be run before/after each test of interaction - **** custom annotation - before each interaction that require state change, all methods annotated by State with appropriate state listed will be invoked ## Example of test ```java @RunWith(PactRunner.class) // Say JUnit to run tests with custom Runner @Provider("myAwesomeService") // Set up name of tested provider @PactFolder("pacts") // Point where to find pacts (See also section Pacts source in documentation) public class ContractTest { // NOTE: this is just an example of embedded service that listens to requests, you should start here real service @ClassRule //Rule will be applied once: before/after whole contract test suite public static final ClientDriverRule embeddedService = new ClientDriverRule(8332); @BeforeClass //Method will be run once: before whole contract test suite public static void setUpService() { //Run DB, create schema //Run service //... } @Before //Method will be run before each test of interaction public void before() { // Rest data // Mock dependent service responses // ... embeddedService.addExpectation( onRequestTo("/data"), giveEmptyResponse() ); } @State("default", "no-data") // Method will be run before testing interactions that require "default" or "no-data" state public void toDefaultState() { // Prepare service before interaction that require "default" state // ... System.out.println("Now service in default state"); } @TestTarget // Annotation denotes Target that will be used for tests public final Target target = new HttpTarget(8332); // Out-of-the-box implementation of Target (for more information take a look at Test Target section) } ``` ## Pacts source Pact runner will automatically collect pacts: for this purpose there are 2 out-of-the-box options or you can easily add your own Pact source. **Note:** it's possible to use only one source of pacts. ### Download pacts from pact-broker To use pacts from Pact Broker annotate test class with `@PactBroker(host="", port = 80)`. ### Pact folder To use pacts from resource folder of project annotate test class with `@PactFolder("subfolder/in/resource/directory")`. ### Custom pacts source It's possible to use custom Pact source: for this implement `interface` and annotate test class with `@PactSource(MyOwnPactLoader.class)`. **Note:** `class MyOwnPactLoader` should have default constructor. ## Test target Field in test class of type `` annotated with `` will be used for actual Interaction execution and asserting of contract. **Note:** should be exactly 1 such field, otherwise `InitializationException` will be thrown. ### HttpTarget `` - out-of-the-box implementation of `` that will play pacts as http request and assert response from service by matching rules from pact. ### Custom Test Target It's possible to use custom `Target` for that `interface Target` should be implemented and this class can be used instead of `HttpTarget`.




Build Status Appveyor build status Maven Central

JVM implementation of the consumer driven contract library pact.

From the Ruby Pact website:

Define a pact between service consumers and providers, enabling "consumer driven contract" testing.

Pact provides an RSpec DSL for service consumers to define the HTTP requests they will make to a service provider and the HTTP responses they expect back. These expectations are used in the consumers specs to provide a mock service provider. The interactions are recorded, and played back in the service provider specs to ensure the service provider actually does provide the response the consumer expects.

This allows testing of both sides of an integration point using fast unit tests.

This gem is inspired by the concept of "Consumer driven contracts". See for more information.

Read Getting started with Pact for more information on how to get going.




Additional documentation can be found at, in the Pact Wiki, and in the Pact-JVM wiki. Stack Overflow is also a good source of help.

Supported JDK and specification versions:

Branch Specification JDK Scala Versions Latest Version
4.0.x V3 8-12 N/A 4.0.0-beta.3
3.6.x V3 8 2.12 3.6.10
3.5.x V3 8 2.12, 2.11 3.5.25
3.5.x-jre7 V3 7 2.11 3.5.7-jre7.0
2.4.x V2 6 2.10, 2.11 2.4.20

Service Consumers

Pact-JVM has a number of ways you can write your service consumer tests.

I Use Scala

You want to look at: scala-pact or pact-jvm-consumer-specs2

I Use Java

You want to look at: pact-jvm-consumer-junit for JUnit 4 tests and pact-jvm-consumer-junit5 for JUnit 5 tests. Also, if you are using Java 8, there is an updated DSL for consumer tests.

I Use Groovy or Grails

You want to look at: pact-jvm-consumer-groovy or pact-jvm-consumer-junit

(Use Clojure I)

Clojure can call out to Java, so have a look at pact-jvm-consumer-junit. For an example look at example_clojure_consumer_pact_test.clj.

I Use some other jvm language or test framework

You want to look at: Pact Consumer

My Consumer interacts with a Message Queue

As part of the V3 pact specification, we have defined a new pact file for interactions with message queues. For an implementation of a Groovy consumer test with a message pact, have a look at PactMessageBuilderSpec.groovy.

Service Providers

Once you have run your consumer tests, you will have generated some Pact files. You can then verify your service providers with these files.

I am writing a provider and want to ...

verify pacts with SBT

You want to look at: scala-pact or pact sbt plugin

verify pacts with Gradle

You want to look at: pact gradle plugin

verify pacts with Maven

You want to look at: pact maven plugin

verify pacts with JUnit tests

You want to look at: junit provider support for JUnit 4 tests and pact-jvm-provider-junit5 for JUnit 5 tests

verify pacts with Leiningen

You want to look at: pact leiningen plugin

verify pacts with Specs2

Have a look at pact-jvm-provider-specs2

verify pacts with a Spring MVC project

Have a look at pact-jvm-provider-specs2 or Spring MVC Pact Test Runner (Not maintained).

I want to verify pacts but don't want to use sbt or gradle or leiningen

You want to look at: pact-jvm-provider

verify interactions with a message queue

As part of the V3 pact specification, we have defined a new pact file for interactions with message queues. The Gradle pact plugin supports a mechanism where you can verify V3 message pacts, have a look at pact gradle plugin. The JUnit pact library also supports verification of V3 message pacts, have a look at pact-jvm-provider-junit.

I Use Ruby or Go or something else

The pact-jvm libraries are pure jvm technologies and do not have any native dependencies.

However if you have a ruby provider, the json produced by this library is compatible with the ruby pact library. You'll want to look at: Ruby Pact.

For .Net, there is Pact-net.

For JS, there is Pact-JS.

For Go, there is Pact-go.

Have a look at implementations in other languages.

I Use something completely different

There's a limit to how much we can help, however check out pact-jvm-server

How do I transport my pacts from consumers to providers?

You want to look at: Pact Broker

Which is a project that aims at providing tooling to coordinate pact generation and delivery between projects.

I want to contribute

Documentation for contributors is on the wiki.