Need help with pact-net?
Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.

About the developer

555 Stars 186 Forks MIT License 637 Commits 24 Opened issues


.NET 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.

Services available


Need anything else?

Contributors list

Important Announcement

The PactNet team are excited to share an important announcement! 🎉

PactNet is undergoing a large change in preparation for a v4.0.0 major release with breaking changes. This is primarily driven by the move from using the Pact Ruby implementation to using the new Pact Rust implementation. For PactNet users, this has the following benefits:

  • A new fluent API which guides developers into the pit of success more often
  • There is now one NuGet to install which handles all supported platforms instead of one per OS/arch combination
  • The Rust implementation is receiving all the new features and fixes, including Pact specification v4 support in future
  • A number of long-standing issues will be resolved, such as:
    • Filepath lengths on Windows will no longer be an issue since the Rust implementation is a single file under the
    • There is no child Ruby process still running if you abort an interactive debugger session, since the Rust implementation runs in-proc
    • The mock server can allocate an unused port dynamically, so you no longer need to provide one that you know is unused
    • You no longer need to remember to call
      between each consumer test

We're working really hard to get to a beta release, but until then you can check out our progress on the


We understand that breaking changes like these can be difficult for users of PactNet, but the major shift in the reference implementation from the Pact Foundation core team makes many of them necessary. At the same time, we've taken the opportunity to make changes which will make future versions of PactNet easier to extend in non-breaking ways as new features are released, and to fix many long-standing issues. We thank you for your patience with this, and rest-assured we'll provide documentation of the new API as well as samples and a full workshop showing how to use it.


Build status A .NET implementation of the Ruby consumer driven contract library, Pact. Pact is based on the specification found at

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

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

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.


Known Issues

  1. 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 for more details.


Below are some samples of usage. For examples of Version 2 usage, please see the Samples.

We have also written some

comments inline in the code to help explain what certain calls do.

A few others things to note: 1. When using

you must supply a valid Ruby regular expression, as we currently use the Ruby core engine.


Via Nuget


Install-Package PactNet.Windows


Install-Package PactNet.OSX

Linux x64 (64-bit)

Install-Package PactNet.Linux.x64

Linux x86 (32-bit)

Install-Package PactNet.Linux.x86

Service Consumer

1. Build your client

Which may look something like this.

public class SomethingApiClient
  private readonly HttpClient _client;

public SomethingApiClient(string baseUri = null) { _client = new HttpClient { BaseAddress = new Uri(baseUri ?? "http://my-api") }; }

public async Task GetSomething(string id) { string reasonPhrase;

var request = new HttpRequestMessage(HttpMethod.Get, "/somethings/" + id);
request.Headers.Add("Accept", "application/json");

var response = await _client.SendAsync(request);

var content = await response.Content.ReadAsStringAsync();
var status = response.StatusCode;

reasonPhrase = response.ReasonPhrase; //NOTE: any Pact mock provider errors will be returned here and in the response body


if (status == HttpStatusCode.OK)
  return !String.IsNullOrEmpty(content) ?
    : null;

throw new Exception(reasonPhrase);

} }

2. Describe and configure the pact as a service consumer with a mock service

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.

public class ConsumerMyApiPact : IDisposable
  public IPactBuilder PactBuilder { get; private set; }
  public IMockProviderService MockProviderService { get; private set; }

public int MockServerPort { get { return 9222; } } public string MockProviderServiceBaseUri { get { return String.Format("http://localhost:{0}", MockServerPort); } }

public ConsumerMyApiPact() { PactBuilder = new PactBuilder(); //Defaults to specification version 1.1.0, uses default directories. PactDir: ....\pacts and LogDir: ....\logs //or PactBuilder = new PactBuilder(new PactConfig { SpecificationVersion = "2.0.0" }); //Configures the Specification Version //or PactBuilder = new PactBuilder(new PactConfig { PactDir = @"..\pacts", LogDir = @"c:\temp\logs" }); //Configures the PactDir and/or LogDir.

  .HasPactWith("Something API");

MockProviderService = PactBuilder.MockService(MockServerPort); //Configure the http mock server
MockProviderService = PactBuilder.MockService(MockServerPort, true); //By passing true as the second param, you can enabled SSL. A self signed SSL cert will be provisioned by default.
MockProviderService = PactBuilder.MockService(MockServerPort, true, sslCert: sslCert, sslKey: sslKey); //By passing true as the second param and an sslCert and sslKey, you can enabled SSL with a custom certificate. See "Using a Custom SSL Certificate" for more details.
MockProviderService = PactBuilder.MockService(MockServerPort, new JsonSerializerSettings()); //You can also change the default Json serialization settings using this overload
MockProviderService = PactBuilder.MockService(MockServerPort, host: IPAddress.Any); //By passing host as IPAddress.Any, the mock provider service will bind and listen on all ip addresses


public void Dispose() { PactBuilder.Build(); //NOTE: Will save the pact file once finished } }

3. Write your test

Create a new test case and implement it.

public class SomethingApiConsumerTests : IClassFixture
  private IMockProviderService _mockProviderService;
  private string _mockProviderServiceBaseUri;

public SomethingApiConsumerTests(ConsumerMyApiPact data) { _mockProviderService = data.MockProviderService; _mockProviderService.ClearInteractions(); //NOTE: Clears any previously registered interactions before the test is run _mockProviderServiceBaseUri = data.MockProviderServiceBaseUri; }

[Fact] public void GetSomething_WhenTheTesterSomethingExists_ReturnsTheSomething() { //Arrange _mockProviderService .Given("There is a something with id 'tester'") .UponReceiving("A GET request to retrieve the something") .With(new ProviderServiceRequest { Method = HttpVerb.Get, Path = "/somethings/tester", Headers = new Dictionary { { "Accept", "application/json" } } }) .WillRespondWith(new ProviderServiceResponse { Status = 200, Headers = new Dictionary { { "Content-Type", "application/json; charset=utf-8" } }, Body = new //NOTE: Note the case sensitivity here, the body will be serialised as per the casing defined { id = "tester", firstName = "Totally", lastName = "Awesome" } }); //NOTE: WillRespondWith call must come last as it will register the interaction

var consumer = new SomethingApiClient(_mockProviderServiceBaseUri);

var result = consumer.GetSomething("tester");


_mockProviderService.VerifyInteractions(); //NOTE: Verifies that interactions registered on the mock provider are called at least once

} }

4. Run the test

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.

Service Provider

1. Create the API

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.

2. Tell the provider it needs to honour the pact

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.

public class SomethingApiTests
  public void EnsureSomethingApiHonoursPactWithConsumer()
    const string serviceUri = "http://localhost:9222";
    var config = new PactVerifierConfig
        Outputters = new List //NOTE: We default to using a ConsoleOutput, however xUnit 2 does not capture the console output, so a custom outputter is required.
            new XUnitOutput(_output)
        CustomHeaders = new Dictionary{{"Authorization", "Basic VGVzdA=="}}, //This allows the user to set request headers that will be sent with every request the verifier sends to the provider
        Verbose = true //Output verbose verification logs to the test output

using (WebApp.Start<teststartup>(serviceUri))
    //Act / Assert
    IPactVerifier pactVerifier = new PactVerifier(config);

    var pactUriOptions = new PactUriOptions()
        .SetBasicAuthentication("someuser", "somepassword") // you can specify basic auth details
        .SetBearerAuthentication("sometoken") // Or a bearer token
        //and / or
        .SetSslCaFilePath("path/to/your/ca.crt") //if you fetch your pact in https and the server certificate authorities are not in the default ca-bundle.crt
        //and / or
        .SetHttpProxy("http://my-http-proxy:8080"); //if you need to go through a proxy to reach the server hosting the pact

        .ServiceProvider("Something API", serviceUri)
        .PactUri("http://pact-broker/pacts/provider/Something%20Api/consumer/Consumer/latest") //You can specify a http or https uri
        .PactUri("http://pact-broker/pacts/provider/Something%20Api/consumer/Consumer/latest", pactUriOptions) //With options decribed above
        //or (if you're using the Pact Broker, you can use the various different features, including pending pacts)
        .PactBroker("http://pact-broker", uriOptions: pactUriOptions, enablePending: true, consumerVersionTags: new   List<string> { "master" }, providerVersionTags: new List<string> { "master" }, consumerVersionSelectors: new List<versiontagselector> { new VersionTagSelector("master") })

} }

public class TestStartup
    public void Configuration(IAppBuilder app)
        var apiStartup = new Startup(); //This is your standard OWIN startup object



public class ProviderStateMiddleware
    private const string ConsumerName = "Event API Consumer";
    private readonly Func, Task> m_next;
    private readonly IDictionary _providerStates;

public ProviderStateMiddleware(Func<idictionary object>, Task&gt; next)
    m_next = next;
    _providerStates = new Dictionary<string action>
            "There is a something with id 'tester'",

private void AddTesterIfItDoesntExist()
  //Add code to go an inject or insert the tester data

public async Task Invoke(IDictionary<string object> environment)
    IOwinContext context = new OwinContext(environment);

    if (context.Request.Path.Value == "/provider-states")
        context.Response.StatusCode = (int)HttpStatusCode.OK;

        if (context.Request.Method == HttpMethod.Post.ToString() &amp;&amp;
            context.Request.Body != null)
            string jsonRequestBody;
            using (var reader = new StreamReader(context.Request.Body, Encoding.UTF8))
                jsonRequestBody = reader.ReadToEnd();

            var providerState = JsonConvert.DeserializeObject<providerstate>(jsonRequestBody);

            //A null or empty provider state key must be handled
            if (providerState != null &amp;&amp;
                !IsNullOrEmpty(providerState.State) &amp;&amp;
                providerState.Consumer == ConsumerName)

            await context.Response.WriteAsync(Empty);
        await m_next.Invoke(environment);


public class ProviderState
    public string Consumer { get; set; }
    public string State { get; set; }
public class XUnitOutput : IOutput
    private readonly ITestOutputHelper _output;

public XUnitOutput(ITestOutputHelper output)
    _output = output;

public void WriteLine(string line)


4. Run the test

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.

Using a Custom SSL Certificate

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.

1. Generate a custom SSL certificate

The simplest way to generate a private key and self-signed certificate for localhost is with this openssl command:

openssl req -x509 -out localhost.crt -keyout localhost.key \
  -newkey rsa:2048 -nodes -sha256 \
  -subj '/CN=localhost' -extensions EXT -days 365 -config 

The above script will generate two files:

  • localhost.crt
  • localhost.key

Ref. certificates-for-localhost.

2. Add Certificate to Certificate Store

For windows, import the localhost.crt to the 'Trust Root Certification Authorities' of the Current User Certificates.

3. Use the Certificate

public string MockProviderServiceBaseUri => $"https://localhost:{MockServerPort}";
var sslCrt = @"{PathTo}\localhost.crt";
var sslKey = @"{PathTo}\localhost.key";
MockProviderService = PactBuilder.MockService(MockServerPort, true, IPAddress.Any, sslCrt, sslKey);

Using a Remote Mock Server Service to execute Consumer tests

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:

 PactBuilder.MockService(MockServerPort, useRemoteMockService = 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:

docker run -dit \
  --rm \
  --name pact-mock-service \
  -p 1234:1234 \
  -v ${HOST_PACT_DIRECTORY}:/tmp/pacts \
  pactfoundation/pact-cli:latest \
  mock-service \
  -p 1234 \
  --host \
  --pact-dir /tmp/pacts

Publishing Pacts to a Broker

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.

Using PowerShell on your build server

Checkout this gist to see an example of how you can do this.

Using the C# client

If you use build tools like Fake and Cake, you may want create a broker publish task and using the PactPublisher.

var pactPublisher = new PactPublisher("", new PactUriOptions("username", "password"));
    "1.0.2", new [] { "master" });

Publishing Provider Verification Results to a Broker

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.

var gitSha = Environment.GetEnvironmentVariable("GIT_SHA");
var isCI = "true".Equals(Environment.GetEnvironmentVariable("CI"));

var config = new PactVerifierConfig { ProviderVersion = gitSha, //NOTE: Setting a provider version is required for publishing verification results PublishVerificationResults = isCI }; IPactVerifier pactVerifier = new PactVerifier(config); pactVerifier .ServiceProvider("Something Api", serviceUri) .HonoursPactWith("Consumer") .PactUri("http://pact-broker/pacts/provider/Something%20Api/consumer/Consumer/latest") //NOTE: This must be a pact broker url for this feature to work .Verify();

Further Documentation

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.