Imported from bedkillerspacex-boop/codex-skill-library (typescript-contract-tests/SKILL.md). Install upstream with npx skills add bedkillerspacex-boop/codex-skill-library --skill typescript-contract-tests. Copyright stays with the author.

TypeScript Contract Tests

Scope And Authorization

• In scope: Defining and verifying contracts between services/frontends your org owns.
• Out of scope: Scraping or burdening external APIs without permission.
• Prefer test environments and stubbed providers; protect broker if used.
• Redact PII from example payloads.
• Pair with typescript-contract-security for auth invariants and code-quality-standards.

When To Use

• Multiple teams shipping TS services that must not break each other.
• Frontend (React/Next) depending on BFF/OpenAPI.
• Migrating from only E2E to faster consumer-driven tests.
• Versioning breaking API changes with explicit contract negotiation.
• Generating types from OpenAPI and ensuring runtime still matches.

Do Not Use As Primary

Domain Focus

Contract styles

Workflow

1. Confirm scope and success criteria

1. Record consumer/provider pairs, auth mode, broker, CI.
2. Success: breaking field removal fails provider verify before deploy.
3. Define versioning policy (URL version vs headers).

2. Inventory interactions

rg -n "fetch\(|axios\.|@openapi" src --glob '*.ts*' | head
# List routes the consumer actually calls  -  not the entire OpenAPI

3. Write consumer tests

// Conceptual  -  keep payloads minimal
type Order = { id: string; status: "pending" | "paid" };

export async function getOrder(
  http: { get: (url: string) => Promise<{ status: number; data: Order }> },
  id: string,
): Promise<Order> {
  const res = await http.get(`/orders/${id}`);
  if (res.status !== 200) throw new Error(`order_fetch_failed:${res.status}`);
  return res.data;
}

Matchers: prefer type+regex over exact timestamps; avoid matching unused fields strictly if evolution needed (team policy).

4. Provider states and verification

states:
- "order 42 exists" -> insert fixture
- "order 42 missing" -> empty DB

pnpm vitest run tests/contracts/consumer
pnpm vitest run tests/contracts/provider-verify

5. OpenAPI path (schema-first)

# Generate types
pnpm openapi-typescript ./openapi.yaml -o src/gen/api.ts
# Validate responses in tests against schema (e.g. ajv)

6. CI integration

1. Consumer PR: run consumer tests; publish contract version.
2. Provider PR: verify all deployed consumer contracts.
3. Can-i-deploy style gate before production.

7. Hand off

1. Document who owns each interaction.
2. Add security negatives via typescript-contract-security.
3. Keep E2E thin smoke only.

Good / Bad

Output Checklist

• Consumer/provider matrix documented
• Core interactions under contract
• Provider states implemented
• CI publish + verify + deploy gate
• OpenAPI/types aligned if schema-first
• PII/secrets redacted from fixtures
• Security contracts linked
• code-quality-standards applied
• Residual risk noted

Rules

• Authorized services only.
• Contract tests complement, not replace, unit and selected E2E.
• Minimize fixtures; avoid brittle over-matching.
• Version breaking changes explicitly.
• Route security-specific invariants to the security contract skill.