testing-integration

集成与契约测试

聚焦 API 边界、跨服务契约、组件集成、数据库层、基于属性的验证和架构验证的测试模式。

快速参考

对于复杂的 emulate 配置（生成完整配置、Webhook HMAC、CI 每个工作进程的端口隔离），请委派给 emulate-engineer 子 Agent。可与 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 测试计划文档（时间安排、角色、缺陷生命周期、签署表）	由 Tracker 管理；没有单一供应商页面涵盖全部四项。缺陷生命周期：https://docs.github.com/en/issues/tracking-your-work-with-issues/about-issues 。时间安排、角色和签署属于组织流程，并非有文档说明的产品功能。已退役模板中的内部质量预算保留在 references/ork-delta.md 中。

这些主题的内部子集仍保留在此技能中，不会被转到其他地方：rules/verification-contract.md 保留了 ork 门禁要求的两条 Broker 命令以及选择器默认值；checklists/contract-testing-checklist.md 保留了 CI/CD、隔离和安全复选项；references/consumer-tests.md 保留了业务语言的提供者状态命名约定和匹配器表。没有任何上游对应内容的规则位于 references/ork-delta.md 中。

---

有状态 API 测试（模拟 — 首选）

对于 GitHub、Vercel 和 Google API 集成测试，模拟是首选方案。它提供可模拟真实 API 行为的完整状态机，而非静态模拟。

工具	最适用场景
emulate	有状态 API 测试（GitHub/Vercel/Google）——首选
Pact	跨团队契约验证
MSW	前端 HTTP 模拟（简单请求/响应）
Nock	Node.js 单元级 HTTP 拦截

请参阅 rules/emulate-stateful-testing.md，了解完整的决策矩阵、seed-start-test-assert 模式以及错误/正确示例。

---

Testcontainers（CI 中的真实依赖项）

当契约测试和 emulate 不够用时，例如需要针对真实的 Postgres、Redis、Kafka 或兼容 S3 的存储进行测试，可使用 Testcontainers 为每项测试启动临时 Docker 容器，并在测试后将其销毁。上方的 path_patterns 已匹配 **/testcontainers/**；请在其中使用这些模式。

目标版本：testcontainers >= 11.0.0（Node）——v11（2026 年第一季度）新增了命名网络自动清理、通过 .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）
• 配置带有 providers 的 React 组件集成测试
• 创建隔离的数据库集成测试
• 实现 Pact 消费者/提供者契约测试
• 使用 Hypothesis 添加基于属性的测试
• 在 API 边界验证 Zod 架构
• 为新功能或服务规划测试策略

相关技能

• ork:testing-unit — 单元测试模式、夹具、模拟
• ork:testing-e2e — 端到端 Playwright 测试
• ork:emulate-seed — 为 emulate providers 编写种子配置
• ork:database-patterns — 数据库架构和迁移模式
• ork:api-design — 用于端点测试的 API 设计模式