configure-integration-tests

/configure:integration-tests

检查并配置集成测试基础设施，用于测试服务交互、数据库和外部依赖项。

何时使用此技能

在以下情况下使用此技能……	在以下情况下使用其他方法……
使用 Supertest、pytest 或 Testcontainers 搭建集成测试基础设施	为特定端点编写单独的集成测试用例（使用 api-plugin:api-testing）
创建 docker-compose.test.yml，用于本地测试服务容器	运行现有集成测试（bun test、pytest -m integration）
审核集成测试设置是否完整（fixtures、工厂、CI）	配置单元测试运行器（改用 /configure:tests）
使用服务容器为 GitHub Actions 添加集成测试任务	调试某个具体的失败集成测试
在项目结构中将集成测试与单元测试分开	设置 API 契约测试（改用 /configure:api-tests）

上下文

• 项目根目录：!pwd
• Package 文件：!find . -maxdepth 1 \( -name 'package.json' -o -name 'pyproject.toml' -o -name 'Cargo.toml' -o -name 'go.mod' \)
• 集成测试目录：!find . -path '*/tests/*' -maxdepth 2 -type d -name 'integration'
• Docker Compose 测试文件：!find . -maxdepth 1 -name 'docker-compose.test.yml'
• Vitest 集成测试配置：!find . -maxdepth 1 -name 'vitest.integration.config.*'
• Supertest 依赖项：!find . -maxdepth 1 -name 'package.json' -exec grep -l 'supertest' {} +
• Testcontainers 依赖项：!find . -maxdepth 1 \( -name package.json -o -name pyproject.toml \) -exec grep -l 'testcontainers' {} +
• 项目规范：!find . -maxdepth 1 -name '.project-standards.yaml'

参数

从命令参数中解析：

• --check-only：报告合规状态，不做修改（CI/CD 模式）
• --fix：自动应用修复，不询问
• --framework <supertest|pytest|testcontainers>：覆盖框架检测结果

集成测试技术栈：

• JavaScript/TypeScript：Supertest + Testcontainers
• Python：pytest + testcontainers-python + httpx
• Rust：使用 #[ignore] 的 cargo test + testcontainers-rs
• Go：testing + testcontainers-go

与单元测试的主要区别：

• 集成测试会与真实的数据库、API 和服务交互
• 它们测试组件边界和数据流
• 通常需要测试夹具和清理操作

执行

执行此集成测试合规性检查：

步骤 1：检测现有集成测试基础设施

检查以下指标：

指标	组件	状态
tests/integration/ 目录	集成测试	存在
依赖项中的 testcontainers	容器测试	已配置
package.json 中的 supertest	HTTP 测试	已配置
docker-compose.test.yml	测试服务	存在
带有 integration 标记的 pytest.ini	pytest 集成测试	已配置

步骤 2：分析当前状态

检查集成测试设置是否完整：

测试组织：

• tests/integration/ 目录存在
• 集成测试与单元测试分开
• 存在测试夹具和工厂
• 存在数据库播种/迁移脚本

JavaScript/TypeScript（Supertest）：

• 已安装 supertest
• 已安装 @testcontainers/postgresql 或类似工具
• 已配置测试数据库
• 存在 API 端点测试
• 存在身份验证测试辅助工具

Python（pytest + testcontainers）：

• 已安装 testcontainers
• 已安装用于 HTTP 测试的 httpx 或 requests
• 已安装用于异步测试的 pytest-asyncio
• 已定义 integration 标记
• conftest.py 中存在数据库 fixtures

容器基础设施：

• 存在 docker-compose.test.yml
• 已定义测试数据库容器
• 已定义 Redis/缓存容器（如有需要）
• 已配置网络隔离

步骤 3：生成合规报告

打印格式化的合规报告：

Integration Testing Compliance Report
======================================
Project: [name]
Language: [TypeScript | Python | Rust | Go]

Test Organization:
  Integration directory    tests/integration/         [EXISTS | MISSING]
  Separated from unit      not in src/                [CORRECT | MIXED]
  Test fixtures            tests/fixtures/            [EXISTS | MISSING]
  Database seeds           tests/seeds/               [EXISTS | N/A]

Framework Setup:
  HTTP testing             supertest/httpx            [INSTALLED | MISSING]
  Container testing        testcontainers             [INSTALLED | MISSING]
  Async support            pytest-asyncio             [INSTALLED | N/A]

Infrastructure:
  docker-compose.test.yml  test services              [EXISTS | MISSING]
  Test database            PostgreSQL/SQLite          [CONFIGURED | MISSING]
  Service isolation        network config             [CONFIGURED | MISSING]

CI/CD Integration:
  Integration test job     GitHub Actions             [CONFIGURED | MISSING]
  Service containers       workflow services          [CONFIGURED | MISSING]

Overall: [X issues found]

Recommendations:
  - Install testcontainers for database testing
  - Create docker-compose.test.yml for local testing
  - Add integration test job to CI workflow

如果使用 --check-only，则到此为止。

步骤 4：配置集成测试（如果使用 --fix 或用户确认）

根据检测到的项目类型应用配置。使用 REFERENCE.md 中的模板：

1. 安装依赖项（supertest、testcontainers 等）
2. 创建测试目录（tests/integration/）及设置文件
3. 为 API 端点和数据库操作创建示例测试
4. 创建 Vitest 集成配置（JS/TS）或 pytest 标记（Python）
5. 在 package.json 中添加脚本或创建运行命令

步骤 5：创建容器基础设施

创建 docker-compose.test.yml，包含：

• PostgreSQL 测试数据库（使用 tmpfs 提升速度）
• Redis 测试实例（如有需要）
• 网络隔离

添加相应的 npm/bun 脚本以管理测试容器。使用 REFERENCE.md 中的模板。

步骤 6：配置 CI/CD 集成

在 .github/workflows/test.yml 中添加集成测试任务，包含：

• 服务容器（postgres、redis）
• 数据库迁移步骤
• 集成测试执行
• 测试结果制品上传

使用 REFERENCE.md 中的 CI 工作流模板。

步骤 7：创建测试夹具和工厂

创建 tests/fixtures/factories.ts（或对应的 Python 文件），包含：

• 使用 faker 的数据工厂函数
• 数据库填充辅助工具
• 清理实用工具

使用 REFERENCE.md 中的工厂模板。

步骤 8：更新标准跟踪

更新 .project-standards.yaml：

standards_version: "2025.1"
last_configured: "[timestamp]"
components:
  integration_tests: "2025.1"
  integration_tests_framework: "[supertest|pytest|testcontainers]"
  integration_tests_containers: true
  integration_tests_ci: true

步骤 9：打印最终报告

打印已应用的更改、添加的脚本以及运行集成测试后续步骤的摘要。

详细模板和代码示例请参阅 REFERENCE.md。

Agentic 优化

场景	命令
快速合规检查	/configure:integration-tests --check-only
自动修复所有问题	/configure:integration-tests --fix
运行集成测试（JS）	bun test tests/integration --dots --bail=1
运行集成测试（Python）	pytest -m integration -x -q
启动测试容器	docker compose -f docker-compose.test.yml up -d
检查容器健康状态	`docker compose -f docker-compose.test.yml ps --format json

标志

标志	描述
--check-only	报告状态，不提供修复方案
--fix	无需提示，自动应用所有修复
--framework <framework>	覆盖框架检测结果（supertest、pytest、testcontainers）

示例

# Check compliance and offer fixes
/configure:integration-tests

# Check only, no modifications
/configure:integration-tests --check-only

# Auto-fix all issues
/configure:integration-tests --fix

# Force specific framework
/configure:integration-tests --fix --framework pytest

错误处理

• 未找到应用入口点：请用户指定应用位置
• Docker 不可用：警告用户需要 testcontainers
• 数据库类型未知：请用户指定数据库类型
• 端口冲突：建议在 docker-compose 中使用其他端口

另请参阅

• /configure:tests - 单元测试配置
• api-plugin:api-testing - 编写此技能用于搭建基础设施的 Supertest / httpx+pytest 测试
• /configure:api-tests - API 契约测试
• /configure:coverage - 覆盖率配置
• /configure:all - 运行所有合规检查
• Testcontainers 文档：https://testcontainers.com
• Supertest 文档：https://github.com/ladjs/supertest