tomevault-io 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-planningskill → Contract test scope
Outputs to:
- CI/CD pipeline → Contract verification gates
- API governance → Breaking change detection
api-design-fundamentalsskill → 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
Converted and distributed by TomeVault — claim your Tome and manage your conversions.