/testing-integration

name: testing-integration
license: MIT
compatibility: "Claude Code 2.1.220+."
description: Integration and contract testing patterns — API endpoint tests, component integration, database testing, Pact contract verification, property-based testing, and Zod schema validation. Use when testing API boundaries, verifying contracts, or validating cross-service integration.
tags: [testing, integration, contract, pact, property, zod, api]
context: fork
agent: test-generator
version: 2.1.0
author: OrchestKit
user-invocable: false
disable-model-invocation: false
complexity: medium
persuasion-type: reference
targets:
  - library: "@pact-foundation/pact"
    version: ">=16.0.0"
  - library: "testcontainers"
    version: ">=11.0.0"
metadata:
  category: document-asset-creation
allowed-tools:
  - Read
  - Glob
  - Grep
  - WebFetch
  - WebSearch
path_patterns: ["**/integration/**", "**/testcontainers/**", "docker-compose.test.*"]

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`](../../agents/emulate-engineer.md) 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.

*