Getting Started with Pactflow

Pactflow is a fully-managed, highly-available, and hardened deployment of the open source "Pact Broker" with a re-imagined user experience. It allows you to integrate Pact into your CI/CD pipelines by providing a central point for managing your consumer driven contracts.

Tutorials

To get you started, we have created a few short in-browser tutorials. If you're new to Pact, or want some help integrating to Pactflow, you should start here.

Essential reading

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

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

If you need general Pact support, we have a number of channels you can reach us on:

If you need Pactflow specific support, you can email us at support@pactflow.io.

Configuring your API token

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

To publish or verify pacts 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.

API Token Screen

Pacts 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:

Consumer

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()

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

Provider

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
});

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

Consumer

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

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

Provider

// 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>'])
}
}
}

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

Consumer

See the Gradle documentation.

Provider

@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();
}
}

Consumer

See the Gradle documentation.

Provider

@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);
}

Consumer

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>",
})

Provider

_, 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>"
})

Consumer

# In your 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

See the Pact Ruby documentation for all the pact publishing options.

Provider

# In your 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

See the Pact Ruby documentation for all the verification options.

Consumer

PowerShell
# Ensure TLS1.2 is set, otherwise it will default to TLS1.0 and you won't be able to connect
[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
$res = Invoke-WebRequest -Uri "https://<YOUR_BROKER>.pactflow.io/pacts/provider/AProvider/consumer/AConsumer/version/SomeVersion" -Method Put -InFile .\a_consumer-a_provider.json -ContentType "application/json" -Headers @{'Authorization' = 'Bearer <your token here>'}
C#
var pactPublisher = new PactPublisher("http://<YOUR_BROKER>.pactflow.io",
new PactUriOptions("<TOKEN>"));
pactPublisher.PublishToBroker("/pact/to/pacts/dir",
Environment.GetEnvironmentVariable("GIT_COMMIT"));

See the PactNet documentation for all the pact publishing options.

Provider

var config = new PactVerifierConfig
{
ProviderVersion = Environment.GetEnvironmentVariable("GIT_COMMIT")
PublishVerificationResults = "true".Equals(Environment.GetEnvironmentVariable("CI"))
};
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();

See the PactNet documentation for all the pact verification options.

Consumer

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}

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

Provider

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>"
docker-compose -f docker-compose-verify.yml up \
--build --abort-on-container-exit --exit-code-from pact_verifier