Contract Testing in .NET — PactNet Enum Removal Failures

In a microservices architecture, the scariest failures aren't the ones your unit tests catch — they're the silent ones that only blow up in production when Service A calls Service B and gets back a response shape it never expected. A field gets renamed, a nullable becomes required, an enum value disappears. Your 2000-unit-test suite is all green. Your integration environment is down for maintenance. And at 2am, your on-call phone rings. Contract testing exists precisely to close this gap.

The problem is subtle: traditional integration tests force you to spin up every dependent service simultaneously, coordinate deployment windows, and pray the test data lines up. That's slow, brittle, and it couples your CI pipelines together in ways that feel manageable on day one and catastrophic at scale. Consumer-Driven Contract (CDC) testing flips the model — each consumer declares what it needs, each provider proves it can satisfy those needs, and they do it asynchronously, independently, and fast.

By the end of this article you'll know how to implement full consumer-driven contract testing in .NET using PactNet, understand the internals of how pact files are generated and verified, handle edge cases like optional fields and provider states, integrate pact verification into your CI/CD pipeline, and avoid the production gotchas that catch even experienced teams off guard.

What is Contract Testing in .NET?

Contract testing in .NET is about defining a formal agreement between a service consumer (e.g., an API client) and a provider (e.g., a REST API). The agreement, called a pact, describes the exact request the consumer will make and the exact response it expects. With PactNet—the .NET implementation of the Pact framework—you write these expectations as unit tests in the consumer project.

The key insight: the consumer's tests generate a JSON file (the pact). The provider then runs its own tests that replay those expectations against the real provider server. No need to deploy both services together, no fragile integration environment.

Let's see a concrete example. Suppose we have an Orders API that returns order details. The consumer (a web frontend) expects a GET /orders/1 to return a 200 with body { id: 1, status: "shipped" }. The consumer test in PactNet builds that expectation.

using PactNet;
using PactNet.Infrastructure.Outputters;
using Xunit;

public class OrderApiConsumerTests
{
    private readonly IPactBuilderV3 _pactBuilder;

    public OrderApiConsumerTests()
    {
        var pactConfig = new PactConfig
        {
            PactDir = @"..\..\pacts",
            Outputters = new[] { new ConsoleOutput() }
        };
        _pactBuilder = PactNet.Pact.V3(
            "WebFrontend",   // consumer name
            "OrderApi",      // provider name
            pactConfig);
    }

    [Fact]
    public async Task GetOrder_ReturnsOrder_WhenOrderExists()
    {
        _pactBuilder
            .UponReceiving("a GET request for order 1")
                .Given("order 1 exists")
                .WithRequest(HttpMethod.Get, "/orders/1")
                .WithHeader("Accept", "application/json")
            .WillRespond()
                .WithStatus(HttpStatusCode.OK)
                .WithHeader("Content-Type", "application/json")
                .WithJsonBody(new
                {
                    id = 1,
                    status = "shipped"
                });

        await _pactBuilder.VerifyAsync(async ctx =>
        {
            // Real consumer code that calls the mock server
            var client = new HttpClient { BaseAddress = ctx.MockServerUri };
            var response = await client.GetAsync("/orders/1");
            var body = await response.Content.ReadAsStringAsync();
            Assert.Equal(HttpStatusCode.OK, response.StatusCode);
            Assert.Contains("\"status\": \"shipped\"", body);
        });
    }
}

Consumer-Driven Contract Testing with PactNet

The consumer-driven approach means the consumer dictates what it needs from the API. The provider doesn't decide the contract unilaterally. This sounds backward, but it's the only way to catch breaking changes before they reach production.

In practice, the consumer team writes PactNet tests that define every interaction they rely on. For each interaction, they specify: - The HTTP method and path - Query parameters, headers, and body (if any) - Expected response status, headers, and body structure - Provider states — named conditions the provider must set up (e.g., "order exists")

Once all consumer tests pass, the pact file is published to a Pact Broker (or stored in a shared artifact repository). The provider's CI pipeline then runs verification tests against that pact. If the provider breaks a contract, the provider build fails — not the consumer's. This shifts the failure left, before the change is ever deployed.

public class OrderApiConsumerTests
{
    // ... setup as before ...

    [Fact]
    public async Task CreateOrder_Returns201_WhenValidRequest()
    {
        _pactBuilder
            .UponReceiving("a POST request to create order")
                .Given("the system is ready to accept orders")
                .WithRequest(HttpMethod.Post, "/orders")
                .WithHeader("Content-Type", "application/json")
                .WithJsonBody(new
                {
                    productId = 42,
                    quantity = 2
                })
            .WillRespond()
                .WithStatus(HttpStatusCode.Created)
                .WithHeader("Location", "/orders/500");

        await _pactBuilder.VerifyAsync(async ctx =>
        {
            var client = new HttpClient { BaseAddress = ctx.MockServerUri };
            var response = await client.PostAsJsonAsync("/orders", new { productId = 42, quantity = 2 });
            Assert.Equal(HttpStatusCode.Created, response.StatusCode);
            Assert.Contains("/orders/", response.Headers.Location.ToString());
        });
    }
}

Provider Verification with PactNet

Now the provider team sets up verification tests. They don't need to write test scenarios — they simply load the pact file and replay it against a running instance of their API. PactNet's verification engine calls each endpoint with the exact request from the pact and checks the response matches expectations.

The provider must register provider states — methods that set up the exact data conditions required by the consumer tests. For example, if the consumer expects "order 1 exists", the provider must have a method that inserts an order with ID 1 into the test database.

Here's how to write provider verification in .NET:

using PactNet.Verifier;
using Xunit;

public class OrderApiProviderTests : IClassFixture<OrderApiFixture>
{
    private readonly OrderApiFixture _fixture;

    public OrderApiProviderTests(OrderApiFixture fixture)
    {
        _fixture = fixture;
    }

    [Fact]
    public void VerifyPacts()
    {
        var config = new PactVerifierConfig
        {
            Outputters = new[] { new ConsoleOutput() },
            LogLevel = PactNet.LogLevel.Debug
        };

        var verifier = new PactVerifier(config);

        verifier
            .ServiceProvider("OrderApi", _fixture.ServerUri)
            .HonoursPactWith("WebFrontend")
            .PactUri(@"..\..\pacts\WebFrontend-OrderApi.json")
            .WithProviderStateUrl(new Uri(_fixture.ServerUri, "/provider-states"))
            .Verify();
    }
}

// Provider states controller (run in-memory with WebApplicationFactory)
[ApiController]
[Route("provider-states")]
public class ProviderStatesController : ControllerBase
{
    [HttpPost("setup")]
    public IActionResult Setup([FromBody] ProviderState state)
    {
        if (state.State == "order 1 exists")
        {
            // Arrange: insert order with id=1 into test database
            TestData.Orders.Add(new Order { Id = 1, Status = "shipped" });
        }
        return Ok();
    }

    [HttpPost("teardown")]
    public IActionResult Teardown()
    {
        TestData.Orders.Clear();
        return Ok();
    }
}

Handling Provider States and Edge Cases

Provider states are the trickiest part of PactNet. They let the consumer describe preconditions without knowing how the provider sets them up. Common edge cases include:

• Missing state: the consumer says "order exists" but the provider hasn't registered that state. Verification fails.
• State with dynamic data: the consumer expects a specific ID, but the provider's test data generates random IDs. The consumer must use a fixed ID.
• Multiple states per interaction: some interactions need multiple conditions (e.g., "user is logged in" AND "order exists"). PactNet supports combining states as an array.
• Teardown: after each state, the provider should clean up any data to avoid test pollution. Use teardown endpoint.

Here's how to handle a consumer test that uses multiple states:

// Consumer test with multiple provider states
_pactBuilder
    .UponReceiving("a GET request for pending orders by user")
        .Given(new[] { "user exists", "user has pending orders" })
        .WithRequest(HttpMethod.Get, "/orders/pending")
        .WithQuery("userId", "42")
    .WillRespond()
        .WithStatus(HttpStatusCode.OK)
        .WithJsonBody(new[]
        {
            new { id = 1, status = "pending" },
            new { id = 2, status = "pending" }
        });

// Provider verification setup
public class ProviderStates
{
    [ProviderState("user exists")]
    public static void UserExists() => TestData.Users.Add(new User { Id = 42, Name = "Alice" });

    [ProviderState("user has pending orders")]
    public static void UserHasPendingOrders()
    {
        TestData.Orders.AddRange(new[]
        {
            new Order { Id = 1, UserId = 42, Status = "pending" },
            new Order { Id = 2, UserId = 42, Status = "pending" }
        });
    }
}

CI/CD Integration and Production Gotchas

The real value of contract testing comes from integrating it into your CI/CD pipelines. Both consumer and provider pipelines must run pact tests on every pull request. The typical flow:

1. Consumer PR: run pact tests, publish pact file to broker.
2. Provider PR: fetch latest pacts from broker, verify all interactions.
3. Provider can only merge if all pacts pass.
4. Consumer can deploy independently — the broker tells them which provider versions are safe.

PactNet supports publishing to a Pact Broker. The broker stores all versions of all pacts and can verify compatibility matrix.

// In consumer test setup, after all tests pass
var publisher = new PactPublisher("https://your-pact-broker.com",
    new PactUriOptions("broker-token-here"));
await publisher.PublishToBroker(
    pactFilePath,
    new Version(1, 0, 0),        // consumer version
    new Dictionary<string, string>
    {
        ["branch"] = "main",
        ["buildUrl"] = buildUrl
    });

When Pact Verification Fails: Real Debugging Patterns

Even with well-written pacts, verification failures happen. Here's how to debug the most common causes:

1. Response field mismatch: PactNet compares actual response against expected using structural tolerance by default. If a field is missing or has wrong type, the verifier reports the exact path. Check the verifier log at debug level for details.

2. Dynamic fields: If your API returns timestamps or GUIDs, the pact must use a matcher (like PactNet's Match.Type or Match.Regex) to say 'I expect a string of this pattern, not an exact value'.

3. Query parameter order: Some HTTP clients order query parameters alphabetically. If your consumer sends them in a different order, the pact request will differ. Use List matching or ignore order.

4. Provider state setup failure: If the provider state method throws an exception, the verification stops. Check that the state name matches exactly (case-sensitive) and that all dependencies (e.g., test database) are available.

5. Missing headers: PactNet expects exact header values. If your provider adds additional headers (like Server or X-Request-Id), the verifier will fail. Use 'header blacklist' or match headers loosely.

// Using matchers for dynamic content
using PactNet.Matchers;

_pactBuilder
    .UponReceiving("a GET request for order 1")
        .Given("order 1 exists")
        .WithRequest(HttpMethod.Get, "/orders/1")
    .WillRespond()
        .WithStatus(HttpStatusCode.OK)
        .WithJsonBody(new
        {
            id = Match.Type(1),              // integer, exact value not important
            status = Match.Regex("shipped", "^(pending|shipped|cancelled)$"),
            created_at = Match.Type("2026-01-01T00:00:00") // datetime string
        });