testing-integration — Claude Code skill for API tests and setup
The testing-integration skill supports integration and contract tests for APIs, services, databases, and Zod schemas. It applies when testing API or service boundaries.
MIT 131 installs ★ 305 updated 2026-11-07
npx skills add yonatangross/orchestkit --skill testing-integration -a claude-codeWhat testing-integration does
The skill provides rules and reference material for testing APIs, database layers, and React components. It also covers Pact contracts, property-based and stateful testing, and Zod schema validation. For complex API emulation setups, it points to the emulate-engineer subagent.
For tests that use real dependencies, the skill describes Testcontainers: temporary Docker containers can run Postgres, Redis, Kafka, or an S3-compatible store, then be removed after the test. Its Node.js example uses @testcontainers/postgresql with Vitest. Docker is needed for this setup, since the dependencies run in containers.
What it helps with
- test an API endpoint through an integration test
- verify service contracts with Pact
- exercise the database layer in tests
- check Zod schemas and data properties
- run a test against Postgres in a container
Example prompts for the agent
- Write an integration test for this API endpoint.
- Add a Pact contract check between these services.
- Create a
UserRepositorytest using Postgres with Testcontainers.
How to install testing-integration
1Skills CLI (Vercel)
npx skills add yonatangross/orchestkit --skill testing-integration -a claude-code2Manually: put the files in place
~/.claude/skills/testing-integration/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/testing-integration/
1Skills CLI (Vercel)
npx skills add yonatangross/orchestkit --skill testing-integration -a codex2Manually: put the files in place
.agents/skills/testing-integration/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add yonatangross/orchestkit --skill testing-integration -a cursor2Manually: put the files in place
.cursor/skills/testing-integration/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install yonatangross/orchestkit src/skills/testing-integration2Manually: put the files in place
.github/skills/testing-integration/SKILL.md1Skills CLI (Vercel)
npx skills add yonatangross/orchestkit --skill testing-integration -a gemini-cli2Platform CLI
gemini skills install https://github.com/yonatangross/orchestkit --path src/skills/testing-integrationManually: put the files in place
.devin/skills/testing-integration/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add yonatangross/orchestkit --skill testing-integration -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about testing-integration
How do I install testing-integration in Claude Code?
Run npx skills add yonatangross/orchestkit --skill testing-integration -a claude-code. The skill file is at ~/.claude/skills/testing-integration/SKILL.md.
What does testing-integration do?
It provides guidance for integration and contract testing across APIs, services, and databases. The material covers Pact, property-based tests, and Zod schemas.
Does Testcontainers require Docker?
Yes. Testcontainers runs dependencies such as Postgres or Redis in temporary Docker containers and removes them after the test.
Source text
SKILL.md · MIT
---
name: testing-integration
license: MIT
compatibility: "Claude Code 2.1.277+."
description: "Integration and contract tests: API endpoints, databases, Pact contracts, property-based tests, Zod validation. Use when testing API or service boundaries."
user-invocable: false
disable-model-invocation: false
targets:
- library: "@pact-foundation/pact"
version: ">=17.1.4"
- library: "testcontainers"
version: ">=12.2.0"
metadata:
owner-agent: "test-generator"
category: document-asset-creation
version: "2.1.0"
author: "OrchestKit"
complexity: "medium"
tags: "testing, integration, contract, pact, property, zod, api"
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.
**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)
```typescript
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: '[email protected]' })
const found = await repo.findById(created.id)
expect(found?.email).toBe('[email protected]')
})
})
```
### Python (testcontainers-python)
```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="[email protected]")
assert repo.find_by_id(user.id).email == "[email protected]"
```
**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)
```typescript
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: '[email protected]', name: 'Test' });
expect(response.status).toBe(201);
expect(response.body.id).toBeDefined();
expect(response.body.email).toBe('[email protected]');
});
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)
```python
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": "[email protected]", "name": "Test"}
)
assert response.status_code == 201
assert response.json()["email"] == "[email protected]"
```
---
## 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
1. **Test at boundaries** -- API inputs, database queries, service calls, external integrations
2. **Fresh state per test** -- In-memory databases, transaction rollback, no shared mutable state
3. **Use matchers in contracts** -- `Like()`, `EachLike()`, `Term()` instead of exact values
4. **Property-based for invariants** -- Roundtrip, idempotence, commutativity properties
5. **Validate schemas at edges** -- Zod `.safeParse()` at every API boundary
6. **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
© OrchestKit · MIT · yonatangross/orchestkit