Getting Started with PactFlow On-Premises

Tip

PactFlow On-Premises makes it easy for many developers and testers to test and deploy microservices.

Using 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.

Prerequisites

Go to PactFlow On-Premises Architecture to check the prerequisites needed to get started with PactFlow On-Premises.

Learn about contract testing

Videos

To learn more about contract testing, watch the introductory-level video series on contract-testing for better understanding.

Workshops

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

Then, enroll in PactFlow On-Premises University to learn more about 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:

Getting help

Here are some ways you can get extra support and have your questions answered:

Pact Slack

We have a Slack workspace where you can chat with other community members and get general support with contract testing or PactFlow On-Premises. Join us by registering here.

Please ask PactFlow On-Premises specific questions in one of the #pactflow channels below (maintained by SmartBear employees), and direct language specific questions to their respective channel such as #pact-jvm for Java or JVM related questions (maintained by the community).

For PactFlow On-Premises specific questions, see the following channels:

Getting Started with PactFlow On-Premises

Join a contract testing and PactFlow On-Premises expert for a monthly one hour drop-in session to learn the basics of contract testing with PactFlow On-Premises and have your questions answered. See the next upcoming session and register to attend.

Stack Overflow

Stack Overflow is another place you can search for support, the following link will show all questions tagged with pact.

SmartBear customer care and solutions engineers

If you need PactFlow On-Premises specific technical support, contact us or for help with a PoC or plan options get in touch with sales.

Migrating from Pact Broker

When you sign up to the SaaS PactFlow On-Premises platform, we create a new hosted database for you. However, if you previously used the open-source Pact Broker for your contract testing needs we migrate the data so that nothing is lost. The process involves:

  1. Moving your existing database to the hosted environment associated with your PactFlow On-Premises account.

  2. Updating it for full compatibility with PactFlow On-Premises. This requires some scheduled down time for the service, including contract publishing and 'can-i-deploy' webhook.

To get started with migrating from Pact Broker contact us with the subject 'migrating from Pact Broker'.

Note

Applies to SaaS (Hosted) PactFlow On-Premises accounts only.

If you want to migrate from On-Premises to the SaaS platform, check out our on-prem migration guide here.

Configuring your API token

Note

You cannot use your username and password to access the PactFlow On-Premises API.

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

Open your PactFlow On-Premises 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).

Then you can see the API Tokens page with two tokens listed - a read-only token and a read/write token.

api-tokens.png

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 (for example, a Jenkins build secret or a Travis encrypted environment variable).

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

Consumer

Pact JS (Node JS)

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 / JUnit 5

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

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

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

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

Docker

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

Pact JS (Node JS)

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 / JUnit 5

@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

@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

// 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

_, 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

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

.NET

PactNet documentation for all the pact 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

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. See the table here.

In this section:
© 2025
Publication date: