Api contract testing

API Contract Testing for Mobile Clients

Instructions

Mobile apps ship asynchronously from their backend. A response-shape change the server team considers "non-breaking" can crash 4 % of installed apps a week later. Consumer-driven contract testing replaces fragile "run the app against staging" checks with fast, deterministic contracts that both sides verify in CI.

1. The Model

• The consumer (mobile app) declares what it needs from each endpoint: request shape, expected response shape, status codes.
• Those expectations are serialized as a pact file (JSON) and published to a broker.
• The provider (backend) replays each interaction against its real service in its own CI and fails if it cannot satisfy the contract.

Pact is the de-facto tool. This skill focuses on the consumer side (mobile).

2. Kotlin (Android / KMP) — Pact-JVM Consumer

@ExtendWith(PactConsumerTestExt::class)
@PactTestFor(providerName = "orders-api", pactVersion = PactSpecVersion.V4)
class OrdersApiPactTest {

    @Pact(consumer = "android-app")
    fun getOrderPact(builder: PactDslWithProvider): RequestResponsePact =
        builder
            .given("order 42 exists")
            .uponReceiving("get order 42")
                .path("/orders/42")
                .method("GET")
            .willRespondWith()
                .status(200)
                .headers(mapOf("Content-Type" to "application/json"))
                .body(newJsonBody { o ->
                    o.numberType("id", 42)
                    o.stringType("status", "PAID")
                    o.numberType("totalCents", 1999)
                }.build())
            .toPact()

    @Test
    fun `client parses order`(mockServer: MockServer) = runTest {
        val client = OrdersClient(baseUrl = mockServer.getUrl())
        val order  = client.getOrder(42)
        assertEquals(Order(id = 42, status = PAID, total = Money.cents(1999)), order)
    }
}

Publish the resulting pact file to a Pact Broker (pact_broker, Pactflow) from CI.

3. Swift (iOS) — PactSwift

final class OrdersApiPactTests: XCTestCase {
    var mockService: MockService!

    override func setUp() {
        mockService = MockService(consumer: "ios-app", provider: "orders-api")
    }

    func test_getOrder_parsesBody() throws {
        mockService
          .uponReceiving("a request for order 42")
          .given("order 42 exists")
          .withRequest(method: .GET, path: "/orders/42")
          .willRespondWith(status: 200, body: [
            "id": Matcher.SomethingLike(42),
            "status": Matcher.SomethingLike("PAID"),
            "totalCents": Matcher.SomethingLike(1999),
          ])

        mockService.run { baseURL, done in
            Task {
                let client = OrdersClient(baseURL: baseURL)
                let order  = try await client.getOrder(id: 42)
                XCTAssertEqual(order, .init(id: 42, status: .paid, totalCents: 1999))
                done()
            }
        }
    }
}

4. Dart (Flutter) — pact_dart

void main() {
  final pact = PactMockService('flutter-app', 'orders-api');

  setUpAll(pact.setup);
  tearDownAll(pact.tearDown);

  test('client parses order', () async {
    pact
      .newInteraction()
      .given('order 42 exists')
      .uponReceiving('get order 42')
      .withRequest(method: 'GET', path: '/orders/42')
      .willRespondWith(status: 200, body: {
        'id': 42, 'status': 'PAID', 'totalCents': 1999,
      });

    final client = OrdersClient(baseUrl: pact.mockServerUrl);
    expect(await client.getOrder(42),
           Order(id: 42, status: OrderStatus.paid, totalCents: 1999));
  });
}

5. TypeScript (React Native) — @pact-foundation/pact

import { PactV3, MatchersV3 } from '@pact-foundation/pact';
const { like } = MatchersV3;

const provider = new PactV3({ consumer: 'rn-app', provider: 'orders-api' });

test('client parses order', async () => {
  provider
    .given('order 42 exists')
    .uponReceiving('get order 42')
    .withRequest({ method: 'GET', path: '/orders/42' })
    .willRespondWith({
      status: 200,
      body: { id: like(42), status: like('PAID'), totalCents: like(1999) },
    });

  await provider.executeTest(async (mock) => {
    const client = new OrdersClient(mock.url);
    expect(await client.getOrder(42)).toEqual({ id: 42, status: 'PAID', totalCents: 1999 });
  });
});

6. Matchers

Match on types and presence, not exact values, or the contract becomes a wire-format diff. Use like(...), eachLike(...), iso8601Date(), uuid(). Reserve exact matches for enums and stable identifiers.

7. Publishing & Versioning

• Publish pact files tagged with the consumer's git SHA and branch.
• The provider's CI uses can-i-deploy to refuse deploying if it breaks a pact a deployed consumer still needs.
• Match pact branches to app release branches so hotfix branches verify against matching provider versions.

8. What Contracts Do NOT Cover

• End-to-end flows across multiple services (use a thin E2E suite).
• Performance, auth, or rate limits (separate tooling).
• UI correctness (snapshot / UI tests).

9. Checklist

• Every screen-level API call used by the mobile client has at least one consumer pact.
• Matchers describe types and structure, not hard-coded values, except for enums and IDs.
• Pact files are published to a broker from CI with version tags.
• Provider CI runs pact-verify and can-i-deploy on every merge.
• Contract tests replace — not duplicate — broad staging integration smoke tests.
• Legacy endpoints that have been retired are removed from the consumer pact.