Integration & Contract Testing
Focused patterns for testing API boundaries, cross-service contracts, component integration, database layers, property-based verification, and schema validation.
Quick Reference
For complex emulate setups (full config generation, webhook HMAC, CI per-worker port isolation), delegate to the emulate-engineer subagent. Pairs with the emulate-seed skill.
| Area |
Rule / Reference |
Impact |
| Stateful API testing (emulate) |
rules/emulate-stateful-testing.md |
HIGH |
| API endpoint tests |
rules/integration-api.md |
HIGH |
| React component integration |
rules/integration-component.md |
HIGH |
| Database layer testing |
rules/integration-database.md |
HIGH |
| Zod schema validation |
rules/validation-zod-schema.md |
HIGH |
| Pact contract testing |
rules/verification-contract.md |
MEDIUM |
| Stateful testing (Hypothesis) |
rules/verification-stateful.md |
MEDIUM |
| Evidence & property-based |
rules/verification-techniques.md |
MEDIUM |
References
| Topic |
File |
| House rules not documented upstream |
references/ork-delta.md |
| Consumer-side Pact tests |
references/consumer-tests.md |
| Hypothesis strategies guide |
references/strategies-guide.md |
Checklists
| Checklist |
File |
| Contract testing readiness |
checklists/contract-testing-checklist.md |
| Property-based testing |
checklists/property-testing-checklist.md |
Scripts & Templates
| Script |
File |
| Create integration test |
scripts/create-integration-test.md |
Examples
| Example |
File |
| Full testing strategy |
examples/orchestkit-test-strategy.md |
Upstream coverage (do not restate)
This skill wraps Pact, the Pact Broker, and FastAPI testing. It carries only the OrchestKit
delta. Fetch the vendor docs for the topics below instead of restating them here.
| Topic |
First-party source |
| Pact Broker publish CLI, pact versioning and tagging flags |
https://docs.pact.io/pact_broker/publishing_and_retrieving_pacts |
can-i-deploy, record-deployment, record-release |
https://docs.pact.io/pact_broker/can_i_deploy |
| Deployment and release recording semantics |
https://docs.pact.io/pact_broker/recording_deployments_and_releases |
| Broker webhooks that trigger a provider build on contract change |
https://docs.pact.io/pact_broker/webhooks |
Consumer version selector syntax (mainBranch, deployedOrReleased, matchingBranch) |
https://docs.pact.io/pact_broker/advanced_topics/consumer_version_selectors |
| Pending pact semantics |
https://docs.pact.io/pact_broker/advanced_topics/pending_pacts |
| Provider state setup hooks and state endpoint wiring |
https://docs.pact.io/getting_started/provider_states |
FastAPI TestClient and dependency_overrides for a test database |
https://fastapi.tiangolo.com/advanced/testing-dependencies/ |
GitHub Actions job ordering (needs:) and branch filters |
https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions |
| QA test-plan paperwork (schedule, roles, defect lifecycle, sign-off tables) |
Tracker-owned; no single vendor page covers all four. Defect lifecycle: https://docs.github.com/en/issues/tracking-your-work-with-issues/about-issues . Schedule, roles and sign-off are org process, not a documented product feature. House quality budgets from the retired template survive in references/ork-delta.md |
The house subset of those topics stays in this skill and is not routed away:
rules/verification-contract.md keeps the two broker commands ork gates on plus the selector
defaults; checklists/contract-testing-checklist.md keeps the CI/CD, isolation and security
checkboxes; references/consumer-tests.md keeps the business-language provider-state naming
convention and the matcher table. The rules that have no upstream home at all live in
references/ork-delta.md.
Stateful API Testing (emulate — FIRST CHOICE)
For GitHub, Vercel, and Google API integration tests, emulate is the first choice. It provides full state machines that model real API behavior — not static mocks.
| Tool |
Best For |
| emulate |
Stateful API tests (GitHub/Vercel/Google) — FIRST CHOICE |
| Pact |
Cross-team contract verification |
| MSW |
Frontend HTTP mocking (simple request/response) |
| Nock |
Node.js unit-level HTTP interception |
See rules/emulate-stateful-testing.md for the full decision matrix, seed-start-test-assert pattern, and incorrect/correct examples.
Testcontainers (real dependencies in CI)
When contract tests and emulate aren't enough — e.g. testing against real Postgres, Redis, Kafka, or an S3-compatible store — Testcontainers spins up ephemeral Docker containers per test and tears them down afterward. path_patterns above already matches **/testcontainers/**; use these patterns there.
Target: testcontainers >= 11.0.0 (Node) — v11 (Q1 2026) added named-network auto-cleanup, reusable containers via .withReuse(), and first-class Podman support.
Node.js (testcontainers-node)
import { PostgreSqlContainer } from '@testcontainers/postgresql'
import { describe, beforeAll, afterAll, test, expect } from 'vitest'
describe('UserRepository integration', () => {
let container: Awaited<ReturnType<PostgreSqlContainer['start']>>
let repo: UserRepository
beforeAll(async () => {
container = await new PostgreSqlContainer('postgres:16-alpine')
.withDatabase('test')
.withUsername('test')
.withPassword('test')
.withReuse() // v11+ — reuse across runs to speed CI
.start()
repo = new UserRepository(container.getConnectionUri())
await repo.migrate()
}, 30_000)
afterAll(async () => {
await container.stop()
})
test('persists and retrieves a user', async () => {
const created = await repo.create({ email: 'a@b.c' })
const found = await repo.findById(created.id)
expect(found?.email).toBe('a@b.c')
})
})
Python (testcontainers-python)
from testcontainers.postgres import PostgresContainer
import pytest
@pytest.fixture(scope="session")
def postgres():
with PostgresContainer("postgres:16-alpine") as pg:
yield pg.get_connection_url()
def test_user_repo(postgres):
repo = UserRepository(postgres)
repo.migrate()
user = repo.create(email="a@b.c")
assert repo.find_by_id(user.id).email == "a@b.c"
Decision matrix:
| Scenario |
Pick |
| Third-party API (GitHub, Vercel, Google) |
emulate |
| Cross-team API contract |
Pact |
| Real Postgres / Redis / Kafka integration |
Testcontainers |
| Just mocking HTTP in a frontend test |
MSW |
Quick Start: API Integration Test
TypeScript (Supertest)
import request from 'supertest';
import { app } from '../app';
describe('POST /api/users', () => {
test('creates user and returns 201', async () => {
const response = await request(app)
.post('/api/users')
.send({ email: 'test@example.com', name: 'Test' });
expect(response.status).toBe(201);
expect(response.body.id).toBeDefined();
expect(response.body.email).toBe('test@example.com');
});
test('returns 400 for invalid email', async () => {
const response = await request(app)
.post('/api/users')
.send({ email: 'invalid', name: 'Test' });
expect(response.status).toBe(400);
expect(response.body.error).toContain('email');
});
});
Python (FastAPI + httpx)
import pytest
from httpx import ASGITransport, AsyncClient
from app.main import app
@pytest.fixture
async def client():
async with AsyncClient(transport=ASGITransport(app=app), base_url="http://test") as ac:
yield ac
@pytest.mark.asyncio
async def test_create_user(client: AsyncClient):
response = await client.post(
"/api/users",
json={"email": "test@example.com", "name": "Test"}
)
assert response.status_code == 201
assert response.json()["email"] == "test@example.com"
Coverage Targets
| Area |
Target |
| API endpoints |
70%+ |
| Service layer |
80%+ |
| Component interactions |
70%+ |
| Contract tests |
All consumer-used endpoints |
| Property tests |
All encode/decode, idempotent functions |
Key Principles
- Test at boundaries -- API inputs, database queries, service calls, external integrations
- Fresh state per test -- In-memory databases, transaction rollback, no shared mutable state
- Use matchers in contracts --
Like(), EachLike(), Term() instead of exact values
- Property-based for invariants -- Roundtrip, idempotence, commutativity properties
- Validate schemas at edges -- Zod
.safeParse() at every API boundary
- Evidence-backed completion -- Exit code 0, coverage reports, timestamps
When to Use This Skill
- Writing API endpoint tests (Supertest, httpx)
- Setting up React component integration tests with providers
- Creating database integration tests with isolation
- Implementing Pact consumer/provider contract tests
- Adding property-based tests with Hypothesis
- Validating Zod schemas at API boundaries
- Planning a testing strategy for a new feature or service
Related Skills
ork:testing-unit — Unit testing patterns, fixtures, mocking
ork:testing-e2e — End-to-end Playwright tests
ork:emulate-seed — Seed configuration authoring for emulate providers
ork:database-patterns — Database schema and migration patterns
ork:api-design — API design patterns for endpoint testing
1---2name: testing-integration3license: MIT4compatibility: "Claude Code 2.1.277+."5description: "Integration and contract tests: API endpoints, databases, Pact contracts, property-based tests, Zod validation. Use when testing API or service boundaries."6user-invocable: false7disable-model-invocation: false8targets:9 - library: "@pact-foundation/pact"10 version: ">=17.1.4"11 - library: "testcontainers"12 version: ">=12.2.0"13metadata:14 source: https://skillmd.com/skills/yonatangross/testing-integration15 owner-agent: "test-generator"16 category: document-asset-creation17 version: "2.1.0"18 author: "OrchestKit"19 complexity: "medium"20 tags: "testing, integration, contract, pact, property, zod, api"21allowed-tools: "Read Glob Grep WebFetch WebSearch"22path_patterns: ["**/integration/**", "**/testcontainers/**", "docker-compose.test.*"]23---2425# Integration & Contract Testing2627Focused patterns for testing API boundaries, cross-service contracts, component integration, database layers, property-based verification, and schema validation.2829## Quick Reference3031> For complex emulate setups (full config generation, webhook HMAC, CI per-worker port isolation), delegate to the [`emulate-engineer`](../../agents/emulate-engineer.md) subagent. Pairs with the `emulate-seed` skill.3233| Area | Rule / Reference | Impact |34|------|-----------------|--------|35| **Stateful API testing (emulate)** | `rules/emulate-stateful-testing.md` | **HIGH** |36| API endpoint tests | `rules/integration-api.md` | HIGH |37| React component integration | `rules/integration-component.md` | HIGH |38| Database layer testing | `rules/integration-database.md` | HIGH |39| Zod schema validation | `rules/validation-zod-schema.md` | HIGH |40| Pact contract testing | `rules/verification-contract.md` | MEDIUM |41| Stateful testing (Hypothesis) | `rules/verification-stateful.md` | MEDIUM |42| Evidence & property-based | `rules/verification-techniques.md` | MEDIUM |4344### References4546| Topic | File |47|-------|------|48| **House rules not documented upstream** | `references/ork-delta.md` |49| Consumer-side Pact tests | `references/consumer-tests.md` |50| Hypothesis strategies guide | `references/strategies-guide.md` |5152### Checklists5354| Checklist | File |55|-----------|------|56| Contract testing readiness | `checklists/contract-testing-checklist.md` |57| Property-based testing | `checklists/property-testing-checklist.md` |5859### Scripts & Templates6061| Script | File |62|--------|------|63| Create integration test | `scripts/create-integration-test.md` |6465### Examples6667| Example | File |68|---------|------|69| Full testing strategy | `examples/orchestkit-test-strategy.md` |7071---7273## Upstream coverage (do not restate)7475This skill wraps Pact, the Pact Broker, and FastAPI testing. It carries only the OrchestKit76delta. Fetch the vendor docs for the topics below instead of restating them here.7778| Topic | First-party source |79|-------|--------------------|80| Pact Broker publish CLI, pact versioning and tagging flags | https://docs.pact.io/pact_broker/publishing_and_retrieving_pacts |81| `can-i-deploy`, `record-deployment`, `record-release` | https://docs.pact.io/pact_broker/can_i_deploy |82| Deployment and release recording semantics | https://docs.pact.io/pact_broker/recording_deployments_and_releases |83| Broker webhooks that trigger a provider build on contract change | https://docs.pact.io/pact_broker/webhooks |84| Consumer version selector syntax (`mainBranch`, `deployedOrReleased`, `matchingBranch`) | https://docs.pact.io/pact_broker/advanced_topics/consumer_version_selectors |85| Pending pact semantics | https://docs.pact.io/pact_broker/advanced_topics/pending_pacts |86| Provider state setup hooks and state endpoint wiring | https://docs.pact.io/getting_started/provider_states |87| FastAPI `TestClient` and `dependency_overrides` for a test database | https://fastapi.tiangolo.com/advanced/testing-dependencies/ |88| GitHub Actions job ordering (`needs:`) and branch filters | https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions |89| QA test-plan paperwork (schedule, roles, defect lifecycle, sign-off tables) | Tracker-owned; no single vendor page covers all four. Defect lifecycle: https://docs.github.com/en/issues/tracking-your-work-with-issues/about-issues . Schedule, roles and sign-off are org process, not a documented product feature. House quality budgets from the retired template survive in `references/ork-delta.md` |9091The house subset of those topics stays in this skill and is not routed away:92`rules/verification-contract.md` keeps the two broker commands ork gates on plus the selector93defaults; `checklists/contract-testing-checklist.md` keeps the CI/CD, isolation and security94checkboxes; `references/consumer-tests.md` keeps the business-language provider-state naming95convention and the matcher table. The rules that have no upstream home at all live in96`references/ork-delta.md`.9798---99100## Stateful API Testing (emulate — FIRST CHOICE)101102For GitHub, Vercel, and Google API integration tests, **emulate is the first choice**. It provides full state machines that model real API behavior — not static mocks.103104| Tool | Best For |105|------|----------|106| **emulate** | Stateful API tests (GitHub/Vercel/Google) — FIRST CHOICE |107| Pact | Cross-team contract verification |108| MSW | Frontend HTTP mocking (simple request/response) |109| Nock | Node.js unit-level HTTP interception |110111See `rules/emulate-stateful-testing.md` for the full decision matrix, seed-start-test-assert pattern, and incorrect/correct examples.112113---114115## Testcontainers (real dependencies in CI)116117When contract tests and emulate aren't enough — e.g. testing against real Postgres, Redis, Kafka, or an S3-compatible store — **Testcontainers** spins up ephemeral Docker containers per test and tears them down afterward. `path_patterns` above already matches `**/testcontainers/**`; use these patterns there.118119**Target**: `testcontainers >= 11.0.0` (Node) — v11 (Q1 2026) added named-network auto-cleanup, reusable containers via `.withReuse()`, and first-class Podman support.120121### Node.js (testcontainers-node)122123```typescript124import { PostgreSqlContainer } from '@testcontainers/postgresql'125import { describe, beforeAll, afterAll, test, expect } from 'vitest'126127describe('UserRepository integration', () => {128 let container: Awaited<ReturnType<PostgreSqlContainer['start']>>129 let repo: UserRepository130131 beforeAll(async () => {132 container = await new PostgreSqlContainer('postgres:16-alpine')133 .withDatabase('test')134 .withUsername('test')135 .withPassword('test')136 .withReuse() // v11+ — reuse across runs to speed CI137 .start()138139 repo = new UserRepository(container.getConnectionUri())140 await repo.migrate()141 }, 30_000)142143 afterAll(async () => {144 await container.stop()145 })146147 test('persists and retrieves a user', async () => {148 const created = await repo.create({ email: 'a@b.c' })149 const found = await repo.findById(created.id)150 expect(found?.email).toBe('a@b.c')151 })152})153```154155### Python (testcontainers-python)156157```python158from testcontainers.postgres import PostgresContainer159import pytest160161@pytest.fixture(scope="session")162def postgres():163 with PostgresContainer("postgres:16-alpine") as pg:164 yield pg.get_connection_url()165166def test_user_repo(postgres):167 repo = UserRepository(postgres)168 repo.migrate()169 user = repo.create(email="a@b.c")170 assert repo.find_by_id(user.id).email == "a@b.c"171```172173**Decision matrix**:174175| Scenario | Pick |176|----------|------|177| Third-party API (GitHub, Vercel, Google) | emulate |178| Cross-team API contract | Pact |179| Real Postgres / Redis / Kafka integration | **Testcontainers** |180| Just mocking HTTP in a frontend test | MSW |181182---183184## Quick Start: API Integration Test185186### TypeScript (Supertest)187188```typescript189import request from 'supertest';190import { app } from '../app';191192describe('POST /api/users', () => {193 test('creates user and returns 201', async () => {194 const response = await request(app)195 .post('/api/users')196 .send({ email: 'test@example.com', name: 'Test' });197198 expect(response.status).toBe(201);199 expect(response.body.id).toBeDefined();200 expect(response.body.email).toBe('test@example.com');201 });202203 test('returns 400 for invalid email', async () => {204 const response = await request(app)205 .post('/api/users')206 .send({ email: 'invalid', name: 'Test' });207208 expect(response.status).toBe(400);209 expect(response.body.error).toContain('email');210 });211});212```213214### Python (FastAPI + httpx)215216```python217import pytest218from httpx import ASGITransport, AsyncClient219from app.main import app220221@pytest.fixture222async def client():223 async with AsyncClient(transport=ASGITransport(app=app), base_url="http://test") as ac:224 yield ac225226@pytest.mark.asyncio227async def test_create_user(client: AsyncClient):228 response = await client.post(229 "/api/users",230 json={"email": "test@example.com", "name": "Test"}231 )232 assert response.status_code == 201233 assert response.json()["email"] == "test@example.com"234```235236---237238## Coverage Targets239240| Area | Target |241|------|--------|242| API endpoints | 70%+ |243| Service layer | 80%+ |244| Component interactions | 70%+ |245| Contract tests | All consumer-used endpoints |246| Property tests | All encode/decode, idempotent functions |247248---249250## Key Principles2512521. **Test at boundaries** -- API inputs, database queries, service calls, external integrations2532. **Fresh state per test** -- In-memory databases, transaction rollback, no shared mutable state2543. **Use matchers in contracts** -- `Like()`, `EachLike()`, `Term()` instead of exact values2554. **Property-based for invariants** -- Roundtrip, idempotence, commutativity properties2565. **Validate schemas at edges** -- Zod `.safeParse()` at every API boundary2576. **Evidence-backed completion** -- Exit code 0, coverage reports, timestamps258259---260261## When to Use This Skill262263- Writing API endpoint tests (Supertest, httpx)264- Setting up React component integration tests with providers265- Creating database integration tests with isolation266- Implementing Pact consumer/provider contract tests267- Adding property-based tests with Hypothesis268- Validating Zod schemas at API boundaries269- Planning a testing strategy for a new feature or service270271## Related Skills272273- `ork:testing-unit` — Unit testing patterns, fixtures, mocking274- `ork:testing-e2e` — End-to-end Playwright tests275- `ork:emulate-seed` — Seed configuration authoring for emulate providers276- `ork:database-patterns` — Database schema and migration patterns277- `ork:api-design` — API design patterns for endpoint testing