@xulthekl/team-flow 0.32.2 → 0.34.0

package/skills/test-strategy/references/integration-test-contracts.md

@@ -0,0 +1,237 @@
+# Integration Test Contracts（集成测试契约）
+
+> 来源：glaf4-test social-test-contracts.md 的通用模式（v0.13 §58）
+> 用途：集成测试的组织方法论，contract-builder 生成矩阵时参考
+
+---
+
+## 一、核心概念
+
+**社交测试（Social Test）**：跨类/跨层交互的测试，需要声明式契约来明确测试边界和依赖。
+
+**契约的作用**：
+- 明确测试的输入和输出
+- 声明依赖的真实/mock/stub
+- 定义测试隔离和清理策略
+- 确保测试可重复和可维护
+
+---
+
+## 二、五种契约类型
+
+### 1. 入口契约（Entry Contract）
+
+**定义**：系统边界入口声明
+
+**内容**：
+- API 端点（URL、HTTP 方法、请求格式）
+- 消息队列（exchange、routingKey、消息格式）
+- 定时任务（cron 表达式、触发条件）
+
+**示例**：
+```markdown
+## 入口契约
+
+- API: `POST /api/users`
+- Content-Type: application/json
+- 请求体: `{ "name": "string", "email": "string" }`
+- 认证: Bearer Token
+```
+
+### 2. 协作者契约（Collaborator Contract）
+
+**定义**：依赖分级声明
+
+**分级**：
+| 级别 | 说明 | 使用场景 |
+|------|------|---------|
+| **真实（Real）** | 使用真实实现 | Repository 层、内部 Service |
+| **Mock** | 使用 mock 框架创建 | 外部 API、第三方服务 |
+| **Stub** | 使用固定返回值 | 简单依赖、配置服务 |
+
+**示例**：
+```markdown
+## 协作者契约
+
+| 协作者 | 级别 | 理由 |
+|--------|------|------|
+| UserRepository | Real | 测试真实持久化逻辑 |
+| EmailService | Mock | 外部服务，避免真实发送 |
+| ConfigService | Stub | 返回固定配置值 |
+```
+
+### 3. 数据契约（Data Contract）
+
+**定义**：测试数据规格声明
+
+**内容**：
+- 输入数据格式和约束
+- 输出数据格式和验证点
+- 测试数据准备方式
+
+**示例**：
+```markdown
+## 数据契约
+
+### 输入
+- name: string, 1-50 字符
+- email: string, 有效邮箱格式
+
+### 输出
+- User 对象，包含 id、name、email、createdAt
+- id: 雪花算法生成，非空
+- createdAt: 当前时间，非空
+
+### 准备方式
+- 使用 Builder 模式构建测试数据
+- 每个测试独立数据，避免共享状态
+```
+
+### 4. 中间件契约（Middleware Contract）
+
+**定义**：基础设施交互规格
+
+**内容**：
+| 中间件 | 交互方式 | 测试策略 |
+|--------|---------|---------|
+| **数据库** | SQL 查询/写入 | H2 内存库 / @Transactional 回滚 |
+| **消息队列** | 发送/接收消息 | rabbitmq-mock / embedded broker |
+| **缓存** | 读写 Redis | embedded-redis / mock |
+| **外部 HTTP** | 调用第三方 API | MockWebServer / WireMock |
+
+**示例**：
+```markdown
+## 中间件契约
+
+| 中间件 | 交互 | 测试策略 |
+|--------|------|---------|
+| MySQL | INSERT/SELECT | H2 内存库，@Transactional 回滚 |
+| RabbitMQ | 发送用户创建事件 | rabbitmq-mock |
+| Redis | 缓存用户信息 | embedded-redis (port 6378) |
+| 支付网关 | 调用支付 API | MockWebServer |
+```
+
+### 5. 清理契约（Cleanup Contract）
+
+**定义**：测试隔离清理声明
+
+**原则**：
+- 每个测试独立，不共享状态
+- 测试后清理所有创建的数据
+- 异步操作需要等待完成
+
+**策略**：
+| 场景 | 清理方式 |
+|------|---------|
+| **同步操作** | @Transactional 自动回滚 |
+| **异步操作** | 手动清理（@AfterEach） |
+| **消息队列** | 清空队列 |
+| **缓存** | 清空 key |
+
+**示例**：
+```markdown
+## 清理契约
+
+- 数据库：@Transactional 自动回滚
+- 消息队列：@AfterEach 清空队列
+- 缓存：@AfterEach 清空测试 key
+- ThreadLocal：@AfterEach 清理 TraceIdHolder
+```
+
+---
+
+## 三、契约声明格式
+
+在 test-matrix.md 的集成测试 case 中，使用以下格式声明契约：
+
+```markdown
+| ID | work_mode | test_tier | design_method | description | priority | mock |
+|----|-----------|-----------|---------------|-------------|----------|------|
+| TC-010 | TDD | integration | equivalence | [contract] 创建用户：POST /api/users | P0 | entry:POST /api/users, collaborator:EmailService=Mock, data:User{name,email}, cleanup:@Transactional |
+```
+
+**字段说明**：
+- `entry`: 入口契约
+- `collaborator`: 协作者契约（Real/Mock/Stub）
+- `data`: 数据契约
+- `middleware`: 中间件契约
+- `cleanup`: 清理契约
+
+---
+
+## 四、矩阵生成指南
+
+### contract-builder 生成集成测试矩阵时：
+
+1. **识别入口**：从 specs/*.md 中提取 API 端点、消息队列、定时任务
+2. **分析依赖**：从代码中识别所有依赖，按真实/mock/stub 分级
+3. **定义数据**：明确输入输出数据格式
+4. **选择中间件**：识别涉及的基础设施，选择测试策略
+5. **设计清理**：根据操作类型（同步/异步）设计清理策略
+
+### 示例：用户注册功能
+
+```markdown
+## 集成测试矩阵
+
+### TC-010: 创建用户成功
+- 入口：POST /api/users
+- 协作者：UserRepository=Real, EmailService=Mock
+- 数据：{name:"John", email:"john@example.com"}
+- 中间件：MySQL=H2
+- 清理：@Transactional
+
+### TC-011: 创建用户失败（邮箱已存在）
+- 入口：POST /api/users
+- 协作者：UserRepository=Real（预先插入重复数据）
+- 数据：{name:"John", email:"existing@example.com"}
+- 中间件：MySQL=H2
+- 清理：@Transactional
+- 预期：409 Conflict
+
+### TC-012: 创建用户后发送欢迎邮件
+- 入口：POST /api/users
+- 协作者：UserRepository=Real, EmailService=Mock
+- 数据：{name:"John", email:"john@example.com"}
+- 中间件：MySQL=H2, RabbitMQ=rabbitmq-mock
+- 清理：@Transactional + 清空队列
+- 验证：EmailService.sendWelcomeEmail() 被调用
+```
+
+---
+
+## 五、最佳实践
+
+### 1. 契约最小化
+- 只声明必要的契约
+- 避免过度 mock（内部依赖尽量用真实实现）
+
+### 2. 契约可读性
+- 使用表格格式，清晰易读
+- 提供理由说明（为什么选择 Mock/Stub）
+
+### 3. 契约可维护性
+- 契约与测试代码同步更新
+- 定期审查契约的有效性
+
+### 4. 契约复用
+- 相似功能的契约可以复用
+- 提取公共契约模板
+
+---
+
+## 六、与 test-strategy 的关系
+
+集成测试契约是 test-strategy §1（Design Method 选择规则）的补充：
+- **基础级**（equivalence/boundary/error）：适用于所有测试
+- **扩展级**（path/state/exception/reject）：条件触发
+- **高级**（permission/idempotency/concurrency/contract）：场景触发
+  - **contract**：跨模块/跨服务接口契约，需要声明集成测试契约
+
+---
+
+## 变更记录
+
+| 日期 | 版本 | 变更内容 |
+|------|------|---------|
+| 2026-08-04 | v1.0 | 从 glaf4-test social-test-contracts.md 抽取通用模式 |

package/skills/test-strategy/references/integration-test-isolation.md

@@ -0,0 +1,346 @@
+# Integration Test Isolation（集成测试隔离分级）
+
+> 来源：glaf4-test h2-rabbitmq-redis.md 的隔离策略（v0.13 §59）
+> 用途：集成测试的分层策略，write-integration-worker 参考
+
+---
+
+## 一、核心原则
+
+**测试隔离**：每个测试独立运行，不依赖其他测试的状态，不污染共享资源。
+
+**隔离级别**：
+- **L1：进程内隔离**（最严格）：H2、embedded-redis、rabbitmq-mock
+- **L2：事务隔离**：@Transactional 自动回滚
+- **L3：手动清理**：@AfterEach 手动清理资源
+- **L4：无隔离**（最宽松）：共享真实基础设施（仅限开发环境）
+
+---
+
+## 二、基础设施隔离策略
+
+### 1. 数据库（MySQL/PostgreSQL）
+
+| 策略 | 适用场景 | 实现方式 | 优缺点 |
+|------|---------|---------|--------|
+| **H2 内存库** | Repository 层测试 | `@DataJpaTest` + H2 依赖 | ✅ 快速、隔离 ❌ SQL 兼容性差异 |
+| **@Transactional** | Service 层测试 | 测试类加 `@Transactional` | ✅ 自动回滚 ❌ 异步操作不适用 |
+| **Testcontainers** | 需要真实数据库 | Docker 容器 | ✅ 真实环境 ❌ 慢、需要 Docker |
+
+**推荐**：
+- Repository 层：H2 内存库
+- Service 层：@Transactional（同步操作）
+- API 层：@Transactional 或 Testcontainers
+
+**H2 配置示例**：
+```yaml
+# application-test.yml
+spring:
+  datasource:
+    url: jdbc:h2:mem:testdb;MODE=MySQL;DATABASE_TO_UPPER=false
+    driver-class-name: org.h2.Driver
+  jpa:
+    hibernate:
+      ddl-auto: create-drop
+```
+
+### 2. 消息队列（RabbitMQ/Kafka）
+
+| 策略 | 适用场景 | 实现方式 | 优缺点 |
+|------|---------|---------|--------|
+| **rabbitmq-mock** | MQ 生产者测试 | `MockConnectionFactory` | ✅ 快速、隔离 ❌ 不测试真实 MQ |
+| **embedded broker** | MQ 消费者测试 | embedded-rabbitmq | ✅ 真实协议 ❌ 慢、资源占用 |
+| **Testcontainers** | 端到端测试 | Docker 容器 | ✅ 真实环境 ❌ 慢、需要 Docker |
+
+**推荐**：
+- 生产者：rabbitmq-mock
+- 消费者：embedded broker 或 Testcontainers
+
+**rabbitmq-mock 配置示例**：
+```java
+@Configuration
+public class RabbitMockConfig {
+    @Bean
+    public ConnectionFactory connectionFactory() {
+        return new MockConnectionFactory();
+    }
+}
+```
+
+### 3. 缓存（Redis）
+
+| 策略 | 适用场景 | 实现方式 | 优缺点 |
+|------|---------|---------|--------|
+| **embedded-redis** | 缓存测试 | embedded-redis（port 6378） | ✅ 真实协议 ❌ ARM64 兼容问题 |
+| **mock** | 简单缓存逻辑 | Mockito mock | ✅ 快速 ❌ 不测试真实 Redis |
+| **Testcontainers** | 端到端测试 | Docker 容器 | ✅ 真实环境 ❌ 慢、需要 Docker |
+
+**推荐**：
+- 简单缓存逻辑：mock
+- 复杂缓存逻辑：embedded-redis
+
+**embedded-redis 配置示例**：
+```java
+@Configuration
+public class RedisTestConfig {
+    @Bean
+    public RedisServer redisServer() throws IOException {
+        RedisServer server = new RedisServer(6378);
+        server.start();
+        return server;
+    }
+}
+```
+
+### 4. 外部 HTTP（第三方 API）
+
+| 策略 | 适用场景 | 实现方式 | 优缺点 |
+|------|---------|---------|--------|
+| **MockWebServer** | HTTP 客户端测试 | OkHttp MockWebServer | ✅ 真实 HTTP 协议 ❌ 只测试客户端 |
+| **WireMock** | 复杂 API 模拟 | WireMock | ✅ 强大的模拟能力 ❌ 学习成本 |
+| **@MockBean** | Spring Cloud Feign | Mockito mock | ✅ 简单 ❌ 不测试真实 HTTP |
+
+**推荐**：
+- 简单 HTTP 客户端：MockWebServer
+- 复杂 API 模拟：WireMock
+- Feign 客户端：@MockBean
+
+**MockWebServer 配置示例**：
+```java
+@Test
+void testCallExternalApi() throws Exception {
+    MockWebServer server = new MockWebServer();
+    server.enqueue(new MockResponse()
+        .setBody("{\"status\":\"ok\"}")
+        .setHeader("Content-Type", "application/json"));
+
+    // 调用被测方法
+    String result = externalService.callApi();
+
+    // 验证请求
+    RecordedRequest request = server.takeRequest();
+    assertEquals("/api/data", request.getPath());
+    assertEquals("ok", result);
+
+    server.shutdown();
+}
+```
+
+---
+
+## 三、分层隔离策略
+
+### Repository 层
+
+**策略**：H2 内存库 + @Transactional
+
+**理由**：
+- Repository 层只测试 SQL 和映射逻辑
+- H2 内存库提供快速、隔离的测试环境
+- @Transactional 确保测试后数据回滚
+
+**示例**：
+```java
+@DataJpaTest
+@Transactional
+class UserRepositoryTest {
+    @Autowired
+    private UserRepository userRepository;
+
+    @Test
+    void testFindByEmail() {
+        // Arrange
+        User user = new User("John", "john@example.com");
+        userRepository.save(user);
+
+        // Act
+        Optional<User> found = userRepository.findByEmail("john@example.com");
+
+        // Assert
+        assertTrue(found.isPresent());
+        assertEquals("John", found.get().getName());
+    }
+    // 测试结束后自动回滚
+}
+```
+
+### Service 层
+
+**策略**：@Transactional（同步操作）或手动清理（异步操作）
+
+**理由**：
+- Service 层测试业务逻辑，需要真实依赖
+- 同步操作用 @Transactional 自动回滚
+- 异步操作需要手动清理（消息队列、缓存）
+
+**示例（同步）**：
+```java
+@SpringBootTest
+@Transactional
+class UserServiceTest {
+    @Autowired
+    private UserService userService;
+
+    @Autowired
+    private UserRepository userRepository;
+
+    @Test
+    void testCreateUser() {
+        // Arrange
+        CreateUserRequest request = new CreateUserRequest("John", "john@example.com");
+
+        // Act
+        User user = userService.createUser(request);
+
+        // Assert
+        assertNotNull(user.getId());
+        assertEquals("John", user.getName());
+    }
+    // 测试结束后自动回滚
+}
+```
+
+**示例（异步）**：
+```java
+@SpringBootTest
+class UserServiceAsyncTest {
+    @Autowired
+    private UserService userService;
+
+    @Autowired
+    private RabbitTemplate rabbitTemplate;
+
+    @AfterEach
+    void cleanup() {
+        // 手动清空消息队列
+        rabbitTemplate.execute(channel -> {
+            channel.queuePurge("user-events");
+            return null;
+        });
+    }
+
+    @Test
+    void testCreateUserSendsEvent() {
+        // Arrange
+        CreateUserRequest request = new CreateUserRequest("John", "john@example.com");
+
+        // Act
+        User user = userService.createUser(request);
+
+        // Assert
+        assertNotNull(user.getId());
+
+        // 验证消息发送
+        Message message = rabbitTemplate.receive("user-events", 1000);
+        assertNotNull(message);
+    }
+}
+```
+
+### API 层
+
+**策略**：MockMvc + @Transactional 或 Testcontainers
+
+**理由**：
+- API 层测试 HTTP 请求和响应
+- 使用 MockMvc 模拟 HTTP 请求
+- 数据库用 @Transactional 或 Testcontainers
+
+**示例**：
+```java
+@WebMvcTest(UserController.class)
+@Transactional
+class UserControllerTest {
+    @Autowired
+    private MockMvc mockMvc;
+
+    @MockBean
+    private UserService userService;
+
+    @Test
+    void testCreateUser() throws Exception {
+        // Arrange
+        User user = new User(1L, "John", "john@example.com");
+        when(userService.createUser(any())).thenReturn(user);
+
+        // Act & Assert
+        mockMvc.perform(post("/api/users")
+                .contentType(MediaType.APPLICATION_JSON)
+                .content("{\"name\":\"John\",\"email\":\"john@example.com\"}"))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.name").value("John"));
+    }
+}
+```
+
+---
+
+## 四、隔离级别选择指南
+
+| 测试类型 | 隔离级别 | 推荐策略 |
+|---------|---------|---------|
+| **Repository 层** | L1 | H2 内存库 |
+| **Service 层（同步）** | L2 | @Transactional |
+| **Service 层（异步）** | L3 | 手动清理 |
+| **API 层（简单）** | L2 | MockMvc + @Transactional |
+| **API 层（复杂）** | L1 | MockMvc + H2 |
+| **端到端** | L1 | Testcontainers |
+
+---
+
+## 五、常见问题和解决方案
+
+### 1. 异步操作测试
+
+**问题**：@Transactional 不适用于异步操作（消息队列、异步方法）
+
+**解决方案**：
+- 使用 @AfterEach 手动清理
+- 使用 Awaitility 等待异步操作完成
+- 使用 embedded broker 替代 mock
+
+### 2. 外部依赖测试
+
+**问题**：外部 API 不可用或不稳定
+
+**解决方案**：
+- 使用 MockWebServer/WireMock 模拟外部 API
+- 使用 @MockBean mock Feign 客户端
+- 使用 Testcontainers 运行真实服务
+
+### 3. 测试数据污染
+
+**问题**：测试数据泄漏到其他测试
+
+**解决方案**：
+- 每个测试独立数据（Builder 模式）
+- 使用 @Transactional 自动回滚
+- 使用 @DirtContexts 标记需要重新加载上下文的测试
+
+### 4. 测试速度慢
+
+**问题**：Testcontainers 启动慢
+
+**解决方案**：
+- 使用 @Testcontainers 的 reuse 模式
+- 使用 H2 替代真实数据库（Repository 层）
+- 使用 mock 替代真实外部服务
+
+---
+
+## 六、与 glaf4-test 的关系
+
+本隔离策略参考了 glaf4-test 的以下规范：
+- **H2 替代 MySQL**：`MERGE INTO ... KEY(id)` 幂等写法、`MODE=MySQL;DATABASE_TO_UPPER=false`
+- **rabbitmq-mock**：`MockConnectionFactory → CachingConnectionFactory → firstRabbitTemplate`
+- **embedded-redis**：端口 6378、`@AutoConfigureBefore` Redisson config
+
+**注意**：glaf4-test 的部分配置是 GLAF4 框架专用的（如 `gtmc.glaf4.*` 配置键），本规范已抽象为通用模式。
+
+---
+
+## 变更记录
+
+| 日期 | 版本 | 变更内容 |
+|------|------|---------|
+| 2026-08-04 | v1.0 | 从 glaf4-test h2-rabbitmq-redis.md 抽取通用隔离策略 |