Download the PHP package pact-foundation/pact-php without Composer

Pact PHP

Fast, easy and reliable testing for your APIs and microservices.

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.

• ⚡ Lightning fast
• 🎈 Effortless full-stack integration testing - from the front-end to the back-end
• 🔌 Supports HTTP/REST and event-driven systems
• 🛠️ Configurable mock server
• 😌 Powerful matching rules prevents brittle tests
• 🤝 Integrates with Pact Broker / PactFlow for powerful CI/CD workflows
• 🔡 Supports 12+ languages

Why use Pact?

Contract testing with Pact lets you:

• ⚡ Test locally
• 🚀 Deploy faster
• ⬇️ Reduce the lead time for change
• 💰 Reduce the cost of API integration testing
• 💥 Prevent breaking changes
• 🔎 Understand your system usage
• 📃 Document your APIs for free
• 🗄 Remove the need for complex data fixtures
• 🤷‍♂️ Reduce the reliance on complex test environments

Watch our series on the problems with end-to-end integrated tests, and how contract testing can help.

Table of contents

• Versions
• Supported Platforms
• Installation
• Basic Consumer Usage
  • Create Consumer Unit Test
  • Create Mock Request
  • Create Mock Response
  • Build the Interaction
  • Make the Request
  • Verify Interactions
  • Make Assertions
  • Delete Old Pact
  • Publish Contracts To Pact Broker
    • CLI
    • Github Actions
• Basic Provider Usage
  • Create Unit Test
  • Verification Sources
    • Verify From Pact Broker
    • Verify From Url
    • Verify Files in Directory
    • Verify Files by Path
  • Start API
• Tips
  • Starting API Asynchronously
  • Set Up Provider State
• Message support
  • Consumer Side Message Processing
  • Provider Side Message Validation
• Usage for the optional pact-stub-service

Versions

* v3 support is limited to the subset of functionality required to enable language inter-operable Message support.

 Supported Platforms

Installation

Install the latest version with:

Composer hosts older versions under mattersight/phppact, which is abandoned. Please convert to the new package name.

Basic Consumer Usage

All of the following code will be used exclusively for the Consumer.

Create Consumer Unit Test

Create a standard PHPUnit test case class and function.

Click here to see the full sample file.

Create Mock Request

This will define what the expected request coming from your http service will look like.

You can also create a body just like you will see in the provider example.

Create Mock Response

This will define what the response from the provider should look like.

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.

Build the Interaction

Now that we have the request and response, we need to build the interaction and ship it over to the mock server.

Make the Request

Verify Interactions

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.

Make Assertions

Verify that the data you would expect given the response configured is correct.

Delete Old Pact

If the value of PACT_FILE_WRITE_MODE is merge, before running the test, we need to delete the old pact manually:

Publish Contracts To Pact Broker

When all tests in test suite are passed, you may want to publish generated contract files to pact broker.

CLI

Run this command using CLI tool:

See more at https://docs.pact.io/pact_broker/publishing_and_retrieving_pacts#publish-using-cli-tools

Github Actions

See how to use at https://github.com/pactflow/actions/tree/main/publish-pact-files

Basic Provider Usage

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 Unit Test

Create a single unit test function. This will test all defined consumers of the service.

Verification Sources

There are four ways to verify Pact files. See the examples below.

Verify From Pact Broker

This will grab the Pact files from a Pact Broker.

Verify From Url

This will grab the Pact file from a url.

Verify Files in Directory

This will grab local Pact files in directory. Results will not be published.

Verify Files by Path

This will grab local Pact file. Results will not be published.

Start API

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.

Tips

Starting API Asynchronously

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.

PHP Server

Symfony Process

Set Up Provider State

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:

1. Write the posted state to a file and use a factory to decide which mock repository class to use based on the state.
2. Set up your database to meet the expectations of the request. At the start of each request, you should first reset the database to its original state.

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.

Message support

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.

Consumer Side Message Processing

The examples provided are pretty basic. See example.

1. Create the content and metadata (array)
2. Annotate the MessageBuilder appropriate content and states
   1. Given = Provider State
   2. expectsToReceive = Description
3. Set the callback you want to run when a message is provided
   1. The callback must accept a JSON string as a parameter
4. Run Verify. If nothing blows up, #winning.

Provider Side Message Validation

Handle these requests on your provider:

1. POST /pact-change-state
   1. Set up your database to meet the expectations of the request
   2. Reset the database to its original state.
2. POST /pact-messages
   1. Return message's content in body
   2. Return message's metadata in header PACT-MESSAGE-METADATA

Click here to see the full sample file.

Usage for the optional pact-stub-service

If you would like to test with fixtures, you can use the pact-stub-service like this: