Testing Contract

---




name: testing-contract
description: Validates external APIs and service contracts, ensuring that your application correctly consumes and produces expected data structures.
license: MIT
compatibility: opencode
metadata:
  version: "1.0.0"
  domain: coding
  triggers: contract testing, service contracts, API contracts, contract validation
  role: implementation
  scope: implementation
  output-format: code
  related-skills: testing-unit, testing-integration, testing-end-to-end
  archetypes: tactical, diagnostic
  anti_triggers: system testing, manual testing, acceptance testing
  response_profile:
    verbosity: medium
    directive_strength: high
    abstraction_level: tactical




---





# Contract Testing

Implements contract testing methods to validate the agreements between application services and external APIs. Ensure both the consumer and provider follow specified contracts like data formats and structures.

## When to Use
- When your application relies on third-party services.
- To ensure that changes in API specifications do not break your application.
- Before deployment to avoid runtime issues caused by contract violations.

## Core Workflow
1. **Choose Contract Testing Tool**  
   Select a framework tailored for contract testing (e.g., `Pact`, `Hoverfly`).
   ```bash
   # For JavaScript
   npm install @pact-foundation/pact
   ```
2. **Define Consumer and Provider Contracts**  
   Define what your service expects from external APIs.
   ```javascript
   const { Pact } = require('@pact-foundation/pact');
   const provider = new Pact({
       consumer: "YourService",
       provider: "ExternalAPI"
   });
   provider
       .uponReceiving('a request for data')
       .withRequest('GET', '/data')
       .willRespondWith({
           status: 200,
           body: { message: "Success" }
       });
   ```
3. **Run Contract Tests**  
   Execute the contract tests and ensure compliance with expectations.
   ```bash
   npm test
   ```
4. **Handle Contract Violations**  
   Repair code or update your contracts as necessary based on your test results.

## Implementation Patterns
### Pattern 1: Using Pact for Consumer-Driven Contracts
```javascript
const { Pact } = require('@pact-foundation/pact');

describe('Pact with Our API', () => {
    const provider = new Pact({
        consumer: 'Consumer',
        provider: 'APIProvider',
    });
    
    beforeAll(() => provider.setup());
    
    it('it should return a successful response', async () => {
        // Arrange
        await provider.addInteraction({
            state: 'data exists',
            uponReceiving: 'a request for data',
            withRequest: { method: 'GET', path: '/data' },
            willRespondWith: { status: 200, body: { message: 'Success' } },
        });
        
        // Act
        const response = await fetch('http://localhost:3000/data');
        const body = await response.json();

        // Assert
        expect(body.message).toEqual('Success');
    });

    afterAll(() => provider.finalize());
});
```

---

## Implementation Patterns

### Pattern 2: Provider Verification with Pact (Python)

On the provider side, use `pact-python` to verify that the API satisfies the consumer's expectations:

```python
from pact import Verifier

def test_provider_meets_consumer_contract():
    """Verify the provider API satisfies the Pact contract."""
    verifier = Verifier(
        provider="APIProvider",
        provider_base_url="http://localhost:8000",
    )
    
    # Load the Pact file published by the consumer
    pact_url = "pacts/consumer-apiprovider.json"
    
    # Verify all interactions from the consumer's Pact
    success, logs = verifier.verify_pacts(
        pact_url,
        provider_states_setup_url=f"{verifier.provider_base_url}/_pact/setup",
        verbose=False,
    )
    
    assert success, f"Provider verification failed: {logs}"
```

The consumer writes tests and publishes a Pact file. The provider loads that file and verifies every interaction actually works against the real API. This catches breaking changes before deployment.

```python
# Example Pact file structure (generated by consumer tests)
# {
#   "consumer": {"name": "Consumer"},
#   "provider": {"name": "APIProvider"},
#   "interactions": [{
#     "description": "a request for data",
#     "request": {"method": "GET", "path": "/data"},
#     "response": {"status": 200, "body": {"message": "Success"}}
#   }]
# }
```

## Constraints
### MUST DO
- Regularly update contracts and documentation to reflect changes.
- Ensure that the API service is functional before running contract tests.

### MUST NOT DO
- Bypass contract tests; they are essential for integration continuity.
- Assume defaults; always explicitly define contracts.