@llryiop/avatar-boot-cli 1.0.0

package/templates/.claude/skills/integration-test-generator/SKILL.md

@@ -0,0 +1,496 @@
+---
+name: integration-test-generator
+description: |
+  集成测试生成技能。当用户提到以下关键词时触发：
+  integration test, 集成测试, SpringBootTest, MockMvc,
+  TestContainers, 端到端测试, E2E test, 接口测试
+
+  本技能提供 Spring Boot 集成测试的完整模板，包括 @SpringBootTest 配置、
+  MockMvc 控制器测试、@MockBean 服务模拟、TestContainers 外部依赖集成、
+  测试数据管理和断言模式等。
+---
+
+# 集成测试生成技能
+
+## 适用场景
+
+- 为 Controller 层生成集成测试
+- 测试接口的完整请求-响应链路
+- 使用 TestContainers 测试数据库/缓存集成
+- 验证 Spring 上下文的正确装配
+
+## @SpringBootTest 基础模板
+
+### 最小配置
+
+```java
+@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT)
+@AutoConfigureMockMvc
+@ActiveProfiles("test")
+class UserControllerIntegrationTest {
+
+    @Autowired
+    private MockMvc mockMvc;
+
+    @Autowired
+    private ObjectMapper objectMapper;
+
+    @Test
+    @DisplayName("创建用户集成测试 - 完整链路")
+    void should_create_user_successfully() throws Exception {
+        // Given
+        UserInfoCreateDTO dto = new UserInfoCreateDTO();
+        dto.setUsername("integration_test_user");
+        dto.setPhone("13812345678");
+        dto.setEmail("test@example.com");
+
+        // When & Then
+        mockMvc.perform(post("/api/users")
+                .contentType(MediaType.APPLICATION_JSON)
+                .content(objectMapper.writeValueAsString(dto)))
+            .andExpect(status().isOk())
+            .andExpect(jsonPath("$.code").value(0))
+            .andExpect(jsonPath("$.data").isNumber());
+    }
+}
+```
+
+### 测试配置文件
+
+```yaml
+# src/test/resources/application-test.yml
+spring:
+  datasource:
+    url: jdbc:h2:mem:testdb;DB_CLOSE_DELAY=-1;MODE=MySQL
+    driver-class-name: org.h2.Driver
+    username: sa
+    password:
+  sql:
+    init:
+      mode: always
+      schema-locations: classpath:schema-test.sql
+
+mybatis-plus:
+  mapper-locations: classpath*:/mapper/**/*.xml
+  configuration:
+    log-impl: org.apache.ibatis.logging.stdout.StdOutImpl
+```
+
+## MockMvc Controller 测试
+
+### GET 请求测试
+
+```java
+@Test
+@DisplayName("根据ID查询用户 - 用户存在时返回用户信息")
+void should_return_user_when_id_exists() throws Exception {
+    // Given - 预置测试数据
+    Long userId = prepareTestUser("testuser", "13800000001");
+
+    // When & Then
+    mockMvc.perform(get("/api/users/{id}", userId)
+            .accept(MediaType.APPLICATION_JSON))
+        .andExpect(status().isOk())
+        .andExpect(jsonPath("$.code").value(0))
+        .andExpect(jsonPath("$.data.username").value("testuser"))
+        .andExpect(jsonPath("$.data.phone").value("138****0001"))
+        .andDo(print());  // 打印请求响应详情，便于调试
+}
+
+@Test
+@DisplayName("根据ID查询用户 - 用户不存在时返回错误")
+void should_return_error_when_id_not_exists() throws Exception {
+    mockMvc.perform(get("/api/users/{id}", 999999L)
+            .accept(MediaType.APPLICATION_JSON))
+        .andExpect(status().isOk())
+        .andExpect(jsonPath("$.code").value(not(0)))
+        .andExpect(jsonPath("$.message").isNotEmpty());
+}
+```
+
+### POST 请求测试
+
+```java
+@Test
+@DisplayName("创建用户 - 参数校验失败时返回400")
+void should_return_400_when_validation_fails() throws Exception {
+    // Given - 缺少必填字段
+    UserInfoCreateDTO dto = new UserInfoCreateDTO();
+    dto.setUsername("");  // 用户名为空
+
+    // When & Then
+    mockMvc.perform(post("/api/users")
+            .contentType(MediaType.APPLICATION_JSON)
+            .content(objectMapper.writeValueAsString(dto)))
+        .andExpect(status().isBadRequest());
+}
+```
+
+### 分页查询测试
+
+```java
+@Test
+@DisplayName("分页查询用户列表")
+void should_return_paged_users() throws Exception {
+    // Given - 准备多条测试数据
+    for (int i = 0; i < 15; i++) {
+        prepareTestUser("user_" + i, "1380000" + String.format("%04d", i));
+    }
+
+    UserInfoPageQueryDTO queryDTO = new UserInfoPageQueryDTO();
+    queryDTO.setPageNum(1);
+    queryDTO.setPageSize(10);
+
+    // When & Then
+    mockMvc.perform(post("/api/users/page")
+            .contentType(MediaType.APPLICATION_JSON)
+            .content(objectMapper.writeValueAsString(queryDTO)))
+        .andExpect(status().isOk())
+        .andExpect(jsonPath("$.code").value(0))
+        .andExpect(jsonPath("$.data.records").isArray())
+        .andExpect(jsonPath("$.data.records.length()").value(10))
+        .andExpect(jsonPath("$.data.total").value(15))
+        .andExpect(jsonPath("$.data.pages").value(2));
+}
+```
+
+### PUT 请求测试
+
+```java
+@Test
+@DisplayName("更新用户信息")
+void should_update_user_successfully() throws Exception {
+    // Given
+    Long userId = prepareTestUser("old_name", "13800000001");
+    UserInfoUpdateDTO dto = new UserInfoUpdateDTO();
+    dto.setUsername("new_name");
+    dto.setEmail("new@example.com");
+
+    // When & Then
+    mockMvc.perform(put("/api/users/{id}", userId)
+            .contentType(MediaType.APPLICATION_JSON)
+            .content(objectMapper.writeValueAsString(dto)))
+        .andExpect(status().isOk())
+        .andExpect(jsonPath("$.code").value(0));
+
+    // 验证数据库中已更新
+    mockMvc.perform(get("/api/users/{id}", userId))
+        .andExpect(jsonPath("$.data.username").value("new_name"))
+        .andExpect(jsonPath("$.data.email").value("new@example.com"));
+}
+```
+
+### DELETE 请求测试
+
+```java
+@Test
+@DisplayName("删除用户")
+void should_delete_user_successfully() throws Exception {
+    // Given
+    Long userId = prepareTestUser("to_delete", "13800000001");
+
+    // When
+    mockMvc.perform(delete("/api/users/{id}", userId))
+        .andExpect(status().isOk())
+        .andExpect(jsonPath("$.code").value(0));
+
+    // Then - 验证已删除
+    mockMvc.perform(get("/api/users/{id}", userId))
+        .andExpect(jsonPath("$.code").value(not(0)));
+}
+```
+
+## @MockBean 服务模拟
+
+当需要隔离外部依赖（如第三方服务调用）时使用 `@MockBean`：
+
+```java
+@SpringBootTest
+@AutoConfigureMockMvc
+@ActiveProfiles("test")
+class OrderControllerIntegrationTest {
+
+    @Autowired
+    private MockMvc mockMvc;
+
+    @Autowired
+    private ObjectMapper objectMapper;
+
+    @MockBean
+    private PaymentFeignClient paymentFeignClient;
+
+    @MockBean
+    private SmsService smsService;
+
+    @Test
+    @DisplayName("创建订单 - 模拟支付服务成功")
+    void should_create_order_when_payment_succeeds() throws Exception {
+        // Given - 模拟外部服务
+        when(paymentFeignClient.createPayment(any()))
+            .thenReturn(Result.success(new PaymentVO("PAY202301010001")));
+        doNothing().when(smsService).sendOrderNotification(any());
+
+        OrderCreateDTO dto = new OrderCreateDTO();
+        dto.setProductId(1L);
+        dto.setQuantity(2);
+
+        // When & Then
+        mockMvc.perform(post("/api/orders")
+                .contentType(MediaType.APPLICATION_JSON)
+                .content(objectMapper.writeValueAsString(dto)))
+            .andExpect(status().isOk())
+            .andExpect(jsonPath("$.code").value(0))
+            .andExpect(jsonPath("$.data.orderId").isNotEmpty());
+
+        // 验证外部服务被调用
+        verify(paymentFeignClient, times(1)).createPayment(any());
+        verify(smsService, times(1)).sendOrderNotification(any());
+    }
+
+    @Test
+    @DisplayName("创建订单 - 支付服务超时时应回滚")
+    void should_rollback_when_payment_timeout() throws Exception {
+        // Given
+        when(paymentFeignClient.createPayment(any()))
+            .thenThrow(new FeignException.GatewayTimeout("支付服务超时", null, null, null));
+
+        OrderCreateDTO dto = new OrderCreateDTO();
+        dto.setProductId(1L);
+        dto.setQuantity(2);
+
+        // When & Then
+        mockMvc.perform(post("/api/orders")
+                .contentType(MediaType.APPLICATION_JSON)
+                .content(objectMapper.writeValueAsString(dto)))
+            .andExpect(status().isOk())
+            .andExpect(jsonPath("$.code").value(not(0)))
+            .andExpect(jsonPath("$.message").value(containsString("支付")));
+    }
+}
+```
+
+## TestContainers 集成
+
+### 依赖配置
+
+```xml
+<!-- pom.xml -->
+<dependency>
+    <groupId>org.testcontainers</groupId>
+    <artifactId>testcontainers</artifactId>
+    <scope>test</scope>
+</dependency>
+<dependency>
+    <groupId>org.testcontainers</groupId>
+    <artifactId>mysql</artifactId>
+    <scope>test</scope>
+</dependency>
+<dependency>
+    <groupId>org.testcontainers</groupId>
+    <artifactId>junit-jupiter</artifactId>
+    <scope>test</scope>
+</dependency>
+```
+
+### MySQL TestContainer
+
+```java
+@SpringBootTest
+@AutoConfigureMockMvc
+@Testcontainers
+class UserRepositoryIntegrationTest {
+
+    @Container
+    static MySQLContainer<?> mysql = new MySQLContainer<>("mysql:8.0")
+        .withDatabaseName("test_db")
+        .withUsername("test")
+        .withPassword("test")
+        .withInitScript("schema-test.sql");
+
+    @DynamicPropertySource
+    static void configureProperties(DynamicPropertyRegistry registry) {
+        registry.add("spring.datasource.url", mysql::getJdbcUrl);
+        registry.add("spring.datasource.username", mysql::getUsername);
+        registry.add("spring.datasource.password", mysql::getPassword);
+    }
+
+    @Autowired
+    private UserInfoMapper userInfoMapper;
+
+    @Test
+    @DisplayName("MyBatis Plus CRUD 集成测试")
+    void should_crud_user_with_real_mysql() {
+        // Given
+        UserInfo user = new UserInfo();
+        user.setUsername("container_test");
+        user.setPhone("13812345678");
+
+        // When - 插入
+        int inserted = userInfoMapper.insert(user);
+
+        // Then
+        assertThat(inserted).isEqualTo(1);
+        assertThat(user.getId()).isNotNull();
+
+        // When - 查询
+        UserInfo found = userInfoMapper.selectById(user.getId());
+        assertThat(found).isNotNull();
+        assertThat(found.getUsername()).isEqualTo("container_test");
+    }
+}
+```
+
+### Redis TestContainer
+
+```java
+@Container
+static GenericContainer<?> redis = new GenericContainer<>("redis:7-alpine")
+    .withExposedPorts(6379);
+
+@DynamicPropertySource
+static void configureRedis(DynamicPropertyRegistry registry) {
+    registry.add("spring.data.redis.host", redis::getHost);
+    registry.add("spring.data.redis.port", () -> redis.getMappedPort(6379));
+}
+```
+
+## 测试数据管理
+
+### 数据准备与清理
+
+```java
+@SpringBootTest
+@AutoConfigureMockMvc
+@ActiveProfiles("test")
+@Transactional  // 每个测试方法执行后自动回滚
+class UserControllerIntegrationTest {
+
+    @Autowired
+    private UserInfoMapper userInfoMapper;
+
+    /**
+     * 准备测试用户数据
+     */
+    private Long prepareTestUser(String username, String phone) {
+        UserInfo user = new UserInfo();
+        user.setUsername(username);
+        user.setPhone(phone);
+        user.setStatus(1);
+        user.setCreateTime(LocalDateTime.now());
+        userInfoMapper.insert(user);
+        return user.getId();
+    }
+
+    /**
+     * 批量准备测试数据
+     */
+    private List<Long> prepareTestUsers(int count) {
+        List<Long> ids = new ArrayList<>();
+        for (int i = 0; i < count; i++) {
+            ids.add(prepareTestUser("user_" + i, "1380000" + String.format("%04d", i)));
+        }
+        return ids;
+    }
+}
+```
+
+### SQL 脚本初始化
+
+```sql
+-- src/test/resources/schema-test.sql
+CREATE TABLE IF NOT EXISTS user_info (
+    id          BIGINT AUTO_INCREMENT PRIMARY KEY,
+    username    VARCHAR(50)  NOT NULL,
+    phone       VARCHAR(20),
+    email       VARCHAR(100),
+    status      TINYINT DEFAULT 1,
+    deleted     TINYINT DEFAULT 0,
+    create_time DATETIME DEFAULT CURRENT_TIMESTAMP,
+    update_time DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
+);
+```
+
+## AssertJ 断言模式
+
+```java
+// 基础断言
+assertThat(result).isNotNull();
+assertThat(result.getCode()).isEqualTo(0);
+assertThat(result.getData()).isInstanceOf(UserInfoVO.class);
+
+// 集合断言
+assertThat(userList)
+    .hasSize(3)
+    .extracting(UserInfoVO::getUsername)
+    .containsExactlyInAnyOrder("user1", "user2", "user3");
+
+// 异常断言
+assertThatThrownBy(() -> userService.getById(null))
+    .isInstanceOf(IllegalArgumentException.class)
+    .hasMessageContaining("ID不能为空");
+
+// 时间断言
+assertThat(user.getCreateTime())
+    .isNotNull()
+    .isBefore(LocalDateTime.now());
+
+// JSON Path 断言（MockMvc）
+mockMvc.perform(get("/api/users/{id}", userId))
+    .andExpect(jsonPath("$.code").value(0))
+    .andExpect(jsonPath("$.data.username").value("testuser"))
+    .andExpect(jsonPath("$.data.phone").value(matchesPattern("\\d{3}\\*{4}\\d{4}")))
+    .andExpect(jsonPath("$.data.roles[*].name").value(hasItem("ADMIN")));
+```
+
+## 最佳实践
+
+1. **使用 @Transactional** — 测试方法加 `@Transactional` 自动回滚，保持数据隔离
+2. **随机端口** — 使用 `RANDOM_PORT` 避免端口冲突
+3. **独立 Profile** — 使用 `@ActiveProfiles("test")` 隔离测试配置
+4. **MockBean 最小化** — 只 mock 真正需要隔离的外部依赖
+5. **数据准备方法** — 封装 `prepareXxx()` 方法统一管理测试数据
+6. **断言充分** — 不仅验证响应，还要验证数据库状态变化
+7. **打印调试** — 开发时用 `.andDo(print())`，提交前移除
+8. **测试分层** — 单元测试覆盖逻辑，集成测试覆盖链路
+
+## 常见问题排查
+
+### 测试上下文启动失败
+
+```
+原因: Bean 创建失败或配置缺失
+解决:
+  1. 检查 application-test.yml 是否完整
+  2. 检查 @MockBean 是否覆盖了必要的外部依赖
+  3. 使用 @SpringBootTest(classes = XxxApplication.class) 指定启动类
+```
+
+### MockMvc 返回 404
+
+```
+原因: Controller 未被扫描到
+解决:
+  1. 确认测试类和启动类在同一包路径下
+  2. 使用 @SpringBootTest 而非 @WebMvcTest（后者只加载 Web 层）
+  3. 检查 URL 路径是否正确（注意 context-path）
+```
+
+### 数据库相关测试失败
+
+```
+原因: H2 和 MySQL 语法差异
+解决:
+  1. H2 使用 MODE=MySQL 兼容模式
+  2. 使用 TestContainers + 真实 MySQL 获得更好的兼容性
+  3. 检查 SQL 中是否有 H2 不支持的语法（如某些函数）
+```
+
+### @Transactional 回滚不生效
+
+```
+原因: 异步操作或多线程环境
+解决:
+  1. 异步操作的数据变更不在事务管理范围内
+  2. 使用 @AfterEach 手动清理数据
+  3. 测试中避免使用异步方法
+```