Contract Test Design Skill

Contract Test Design

When to Use This Skill

Use this skill when:

Contract Test Design tasks - Working on consumer-driven contract testing strategies using Pact
Planning or design - Need guidance on contract testing approaches
Best practices - Want to follow established patterns and standards

Overview

Contract testing verifies that services communicate correctly by testing the contract (API agreement) between a consumer and provider. Consumer-driven contracts (CDC) ensure providers don't break their consumers.

Contract Testing vs Other Test Types

| Aspect | E2E Tests | Integration Tests | Contract Tests | |--------|-----------|-------------------|----------------| | Scope | Full system | Component + deps | Consumer-provider | | Speed | Slow (minutes) | Medium (seconds) | Fast (ms) | | Reliability | Often flaky | Moderate | Very stable | | Deployment coupling | High | Medium | Low (async) | | Failure localization | Poor | Moderate | Excellent | | Maintenance | High | Medium | Low |

Consumer-Driven Contract Flow

┌─────────────────────────────────────────────────────────────┐
│                    CONSUMER SIDE                            │
│                                                             │
│  1. Consumer writes test   2. Test generates contract       │
│     ┌──────────────┐          ┌──────────────┐              │
│     │ Consumer     │          │   Contract   │              │
│     │ Test         │  ─────►  │   (JSON)     │              │
│     └──────────────┘          └──────────────┘              │
│                                      │                      │
└──────────────────────────────────────┼──────────────────────┘
                                       │
                                       ▼ Publish to Broker
                              ┌──────────────────┐
                              │  Contract Broker │
                              │  (Pact Broker)   │
                              └────────┬─────────┘
                                       │
┌──────────────────────────────────────┼──────────────────────┐
│                    PROVIDER SIDE     │                      │
│                                      ▼                      │
│  3. Provider verifies contract                              │
│     ┌──────────────┐          ┌──────────────┐              │
│     │  Provider    │  ◄─────  │   Contract   │              │
│     │  Verification│          │   (JSON)     │              │
│     └──────────────┘          └──────────────┘              │
│            │                                                │
│            ▼                                                │
│  4. Provider tests pass = Contract honored                  │
│                                                             │
└─────────────────────────────────────────────────────────────┘

Quick Reference: Breaking Changes

| Change Type | Breaking? | Action | |-------------|-----------|--------| | Remove field | Yes | Block deployment | | Change field type | Yes | Block deployment | | Add required field | Yes | Block deployment | | Add optional field | No | Allow | | Add new endpoint | No | Allow |

Tooling Selection

| Purpose | Tool | Rationale | |---------|------|-----------| | Contract Framework | PactNet | .NET native, mature | | Broker | Pact Broker | Standard, free tier | | Async Contracts | Pact Message | Same ecosystem | | Schema Validation | OpenAPI | Industry standard |

References

| Reference | Content | When to Load | | --- | --- | --- | | strategy-template.md | Contract testing strategy template, service maps, workflows | Planning contract testing strategy | | pact-dotnet-implementation.md | Consumer tests, provider verification, provider states | Implementing Pact in .NET | | message-contracts.md | Async message/event contract testing | Testing event-driven architectures | | matchers-cicd.md | Pact matchers, breaking change detection, CI/CD pipelines | Matcher syntax, CI/CD integration |

Integration Points

Inputs from:

API specifications → Contract definitions
Service architecture → Consumer-provider map
test-strategy-planning skill → Contract test scope

Outputs to:

CI/CD pipeline → Contract verification gates
API governance → Breaking change detection
api-design-fundamentals skill → Contract-first design

Test Scenarios

Scenario 1: Planning contract testing strategy

Query: "Help me design a contract testing strategy for our microservices"

Expected: Skill activates, provides strategy template, guides through service mapping

Scenario 2: Implementing Pact tests

Query: "Show me how to write Pact consumer tests in .NET"

Expected: Skill activates, loads pact-dotnet-implementation.md reference, provides code examples

Scenario 3: CI/CD integration

Query: "How do I integrate contract testing into our GitHub Actions pipeline?"

Expected: Skill activates, loads matchers-cicd.md reference, provides pipeline examples

Last Updated: 2025-12-28

Version History

v1.1.0 (2025-12-28): Refactored to progressive disclosure - extracted implementation to references/
v1.0.0 (2025-12-26): Initial release

Agent Skills: Contract Test Design

Install this agent skill to your local

Skill Files