testing-integration

用途

此技能可促进 API 和服务的集成测试，重点介绍 Supertest（Node.js）、httpx（Python）、用于管理测试环境的 Testcontainers，以及用于契约测试的 Pact 等工具。它可确保对服务交互、数据库集成和 API 契约进行端到端验证。

使用时机

在真实环境中验证 API 端点、测试服务集成（例如与数据库或外部服务的集成）、运行容器化测试或强制执行微服务之间的契约时，请使用此技能。当模拟依赖项不足以满足需求时，也可在 CI/CD 流水线中将其用于回归测试。

主要功能

• 使用 Supertest 对 Node.js 应用进行 HTTP API 测试，包括模拟和断言。
• 在 Python 中使用 httpx 发送异步 HTTP 请求并与数据库集成。
• 通过 Testcontainers 管理测试容器，启动隔离环境（例如基于 Docker 的数据库）。
• 使用 Pact 进行契约测试，定义并验证 API 提供方与消费者之间的约定。
• 支持服务集成测试，例如将 API 与外部服务或数据库连接。

使用模式

要使用此技能，请先安装所需依赖项（例如通过 npm 或 pip）。在项目中设置测试文件，使用 $API_BASE_URL 等变量配置环境，然后通过测试运行器运行测试。对于 API 测试，应编写代码发送请求并断言响应。对于契约测试，应在单独文件中定义 Pact，并针对提供方进行验证。始终使用容器隔离测试，以避免副作用。示例模式：导入工具、定义测试函数、发送请求，并在 2-3 行内处理断言。

常用命令/API

• Supertest（Node.js）：使用 supertest 测试 Express 应用。命令：npm install supertest。代码片段：

  const request = require('supertest');
  const app = require('./app');
  request(app).get('/api/users').expect(200);
  

  CLI 标志：使用 npx jest --runInBand 顺序运行测试。
• httpx（Python）：用于异步 HTTP 测试。命令：pip install httpx。代码片段：

  import httpx
  response = httpx.get('http://example.com/api/data', headers={'Authorization': f'Bearer {os.environ.get("API_KEY")}'}).json()
  assert response['status'] == 'success'
  

  API 端点：传入 https://api.service.com/endpoint 等 URL，并附加查询参数（例如 ?limit=10）。
• Testcontainers：启动容器以进行集成测试。命令：添加到 pom.xml 或 requirements。代码片段：

  GenericContainer container = new GenericContainer("postgres:13").withExposedPorts(5432);
  container.start();
  String jdbcUrl = container.getJdbcUrl();
  

  配置格式：在 YAML 中使用 Docker 镜像规格，例如 image: postgres:13，并设置 $DB_PASSWORD 等环境变量。
• Pact（契约测试）：定义并验证契约。命令：npm install @pact-foundation/pact 或 pip install pact-python。代码片段：

  const { Pact } = require('@pact-foundation/pact');
  const pact = new Pact({ consumer: 'MyConsumer', provider: 'MyProvider' });
  pact.addInteraction({ state: 'default', uponReceiving: 'a request' });
  

  API：使用 /pacts/provider/MyProvider/consumer/MyConsumer/verification 等端点进行验证，并通过 $PACT_BROKER_TOKEN 进行身份验证。

集成说明

将此技能添加到构建工具中以完成集成：对于 Node.js，将其加入 Jest 或 Mocha 配置；对于 Python，使用 pytest fixtures。设置 $DATABASE_URL 等环境变量以连接数据库，或设置 $SERVICE_API_KEY 以发送经过身份验证的请求。对于容器集成，请确保已安装 Docker，并使用 Testcontainers 连接服务（例如，通过 withExposedPorts(8080) 暴露端口）。与 Pact 配合使用时，将 Pact 发布到 broker（例如，通过 pact-broker publish --broker-url=$PACT_BROKER_URL）。配置格式：Pact 文件使用 JSON，例如 { "interactions": [...] }，并通过添加 run: docker-compose up -d 等步骤，确保与 GitHub Actions 等 CI 工具兼容。

错误处理

将请求包装在 try-catch 块中以处理错误。对于 Supertest，请检查响应状态和响应正文：例如，如果 .expect(200) 失败，请使用 console.error(response.error) 记录错误。在 httpx 中，捕获 httpx.HTTPError 以处理网络问题，例如：

try:
    response = httpx.get(url)
    response.raise_for_status()
except httpx.HTTPError as e:
    print(f"Error: {e} - Check $API_BASE_URL")

对于 Testcontainers，请在测试前通过 container.isRunning() 确认容器已启动。在 Pact 中，使用 pact.verify()，并通过检查 Pact 文件处理不匹配问题。常见模式：使用环境变量设置重试次数（例如 $RETRY_COUNT=3），并记录包含堆栈跟踪的详细错误。

具体使用示例

1. 使用 Supertest 进行 API 集成测试：要在使用数据库的 Node.js 应用中测试用户端点，首先设置 $DB_URL=postgres://user:pass@localhost:5432/db。编写测试文件：导入 Supertest，发送 GET 请求并断言响应。运行 npx jest tests/integration.test.js。这可以验证 API 是否连接到数据库并返回数据。

2. 使用 Pact 进行契约测试：对于消费者与提供者的配置，在文件（例如 pacts/my-pact.json）中定义包含交互的 pact。使用 pact.verify() 对照提供者端点（例如 http://provider.com）进行验证，并传入 $PACT_BROKER_TOKEN。通过 npx pact-verifier --provider-base-url=$PROVIDER_URL 运行。这可以确保消费者的预期与提供者的实现相符。

图关系

• 关联到集群：“testing”（例如，与单元测试技能共享标签）。
• 通过集成测试标签连接到技能：“api-development”，用于 API 工作流。
• 通过契约测试标签链接到：“contract-management”，用于基于 Pact 的验证。
• 与“database-integration”相关联，因为数据库测试使用了测试容器。