testing-integration

統合テストとコントラクトテスト

API 境界、サービス間のコントラクト、コンポーネント統合、データベースレイヤー、プロパティベース検証、スキーマ検証をテストするための、目的に特化したパターンです。

クイックリファレンス

複雑な emulate のセットアップ（完全な設定生成、Webhook HMAC、CI でのワーカーごとのポート分離）については、emulate-engineer サブエージェントに委任してください。emulate-seed スキルと組み合わせて使用します。

領域	ルール／リファレンス	影響
ステートフル API テスト（emulate）	rules/emulate-stateful-testing.md	高
API エンドポイントテスト	rules/integration-api.md	高
React コンポーネント統合	rules/integration-component.md	高
データベースレイヤーのテスト	rules/integration-database.md	高
Zod スキーマ検証	rules/validation-zod-schema.md	高
Pact コントラクトテスト	rules/verification-contract.md	中
ステートフルテスト（Hypothesis）	rules/verification-stateful.md	中
エビデンスとプロパティベーステスト	rules/verification-techniques.md	中

リファレンス

トピック	ファイル
上流で文書化されていない独自ルール	references/ork-delta.md
コンシューマー側の Pact テスト	references/consumer-tests.md
Hypothesis ストラテジーガイド	references/strategies-guide.md

チェックリスト

チェックリスト	ファイル
コントラクトテストの準備状況	checklists/contract-testing-checklist.md
プロパティベーステスト	checklists/property-testing-checklist.md

スクリプトとテンプレート

スクリプト	ファイル
統合テストの作成	scripts/create-integration-test.md

例

例	ファイル
テスト戦略の全体像	examples/orchestkit-test-strategy.md

---

上流の対象範囲（ここでは繰り返さないでください）

このスキルは Pact、Pact Broker、FastAPI のテストを扱います。ここに含まれるのは OrchestKit 独自の差分のみです。以下のトピックについては、ここで説明を繰り返すのではなく、ベンダーのドキュメントを参照してください。

トピック	公式の情報源
Pact Broker の公開 CLI、Pact のバージョン管理およびタグ付けフラグ	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
デプロイおよびリリースの記録のセマンティクス	https://docs.pact.io/pact_broker/recording_deployments_and_releases
コントラクト変更時にプロバイダーのビルドをトリガーする Broker Webhook	https://docs.pact.io/pact_broker/webhooks
コンシューマーバージョンセレクターの構文（mainBranch、deployedOrReleased、matchingBranch）	https://docs.pact.io/pact_broker/advanced_topics/consumer_version_selectors
保留中の Pact のセマンティクス	https://docs.pact.io/pact_broker/advanced_topics/pending_pacts
プロバイダー状態のセットアップフックと状態エンドポイントの接続	https://docs.pact.io/getting_started/provider_states
テストデータベースに対する FastAPI の TestClient と dependency_overrides	https://fastapi.tiangolo.com/advanced/testing-dependencies/
GitHub Actions のジョブ順序（needs:）とブランチフィルター	https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions
QA テスト計画の書類（スケジュール、役割、バグのライフサイクル、承認表）	トラッカーが管理します。これらすべてを網羅する単一のベンダーページはありません。バグのライフサイクル：https://docs.github.com/en/issues/tracking-your-work-with-issues/about-issues 。スケジュール、役割、承認は組織のプロセスであり、文書化された製品機能ではありません。廃止されたテンプレートの品質予算は references/ork-delta.md に引き継がれています

これらのトピックのうち、OrchestKit 独自の対象範囲は引き続きこのスキルに含まれ、外部には委ねません。 rules/verification-contract.md には、ork が必須とする Broker コマンド 2 つとセレクターのデフォルトが記載されています。 checklists/contract-testing-checklist.md には CI/CD、分離、セキュリティのチェック項目が記載されています。references/consumer-tests.md には、ビジネス用語を使ったプロバイダー状態の命名規則とマッチャーの表が記載されています。上流に参照先のないルールは references/ork-delta.md に記載されています。

---

ステートフル API テスト（emulate — 第一候補）

GitHub、Vercel、Google API の統合テストでは、emulate を第一候補とします。静的なモックではなく、実際の API の動作をモデル化する完全なステートマシンを提供します。

ツール	最適な用途
emulate	ステートフル API テスト（GitHub/Vercel/Google） — 第一候補
Pact	チーム間のコントラクト検証
MSW	フロントエンドの HTTP モック（単純なリクエスト／レスポンス）
Nock	Node.js のユニットレベル HTTP インターセプト

完全な判断マトリックス、seed-start-test-assert パターン、誤った例と正しい例については rules/emulate-stateful-testing.md を参照してください。

---

Testcontainers（CI で実際の依存関係を使用）

コントラクトテストや emulate だけでは不十分な場合（たとえば、実際の Postgres、Redis、Kafka、または S3 互換ストアに対するテスト）には、Testcontainers がテストごとに一時的な Docker コンテナーを起動し、テスト後に破棄します。上記の path_patterns はすでに **/testcontainers/** に一致するため、そこでこれらのパターンを使用してください。

対象：testcontainers >= 11.0.0（Node）。v11（2026 年第 1 四半期）では、名前付きネットワークの自動クリーンアップ、.withReuse() によるコンテナーの再利用、Podman の正式サポートが追加されました。

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: '[email protected]' })
    const found = await repo.findById(created.id)
    expect(found?.email).toBe('[email protected]')
  })
})

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="[email protected]")
    assert repo.find_by_id(user.id).email == "[email protected]"

判断マトリックス：

シナリオ	選択肢
サードパーティ API（GitHub、Vercel、Google）	emulate
チーム間の API コントラクト	Pact
実際の Postgres／Redis／Kafka との統合	Testcontainers
フロントエンドのテストで HTTP をモックするだけ	MSW

---

クイックスタート：API 統合テスト

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: '[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）

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]"

---

カバレッジ目標

領域	目標
API エンドポイント	70% 以上
サービスレイヤー	80% 以上
コンポーネント間の連携	70% 以上
コントラクトテスト	コンシューマーが使用するすべてのエンドポイント
プロパティテスト	すべてのエンコード／デコード関数、および冪等関数

---

主な原則

1. 境界でテストする -- API 入力、データベースクエリ、サービス呼び出し、外部連携
2. テストごとに状態を新しくする -- インメモリデータベース、トランザクションのロールバック、共有の可変状態を避ける
3. コントラクトではマッチャーを使う -- 完全一致の値の代わりに Like()、EachLike()、Term() を使う
4. 不変条件にはプロパティベーステストを使う -- 往復、冪等性、可換性のプロパティ
5. 境界でスキーマを検証する -- すべての API 境界で Zod の .safeParse() を使う
6. 根拠に基づいて完了を確認する -- 終了コード 0、カバレッジレポート、タイムスタンプ

---

このスキルを使う場面

• API エンドポイントテストの作成（Supertest、httpx）
• プロバイダーを使った React コンポーネントの統合テストの設定
• 分離されたデータベース統合テストの作成
• Pact のコンシューマー／プロバイダーコントラクトテストの実装
• Hypothesis を使ったプロパティベーステストの追加
• API 境界での Zod スキーマの検証
• 新しい機能やサービスのテスト戦略の策定

関連スキル

• ork:testing-unit — 単体テストのパターン、フィクスチャ、モック
• ork:testing-e2e — エンドツーエンドの Playwright テスト
• ork:emulate-seed — エミュレートプロバイダー用のシード設定の作成
• ork:database-patterns — データベーススキーマとマイグレーションのパターン
• ork:api-design — エンドポイントテスト向けの API 設計パターン