A .NET implementation of the Ruby consumer driven contract library, Pact.
Pact is based on the specification found at https://github.com/pact-foundation/pact-specification.
PactNet primarily provides a fluent .NET DSL for describing HTTP requests that will be made to a service provider and the HTTP responses the consumer expects back to function correctly.
In documenting the consumer interactions, we can replay them on the provider and ensure the provider responds as expected. This basically gives us complete test symmetry and removes the basic need for integrated tests.
PactNet also has the ability to support other mock providers should we see fit.
PactNet is Version 2.0 compliant, and we now use the Ruby standalone engine as we move towards a common core approach. To enable Version 2.0 support, make sure you supply a
PactConfig object with
SpecificationVersion = "2.0.0" when creating the
In reaching Version 2.0 compliance, we have made some breaking changes. This readme details the current latest version.
See Version 1.0 readme for the previous version.
From the Pact Specification repo
"Pact" is an implementation of "consumer driven contract" testing that allows mocking of responses in the consumer codebase, and verification of the interactions in the provider codebase. The initial implementation was written in Ruby for Rack apps, however a consumer and provider may be implemented in different programming languages, so the "mocking" and the "verifying" steps would be best supported by libraries in their respective project's native languages. Given that the pact file is written in JSON, it should be straightforward to implement a pact library in any language, however, to get the best experience and most reliability of out mixing pact libraries, the matching logic for the requests and responses needs to be identical. There is little confidence to be gained in having your pacts "pass" if the logic used to verify a "pass" is inconsistent between implementations.
Read more about Pact and the problems it solves at https://docs.pact.io/
Please feel free to contribute, we do accept pull requests. This solution has been built using VS2017, you will need it to open this project.
PactNet was initially built at SEEK to help solve some of the challenges faced with testing across service boundaries.
The project now lives in the pact-foundation GH organisation, to help group and support the official Pact libraries.
Massive thanks to the SEEK team for all the time and hard work put into this library.
- When debugging a test locally (either consumer or provider) if you click the stop button in your test runner, it will abort the process abruptly and the ruby runtime will not get cleaned up. If you do this, simply kill the ruby process from your task/process manager. We recommend you play the test through to the end to avoid this issue. See https://github.com/pact-foundation/pact-net/issues/108 for more details.
Below are some samples of usage.
For examples of Version 2 usage, please see the Samples.
We have also written some
//NOTE: comments inline in the code to help explain what certain calls do.
A few others things to note:
- When using
Match.Regexyou must supply a valid Ruby regular expression, as we currently use the Ruby core engine.
Linux x64 (64-bit)
Linux x86 (32-bit)
Which may look something like this.
Create a new test case within your service consumer test project, using whatever test framework you like (in this case we used xUnit).
This should only be instantiated once for the consumer you are testing.
Create a new test case and implement it.
If you now navigate to [RepositoryRoot]/pacts you will see the pact file your test generated. Take a moment to have a look at what it contains which is a JSON representation of the mocked requests your test made.
Everything should be green.
Note: we advise using a TDD approach when using this library, however we will leave it up to you.
Likely you will be creating a skeleton client, describing the pact, write the failing test, implement the skeleton client, run the test to make sure it passes, then rinse and repeat.
You can create the API using whatever framework you like, however this example will use ASP.NET Web API 2 with Owin.
Note: We have removed to support for Microsoft.Owin.Testing, as we have moved to using a shared Pact core. You will now be required to start the API and listen on the correct port, as part of the test.
Create a new test case within your service provider test project, using whatever test framework you like (in this case we used xUnit). PactUri method should refer to the pact json file, created when the Consumer Test was run.
Everything should be green
Again, please note: we advise using a TDD approach when using this library, however we will leave it up to you.
For further examples please refer to the Samples in the solution.
When creating the MockProviderService you can use a custom SSL cert, which allows the use of a valid installed certificate without requiring any hacks to ignore certificate validation errors.
The simplest way to generate a private key and self-signed certificate for localhost is with this openssl command:
The above script will generate two files:
For windows, import the localhost.crt to the 'Trust Root Certification Authorities' of the Current User Certificates.
It is possible to execute your consumer test against any remote Mock Server (including a docker container).
In that case you don't need any other package than PactNet. (Ruby packages are not required i.e.: PactNet.Windows/PactNet.OSX, PactNet.Linux.*)
This also fix the building issues of path too long in windows with ruby packages.
To run your consumer tests against a remote server, in PactBuilder class, set the "useRemoteMockService" parameter to true:
Then simply use the remote host url and port to send the call to your remote server.
The pacts file generated this way will be saved to the path that you define in the PactDir property of PactConfig object.
You can run a remote mock server service with the pact-cli docker container as follow:
The Pact broker is a useful tool that can be used to share pacts between the consumer and provider. In order to make this easy, below are a couple of options for publishing your Pacts to a Pact Broker.
Checkout this gist to see an example of how you can do this.
If you use build tools like Fake and Cake, you may want create a broker publish task and using the PactPublisher.
This feature allows the result of the Provider verification to be pushed to the broker and displayed on the index page. In order for this to work you must set the ProviderVersion, PublishVerificationResults and use a pact broker uri. If you do not use a broker uri no verification results will be published. See the code snippet code below. For more info and compatibility details refer to this. See the Best practices section of the "Versioning in the Pact Broker" for recommendations on what to use for the version number.