pact-foundation / pact-php
Enables consumer driven contract testing, following the PACT foundation principles.
Installs: 1 041 247
Dependents: 19
Suggesters: 0
Security: 0
Stars: 273
Watchers: 18
Forks: 92
Open Issues: 3
Requires
- php: ^8.1
- ext-ffi: *
- ext-json: *
- ext-openssl: *
- composer/semver: ^1.4.0|^3.2.0
- guzzlehttp/psr7: ^2.4.5
- pact-foundation/composer-downloads-plugin: ^2.1
- symfony/process: ^5.4|^6.0|^7.0
Requires (Dev)
- ext-sockets: *
- behat/behat: ^3.13
- clue/framework-x: ^0.16.0
- friendsofphp/php-cs-fixer: ^3.0
- galbar/jsonpath: ^3.0
- guzzlehttp/guzzle: ^7.8
- pact-foundation/example-protobuf-sync-message-provider: @dev
- php-amqplib/php-amqplib: ^3.0
- phpstan/phpstan: ^1.9
- phpunit/phpunit: ^10.1.0|^11.0
- ramsey/uuid: ^4.7
- rector/rector: ^1.2
- roave/security-advisories: dev-latest
- webonyx/graphql-php: ^15.14
- dev-master
- 10.1.0-beta1
- 10.0.0
- 10.0.0-beta2
- 10.0.0-beta1
- 10.0.0-alpha7
- 10.0.0-alpha6
- 10.0.0-alpha5
- 10.0.0-alpha4
- 10.0.0-alpha3
- 10.0.0-alpha2
- 10.0.0-alpha1
- 9.1.1
- 9.1.0
- 9.0.0
- 8.1.0
- 8.0.0
- 7.2.0
- 7.1.2
- 7.1.1
- 7.1.0
- 7.0.1
- 7.0.0
- 6.0.3
- 6.0.2
- 6.0.1
- 6.0.0
- 5.0.7
- 5.0.6
- 5.0.5
- 5.0.4
- 5.0.3
- 5.0.2
- 5.0.1
- 5.0.0
- 4.0.2
- 4.0.1
- 4.0.0
- 3.1.1
- 3.1.0
- 3.0.3
- 3.0.2
- 3.0.1
- 3.0.0
- 2.2.1
- 2.2.0
- 2.1.0
- 2.0.4
- 2.0.3
- 2.0.2
- 2.0.1
- 1.1.3
- 1.1.0
- 1.0.5
- 1.0.4
- 1.0.3
- 1.0.1
- dev-release/9.x
- dev-ubuntu-sockets
This package is auto-updated.
Last update: 2024-11-01 10:21:53 UTC
README
Pact PHP
Fast, easy and reliable testing for your APIs and microservices.
Documentation
This readme offers a basic introduction to the library. The full documentation for Pact PHP and the rest of the framework is available at https://docs.pact.io/.
- Installation
- Consumer Testing
- Provider Testing
- Event Driven Systems
- Examples
- Stub Server
- Framework Integrations
Need Help
- Join our community slack workspace.
- Stack Overflow: https://stackoverflow.com/questions/tagged/pact
- Say 👋 on Twitter: [@pact_up]
Installation
composer require pact-foundation/pact-php --dev
# 🚀 now write some tests!
Looking for the previous stable 9.x.x release?
Requirements
PHP 8.1+ as of pact-php v10
Do Not Track
In order to get better statistics as to who is using Pact, we have an anonymous tracking event that triggers when Pact installs for the first time. The only things we track are your type of OS, and the version information for the package being installed. No PII data is sent as part of this request. You can disable tracking by setting the environment variable PACT_DO_NOT_TRACK=true
:
Usage
Writing a Consumer test
namespace App\Tests; use App\Service\HttpClientService; use PhpPact\Consumer\InteractionBuilder; use PhpPact\Consumer\Matcher\Matcher; use PhpPact\Consumer\Model\ConsumerRequest; use PhpPact\Consumer\Model\ProviderResponse; use PhpPact\Standalone\MockService\MockServerConfig; use PHPUnit\Framework\TestCase; class ConsumerServiceHelloTest extends TestCase { public function testGetHelloString(): void { $matcher = new Matcher(); // Create your expected request from the consumer. $request = new ConsumerRequest(); $request ->setMethod('GET') ->setPath('/hello/Bob') ->addHeader('Content-Type', 'application/json'); // Create your expected response from the provider. $response = new ProviderResponse(); $response ->setStatus(200) ->addHeader('Content-Type', 'application/json') ->setBody([ 'message' => $matcher->term('Hello, Bob', '(Hello, )[A-Za-z]+') ]); // Create a configuration that reflects the server that was started. You can create a custom MockServerConfigInterface if needed. $config = new MockServerConfig(); $config ->setConsumer('jsonConsumer') ->setProvider('jsonProvider') ->setPactDir(__DIR__.'/../../../pacts'); if ($logLevel = \getenv('PACT_LOGLEVEL')) { $config->setLogLevel($logLevel); } $builder = new InteractionBuilder($config); $builder ->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. $helloResult = $service->getHelloString('Bob'); // Make the real API request against the Mock Server. $verifyResult = $builder->verify(); // This will verify that the interactions took place. $this->assertTrue($verifyResult); // Make your assertions. $this->assertEquals('Hello, Bob', $helloResult); } }
You can see (and run) the full version of this in ./examples/json
, as well as other examples in the parent folder.
To run the examples
- Clone the repo
git@github.com:pact-foundation/pact-php.git
- Go to the repo
cd pact-php
- Install all dependencies
composer install
Run a single example
composer run-example:json
Run all examples
composer run-examples
Verifying a Provider
A provider test takes one or more pact files (contracts) as input, and Pact verifies that your provider adheres to the contract. In the simplest case, you can verify a provider as per below using a local pact file, although in practice you would usually use a Pact Broker to manage your contracts and CI/CD workflow.
namespace App\Tests; use GuzzleHttp\Psr7\Uri; use PhpPact\Standalone\ProviderVerifier\Model\VerifierConfig; use PhpPact\Standalone\ProviderVerifier\Verifier; use PhpPactTest\Helper\PhpProcess; use PHPUnit\Framework\TestCase; class PactVerifyTest extends TestCase { private PhpProcess $process; protected function setUp(): void { $this->process = new PhpProcess(__DIR__ . '/path/to/public/'); $this->process->start(); } protected function tearDown(): void { $this->process->stop(); } /** * This test will run after the web server is started. */ public function testPactVerifyConsumer() { $config = new VerifierConfig(); $config->getProviderInfo() ->setName('jsonProvider') // Providers name to fetch. ->setHost('localhost') ->setPort($this->process->getPort()); $config->getProviderState() ->setStateChangeUrl(new Uri(sprintf('http://localhost:%d/pact-change-state', $this->process->getPort()))) ; if ($level = \getenv('PACT_LOGLEVEL')) { $config->setLogLevel($level); } $verifier = new Verifier($config); $verifier->addFile(__DIR__ . '/path/to/pacts/jsonConsumer-jsonProvider.json'); $verifyResult = $verifier->verify(); $this->assertTrue($verifyResult); } }
It's best to run Pact verification tests as part of your unit testing suite, so you can readily access stubbing, IaC and other helpful tools.
Compatibility
Versions
* v3 support is limited to the subset of functionality required to enable language inter-operable Message support.
Supported Platforms
* For 9.x and below, supported with a workaround Ruby Standalone with Alpine.
Roadmap
The roadmap for Pact and Pact PHP is outlined on our main website.
Contributing
See CONTRIBUTING.