PHP version of Pact. Enables consumer driven contract testing, providing a mock service and DSL for the consumer project, and interaction playback and verification for the service provider project
Pact is the de-facto API contract testing tool. Replace expensive and brittle end-to-end integration tests with fast, reliable and easy to debug unit tests.
Why use Pact?
Contract testing with Pact lets you:
Watch our series on the problems with end-to-end integrated tests, and how contract testing can help.
pact-stub-service
Version | Status | Spec Compatibility | PHP Compatibility | Install |
---|---|---|---|---|
10.x | Alpha | 1, 1.1, 2, 3, 4 | ^8.1 | See installation |
9.x | Stable | 1, 1.1, 2, 3* | ^8.0 | 9xx |
8.x | Deprecated | 1, 1.1, 2, 3* | ^7.4 | ^8.0 |
7.x | Deprecated | 1, 1.1, 2, 3* | ^7.3 | |
6.x | Deprecated | 1, 1.1, 2, 3* | ^7.2 | |
5.x | Deprecated | 1, 1.1, 2, 3* | ^7.1 | |
4.x | Deprecated | 1, 1.1, 2 | ^7.1 | |
3.x | Deprecated | 1, 1.1, 2 | ^7.0 | |
2.x | Deprecated | 1, 1.1, 2 | >=7 | |
1.x | Deprecated | 1, 1.1 | >=7 |
* v3 support is limited to the subset of functionality required to enable language inter-operable Message support.
OS | Architecture | Supported | Pact-PHP Version |
---|---|---|---|
OSX | x86_64 | β | All |
Linux | x86_64 | β | All |
OSX | arm64 | β | 9.x + |
Linux | arm64 | β | 9.x + |
Windows | x86_64 | β | All |
Windows | x86 | β | All |
Install the latest version with:
$ composer require pact-foundation/pact-php --dev
Composer hosts older versions under mattersight/phppact
, which is abandoned. Please convert to the new package name.
All of the following code will be used exclusively for the Consumer.
Create a standard PHPUnit test case class and function.
Click here to see the full sample file.
This will define what the expected request coming from your http service will look like.
$request = new ConsumerRequest();
$request
->setMethod('GET')
->setPath('/hello/Bob')
->addHeader('Content-Type', 'application/json');
You can also create a body just like you will see in the provider example.
This will define what the response from the provider should look like.
$matcher = new Matcher();
$response = new ProviderResponse();
$response
->setStatus(200)
->addHeader('Content-Type', 'application/json')
->setBody([
'message' => $matcher->regex('Hello, Bob', '(Hello, )[A-Za-z]')
]);
In this example, we are using matchers. This allows us to add flexible rules when matching the expectation with the actual value. In the example, you will see regex is used to validate that the response is valid.
$matcher = new Matcher();
$response = new ProviderResponse();
$response
->setStatus(200)
->addHeader('Content-Type', 'application/json')
->setBody([
'list' => $matcher->eachLike([
'firstName' => 'Bob',
'age' => 22
])
]);
Matcher | Explanation | Parameters | Example |
---|---|---|---|
term | Match a value against a regex pattern. | Value, Regex Pattern | $matcher->term('Hello, Bob', '(Hello, )[A-Za-z]') |
regex | Alias to term matcher. | Value, Regex Pattern | $matcher->regex('Hello, Bob', '(Hello, )[A-Za-z]') |
dateISO8601 | Regex match a date using the ISO8601 format. | Value (Defaults to 2010-01-01) | $matcher->dateISO8601('2010-01-01') |
timeISO8601 | Regex match a time using the ISO8601 format. | Value (Defaults to T22:44:30.652Z) | $matcher->timeISO8601('T22:44:30.652Z') |
dateTimeISO8601 | Regex match a datetime using the ISO8601 format. | Value (Defaults to 2015-08-06T16:53:10+01:00) | $matcher->dateTimeISO8601('2015-08-06T16:53:10+01:00') |
dateTimeWithMillisISO8601 | Regex match a datetime with millis using the ISO8601 format. | Value (Defaults to 2015-08-06T16:53:10.123+01:00) | $matcher->dateTimeWithMillisISO8601('2015-08-06T16:53:10.123+01:00') |
timestampRFC3339 | Regex match a timestamp using the RFC3339 format. | Value (Defaults to Mon, 31 Oct 2016 15:21:41 -0400) | $matcher->timestampRFC3339('Mon, 31 Oct 2016 15:21:41 -0400') |
like | Match a value against its data type. | Value | $matcher->like(12) |
somethingLike | Alias to like matcher. | Value | $matcher->somethingLike(12) |
eachLike | Match on an object like the example. | Value, Min (Defaults to 1) | $matcher->eachLike(12) |
constrainedArrayLike | Behaves like the eachLike matcher, but also applies a minimum and maximum length validation on the length of the array. The optional count parameter controls the number of examples generated. |
Value, Min, Max, count (Defaults to null) | $matcher->constrainedArrayLike('test', 1, 5, 3) |
boolean | Match against boolean true. | none | $matcher->boolean() |
integer | Match a value against integer. | Value (Defaults to 13) | $matcher->integer() |
decimal | Match a value against float. | Value (Defaults to 13.01) | $matcher->decimal() |
hexadecimal | Regex to match a hexadecimal number. Example: 3F | Value (Defaults to 3F) | $matcher->hexadecimal('FF') |
uuid | Regex to match a uuid. | Value (Defaults to ce118b6e-d8e1-11e7-9296-cec278b6b50a) | $matcher->uuid('ce118b6e-d8e1-11e7-9296-cec278b6b50a') |
ipv4Address | Regex to match a ipv4 address. | Value (Defaults to 127.0.0.13) | $matcher->ipv4Address('127.0.0.1') |
ipv6Address | Regex to match a ipv6 address. | Value (Defaults to ::ffff:192.0.2.128) | $matcher->ipv6Address('::ffff:192.0.2.1') |
Regex to match an address. | Value ([email protected]) | $matcher->email('[email protected]') |
Now that we have the request and response, we need to build the interaction and ship it over to the mock server.
// Create a configuration that reflects the server that was started. You can
// create a custom MockServerConfigInterface if needed. This configuration
// is the same that is used via the PactTestListener and uses environment variables.
$config = new MockServerEnvConfig();
$builder = new InteractionBuilder($config);
$builder
->given('a person exists', ['name' => 'Bob'])
->uponReceiving('a get request to /hello/{name}')
->with($request)
->willRespondWith($response); // This has to be last. This is what makes FFI calls to register the interaction and start the mock server.
$service = new HttpClientService($config->getBaseUri()); // Pass in the URL to the Mock Server.
$result = $service->getHelloString('Bob'); // Make the real API request against the Mock Server.
Verify that all interactions took place that were registered. This typically should be in each test, that way the test that failed to verify is marked correctly.
$verifyResult = $builder->verify();
$this->assertTrue($verifyResult);
Verify that the data you would expect given the response configured is correct.
$this->assertEquals('Hello, Bob', $result); // Make your assertions.
If the value of PACT_FILE_WRITE_MODE
is merge
, before running the test, we need to delete the old pact manually:
rm /path/to/pacts/consumer-provider.json
When all tests in test suite are passed, you may want to publish generated contract files to pact broker.
Run this command using CLI tool:
pact-broker publish /path/to/pacts/consumer-provider.json --consumer-app-version 1.0.0 --branch main --broker-base-url https://test.pactflow.io --broker-token SomeToken
See more at https://docs.pact.io/pact_broker/publishing_and_retrieving_pacts#publish-using-cli-tools
See how to use at https://github.com/pactflow/actions/tree/main/publish-pact-files
All of the following code will be used exclusively for Providers. This will run the Pacts against the real Provider and either verify or fail validation on the Pact Broker.
Create a single unit test function. This will test all defined consumers of the service.
protected function setUp(): void
{
// Start API
}
protected function tearDown(): void
{
// Stop API
}
public function testPactVerifyConsumers(): void
{
$config = new VerifierConfig();
$config->getProviderInfo()
->setName('someProvider')
->setHost('localhost')
->setPort(8000);
$config->getProviderState()
->setStateChangeUrl(new Uri('http://localhost:8000/pact-change-state'))
->setStateChangeTeardown(true)
->setStateChangeAsBody(true);
// If your provider dispatch messages
$config->addProviderTransport(
(new ProviderTransport())
->setProtocol(ProviderTransport::MESSAGE_PROTOCOL)
->setPort(8000)
->setPath('/pact-messages')
->setScheme('http')
);
// If you want to publish verification results to Pact Broker.
if ($isCi = getenv('CI')) {
$publishOptions = new PublishOptions();
$publishOptions
->setProviderVersion(exec('git rev-parse --short HEAD'))
->setProviderBranch(exec('git rev-parse --abbrev-ref HEAD'));
$config->setPublishOptions($publishOptions);
}
// If you want to display more/less verification logs.
if ($logLevel = \getenv('PACT_LOGLEVEL')) {
$config->setLogLevel($logLevel);
}
// Add sources ...
$verifyResult = $verifier->verify();
$this->assertTrue($verifyResult);
}
There are four ways to verify Pact files. See the examples below.
This will grab the Pact files from a Pact Broker.
$selectors = (new ConsumerVersionSelectors())
->addSelector(new Selector(mainBranch: true))
->addSelector(new Selector(deployedOrReleased: true));
$broker = new Broker();
$broker
->setUrl(new Uri('http://localhost'))
->setUsername('user')
->setPassword('pass')
->setToken('token')
->setEnablePending(true)
->setIncludeWipPactSince('2020-01-30')
->setProviderTags(['prod'])
->setProviderBranch('main')
->setConsumerVersionSelectors($selectors)
->setConsumerVersionTags(['dev']);
$verifier->addBroker($broker);
This will grab the Pact file from a url.
$url = new Url();
$url
->setUrl(new Uri('http://localhost:9292/pacts/provider/personProvider/consumer/personConsumer/latest'))
->setUsername('user')
->setPassword('pass')
->setToken('token');
$verifier->addUrl($url);
This will grab local Pact files in directory. Results will not be published.
$verifier->addDirectory('C:\SomePath');
This will grab local Pact file. Results will not be published.
$verifier->addFile('C:\SomePath\consumer-provider.json');
Get an instance of the API up and running. Click here for some tips.
If you need to set up the state of your API before making each request please see Set Up Provider State.
You can use the built in PHP server to accomplish this during your tests setUp function. The Symfony Process library can be used to run the process asynchronous.
The PACT verifier is a wrapper of the Ruby Standalone Verifier. See API with Provider States for more information on how this works. Since most PHP rest APIs are stateless, this required some thought.
Here are some options:
No matter which direction you go, you will have to modify something outside of the PHP process because each request to your server will be stateless and independent.
The goal is not to test the transmission of an object over a bus but instead vet the contents of the message. While examples included focus on a Rabbit MQ, the exact message queue is irrelevant. Initial comparisons require a certain object type to be created by the Publisher/Producer and the Consumer of the message. This includes a metadata set where you can store the key, queue, exchange, etc that the Publisher and Consumer agree on. The content format needs to be JSON.
To take advantage of the existing pact-verification tools, the provider side of the equation stands up an http proxy to callback to processing class. Aside from changing default ports, this should be transparent to the users of the libary.
Both the provider and consumer side make heavy use of lambda functions.
The examples provided are pretty basic. See example.
$builder = new MessageBuilder(self::$config);
$contents = new \stdClass();
$contents->song = 'And the wind whispers Mary';
$metadata = ['queue'=>'And the clowns have all gone to bed', 'routing_key'=>'And the clowns have all gone to bed'];
$builder
->given('You can hear happiness staggering on down the street')
->expectsToReceive('footprints dressed in red')
->withMetadata($metadata)
->withContent($contents);
// established mechanism to this via callbacks
$consumerMessage = new ExampleMessageConsumer();
$callback = [$consumerMessage, 'ProcessSong'];
$builder->setCallback($callback);
$verifyResult = $builder->verify();
$this->assertTrue($verifyResult);
Handle these requests on your provider:
PACT-MESSAGE-METADATA
Click here to see the full sample file.
pact-stub-service
If you would like to test with fixtures, you can use the pact-stub-service
like this:
$files = [__DIR__ . '/someconsumer-someprovider.json'];
$port = 7201;
$endpoint = 'test';
$config = (new StubServerConfig())
->setFiles($files)
->setPort($port);
$stubServer = new StubServer($config);
$stubServer->start();
$client = new \GuzzleHttp\Client();
$response = $client->get($this->config->getBaseUri() . '/' . $endpoint);
echo $response->getBody(); // output: {"results":[{"name":"Games"}]}