Getting Started with Pactflow

did you know

Pactflow makes testing and deploying microservices at scale, simple and worry free for thousands of developers and testers around the world.

Utilising the Pact framework, create consumer and provider mocks in-platform or use a range of BYO tools to do so through the Bi-Directional Contract Testing feature

Create an account

If you don’t already have a Pactflow account (have not created one or have not been invited to someone else’s account) get started with our free Starter Plan

Learn about contract testing

Videos

New to contract testing? Watch this introductory level video series on contract-testing to understand what it's all about.

Workshops

See contract testing in action by completing short and easy in-browser tutorials.

And when you’re ready to dive deeper, enroll in Pactflow University to dive deeper into the basics of contract testing through to advanced use cases including a CI/CD integration to help you scale

Essential reading

Here are some key resources to help you on your way:

• How Pact works
• Bi-Directional Contracts Guide
• The Pact Broker overview
• Versioning in the Pact Broker
• General Pact documentation
• You can find documentation on all the Pactflow screens under Pactflow User Interface.

Getting help

We also have a Slack workspace where you can chat with other members and get general support with contract or the product. Join us by registering here.

Stack Overflow is another place you can search for support.

• slack.pact.io
• https://stackoverflow.com/questions/tagged/pact

And, if you need Pactflow specific technical support, email support@pactflow.io or for help with a PoC or plan options get in touch with sales.

Configuring your API token

NOTE: You cannot use your username and password to access the Pactflow API.

To publish or verify contracts you need to use one of the bearer tokens from the API Tokens section of your Pactflow settings page.

Open your Pactflow account in a browser and log in with your username and password. Click on the settings icon (the cog wheel icon at the top right of the screen).

You will see the API Tokens page with two tokens listed - a read only token, and a read/write token.

Contracts and verification results are generally only published from a CI machine, so use the read only token on a local development machine, and keep the read/write token for CI.

While each of the following examples shows the use of a hardcoded token, note that you would normally be accessing the token via an environment variable or build parameter that is stored and provided in a secure manner (eg. a Jenkins build secret or a Travis encrypted environment variable).

To configure the token, click on a tab for your chosen language:

Consumer

JavaScript

Pact JS (Node JS)

• Pact-JS documentation for all the pact publication options.

const { Publisher } = require("@pact-foundation/pact")
const opts = {
pactBroker: 'https://<YOUR_BROKER>.pactflow.io',
pactBrokerToken: '<TOKEN>',
consumerVersion: process.env.GIT_COMMIT
pactFilesOrDirs: ['./pacts'],
};

new Publisher(opts).publishPacts()

Java

Java / JUnit 5

• Pact-JVM documentation for all the pact publication options.

pact {
  publish {
    providerVersion = {  '<GIT_COMMIT>' } //yes, this field name is correct :(
    pactBrokerUrl = 'https://<YOUR_BROKER>.pactflow.io/'
    pactBrokerToken = '<TOKEN>'
  }
}

Java / JUnit 4

pact {
  publish {
    providerVersion = {  '<GIT_COMMIT>' } //yes, this field name is correct :(
    pactBrokerUrl = 'https://<YOUR_BROKER>.pactflow.io/'
    pactBrokerToken = '<TOKEN>'
  }
}

Java / Gradle

pact {
  publish {
    providerVersion = {  '<GIT_COMMIT>' } //yes, this field name is correct :(
    pactBrokerUrl = 'https://<YOUR_BROKER>.pactflow.io/'
    pactBrokerToken = '<TOKEN>'
  }
}

Golang

Golang

p := dsl.Publisher{}
err := p.Publish(types.PublishRequest{
  PactURLs:        []string{"/path/to/pact/file"},
  PactBroker:      "https://<YOUR_BROKER>.pactflow.io",
  ConsumerVersion: "<GIT_COMMIT>",
  BrokerToken:     "<TOKEN>",
})

Ruby

Ruby

• Pact Ruby documentation for all the pact publishing options.

Rakefile

require 'pact_broker/client/tasks'

PactBroker::Client::PublicationTask.new do | task |
task.consumer_version = ENV['GIT_COMMIT']
task.pact_broker_base_url = "https://<YOUR_BROKER>.pactflow.io"
task.pact_broker_token = "<TOKEN>"
end

.NET

.NET

• PactNet documentation for all the pact publishing options.

Pact Publisher options

var pactPublisher = new PactPublisher("http://<YOUR_BROKER>.pactflow.io",
  new PactUriOptions("<TOKEN>"));
pactPublisher.PublishToBroker("/pact/to/pacts/dir",
  Environment.GetEnvironmentVariable("GIT_COMMIT"));

Docker

Docker

• Pact CLI Docker documentation for all the pact publishing options.

docker run --rm \
-v ${PWD}:${PWD} \
-e PACT_BROKER_BASE_URL="https://<YOUR_BROKER>.pactflow.io" \
-e PACT_BROKER_TOKEN="<TOKEN>" \
pactfoundation/pact-cli:latest \
publish \
${PWD}/pacts \
--consumer-app-version ${GIT_COMMIT}

Provider

JavaScript

Pact JS (Node JS)

• Pact-JS documentation for all the pact verification options.

const { Verifier } = require("@pact-foundation/pact");

return new Verifier().verifyProvider({
  provider: "<Your provider name here>",
  providerBaseUrl: "http://localhost:8081",

  // Fetch pacts from broker
  pactBrokerUrl: "https://<YOUR_BROKER>.pactflow.io/",
  pactBrokerToken: "<TOKEN>",

  publishVerificationResult: process.env.CI === "true",
  providerVersion: process.env.GIT_COMMIT,
});

Java

Java / JUnit 5

• Pact-JVM documentation for all the pact verification options.

@Provider("<Your provider name here>")
@PactBroker(host = "<YOUR_BROKER>.pactflow.io", scheme = "https",
  authentication = @PactBrokerAuth(scheme = "bearer", username = "<TOKEN>", password = ""))
public class PactJUnitBrokerTest {

    @TestTemplate
    @ExtendWith(PactVerificationInvocationContextProvider.class)
    void testTemplate(Pact pact, Interaction interaction, HttpRequest request, PactVerificationContext context) {
      context.verifyInteraction();
    }
}

Java / JUnit 4

• Pact-JVM documentation for all the pact verification options.

@RunWith(PactRunner.class)
@Provider("<Your provider name here>")
@PactBroker(host = "<YOUR_BROKER>.pactflow.io", scheme = "https",
  authentication = @PactBrokerAuth(scheme = "bearer", username = "<TOKEN>", password = ""))
public class PactJUnitBrokerTest {
  @TestTarget
  public final Target target = new HttpTarget(8080);
}

Java / Gradle

• Pact-JVM documentation for all the pact verification options.

// To turn on the verification publishing,
// set the project property `pact.verifier.publishResults` to `true`

pact {
  serviceProviders {
    '<Your provider name here>' {

      providerVersion = { '<GIT_COMMIT>' }
      hasPactsFromPactBroker('https://<YOUR_BROKER>.pactflow.io/',
        authentication: ['Bearer', '<TOKEN>'])

    }
  }
}

Golang

Golang

_, err := pact.VerifyProvider(t, types.VerifyRequest{
  ProviderBaseURL:            fmt.Sprintf("http://127.0.0.1:%d", port),
  BrokerURL:                  "https://<YOUR_BROKER>.pactflow.io",
  BrokerToken:                "<TOKEN>",
  PublishVerificationResults: true,
  ProviderVersion:            "<GIT_COMMIT>"
})

Ruby

Ruby

• Pact Ruby documentation for all the verification options.

spec/pact_helper.rb

Pact.service_provider "<Your provider name here>" do
  app_version ENV['GIT_COMMIT']
  publish_verification_results ENV['CI'] == 'true'

  honours_pacts_from_pact_broker do
    pact_broker_base_url "https://<YOUR_BROKER>.pactflow.io", { token: "<TOKEN>" }
  end
end

C++

.NET

PactNet documentation for all the pact verification options.

Provider verification options

var ProviderVersion = Environment.GetEnvironmentVariable("GIT_COMMIT");
var PublishVerificationResults = "true".Equals(Environment.GetEnvironmentVariable("CI"));
var config = new PactVerifierConfig
{
    ProviderVersion, //NOTE: Setting a provider version is required for publishing verification results
    PublishVerificationResults
};
IPactVerifier pactVerifier = new PactVerifier(config);
pactVerifier
    .ServiceProvider("<Your provider name here>", "http://your-test-provider-url")
   .PactBroker("https://<YOUR_BROKER>.pactflow.io", uriOptions: new PactUriOptions("<TOKEN>"))
   .Verify();

Docker

Docker

docker-compose-verify.yml

version: "3"

services:
  api:
    image: "your image"
    expose:
      - "9292"

  pact_verifier:
    image: pactfoundation/pact-cli:latest
    depends_on:
      - api
    environment:
      - PACT_BROKER_BASE_URL="https://<YOUR_BROKER>.pactflow.io"
      - PACT_BROKER_TOKEN="<TOKEN>"
    command: >
      verify
      --provider-base-url http://api:9292
      --provider "<Your provider name here>"

To run

docker-compose -f docker-compose-verify.yml up \
    --build --abort-on-container-exit --exit-code-from pact_verifier

Supported Tools & Languages

Pact is available in many different implementations, Click on a language icon to take you to the implementation guide or readme.

The guides cover the consumer-driven contract testing flow.

Consumer-Driven

Pact Language implementation guide for JavaScript

Demo applications:

React JavaScript Website tested using Pact to generate consumer pacts

React JavaScript Website tested using Cypress to generate consumer pacts

ExpressJS API provider tested with Pact Verifier

ExpressJS AWS Lambda SNS Provider tested with Pact Verifier

Pact Language implementation guide for Java

Demo applications:

Java SOAP API provider tested with Pact Verifier

Java Kafka message provider tested with Pact Verifier

Java Spring Boot API provider tested with Pact Verifier

Java Junit API Consumer tested using Pact to generate consumer pacts

Java SOAP API Consumer tested using Pact to generate consumer pacts

Java Kafka Consumer tested using Pact to generate consumer pacts

Pact Language implementation guide for Golang

Demo applications:

Golang Gin API Provider tested with Pact Verifier

Golang API Consumer tested using Pact to generate consumer pacts

Pact Language implementation guide for Ruby

Demo applications:

Pact Language implementation guide for .NET

Demo applications:

.NET API Provider tested with Pact Verifier

.NET (v3.x.x) API Consumer tested using Pact to generate consumer pacts

.NET (v4.x.x) API Consumer tested using Pact to generate consumer pacts

Pact Language implementation guide for Docker

Demo applications:

Pact Language implementation guide for Kotlin

Demo applications:

Pact Language implementation guide for Scala

Demo applications:

Pact Language implementation guide for Clojure

Demo applications:

Pact Language implementation guide for Python

Demo applications:

Python API Provider tested with Pact Verifier

Python API Consumer tested using Pact to generate consumer pacts

Pact Language implementation guide for Swift and Objective-C

Demo applications:

Pact Language implementation guide for PHP

Demo applications:

Pact Language implementation guide for C++

Demo applications:

Bi-Directional

Pactflow supports many different testing tools for Bi-Directional Contract Testing.

Click on a testing tool icon to see a demo application you can quickly run to get you started

Consumer Side

Pactflow consumer side demo with Cypress

Pactflow consumer side demo with Wiremock

Pactflow consumer side demo with Nock

Pactflow consumer side demo with Mountebank

Pactflow consumer side demo with Pact

Pactflow consumer side demo with Mock Service Worker

Provider side

Pactflow provider side demo with Postman

Pactflow provider side demo with REST-assured

Pactflow provider side demo with Dredd

Pactflow provider side demo with Schemathesis