jsharness 1.0.0

package/.harness/skills/test-unit.md

@@ -0,0 +1,649 @@
+# 单元测试技能 (test-unit)
+
+> **执行角色**: 开发实现 Agent / 测试验证 Agent
+> **触发时机**: 功能开发完成时、PR 提交前、CI 流水线中
+
+---
+
+## 执行命令
+
+```bash
+# 运行全部单元测试
+npm run test
+
+# 或带覆盖率报告
+npm run test:coverage
+
+# 运行特定测试文件
+npm run test -- --testPathPattern="UserService"
+
+# 监听模式（开发时）
+npm run test:watch
+```
+
+## 覆盖率收集
+
+### 配置要求
+
+```javascript
+// jest.config.js 或 vitest.config.ts
+module.exports = {
+  coverageThreshold: {
+    global: {
+      branches: 80,     // 分支覆盖率 ≥ 80%
+      functions: 80,    // 函数覆盖率 ≥ 80%
+      lines: 80,        // 行覆盖率 ≥ 80%
+      statements: 80    // 语句覆盖率 ≥ 80%
+    }
+  },
+  collectCoverageFrom: [
+    'src/**/*.{ts,tsx,js,jsx}',
+    '!src/**/*.d.ts',
+    '!src/**/*.test.{ts,tsx}',
+    '!src/**/*.stories.{ts,tsx}',
+    '!src/main.{ts,tsx}',       // 入口文件
+    '!src/vite-env.d.ts'         // 类型声明
+  ]
+};
+```
+
+### 覆盖率分级标准
+
+| 等级 | 分支覆盖率 | 说明 |
+|------|-----------|------|
+| 🟢 优秀 | ≥ 90% | 高质量代码 |
+| 🟡 合格 | 70% - 89% | 达标，建议提升 |
+| 🔴 不合格 | < 70% | 门禁 FAIL |
+
+### 新代码额外要求
+
+新编写或修改的代码，覆盖率必须 **≥ 85%**。
+
+## 测试用例编写规范
+
+### 结构要求（AAA 模式）
+
+```typescript
+describe('UserService', () => {
+  describe('getUserById', () => {
+    it('应该根据 ID 返回用户信息', async () => {
+      // Arrange（准备）
+      const mockUserId = 'user-001';
+      const expectedUser = { id: mockUserId, name: 'Test User' };
+      userRepository.findById.mockResolvedValue(expectedUser);
+
+      // Act（执行）
+      const result = await userService.getUserById(mockUserId);
+
+      // Assert（断言）
+      expect(result).toEqual(expectedUser);
+      expect(userRepository.findById).toHaveBeenCalledWith(mockUserId);
+    });
+  });
+});
+```
+
+### 必须覆盖的场景
+
+每个函数/方法必须覆盖：
+
+| 场景 | 示例 |
+|------|------|
+| **正常路径** | 有效输入 → 正确输出 |
+| **边界条件** | 空值、最大值、最小值 |
+| **异常情况** | 无效输入、服务不可用 |
+| **异步行为** | 成功回调、超时处理 |
+
+```typescript
+describe('getUserById', () => {
+  it('正常：返回用户信息', async () => { /* ... */ });
+  
+  it('边界：ID 为空字符串时抛出 ValidationError', async () => {
+    await expect(userService.getUserById(''))
+      .rejects.toThrow(ValidationError);
+  });
+  
+  it('异常：用户不存在时返回 null', async () => {
+    userRepository.findById.mockResolvedValue(null);
+    const result = await userService.getUserById('nonexistent');
+    expect(result).toBeNull();
+  });
+
+  it('异常：数据库连接超时时抛出 DatabaseError', async () => {
+    userRepository.findById.mockRejectedValue(new Error('Connection timeout'));
+    await expect(userService.getUserById('user-001'))
+      .rejects.toThrow(DatabaseError);
+  });
+});
+```
+
+## 失败报告分析
+
+### 测试失败时的诊断步骤
+
+```
+1. 查看失败信息
+   ├── 断言失败？→ 检查预期值和实际值的差异
+   ├── 超时失败？→ 检查是否有未解决的 Promise
+   ├── 编译错误？→ 检查类型和导入
+   └── Hook 失败？→ 检查 beforeAll/afterAll 设置
+
+2. 定位原因
+   ├── 代码逻辑变更导致预期失效？→ 更新测试用例
+   ├── 测试数据不足？→ 补充边界用例
+   ├── Mock 配置错误？→ 检查 mock 行为定义
+   └── 异步竞态？→ 添加 waitFor / act 包裹
+
+3. 修复并验证
+   ├── 修复代码或测试
+   ├── 重跑失败用例（不重跑全部以节省时间）
+   └── 确认覆盖率未下降
+```
+
+## 测试结果输出模板
+
+```yaml
+test_result_unit:
+  timestamp: "2026-05-20T22:00:00Z"
+  framework: "vitest" | "jest"
+  status: pass | fail
+  
+  summary:
+    total_tests: 156
+    passed: 154
+    failed: 2
+    skipped: 0
+    
+  coverage:
+    lines: 82.5
+    functions: 81.2
+    branches: 78.9
+    statements: 83.1
+    
+  failed_tests:
+    - name: "UserService > getUserById > should throw on empty id"
+      file: "src/services/UserService.test.ts:42"
+      error: "Expected 'ValidationError' but received 'null'"
+      
+  baseline_comparison:
+    coverage_delta: +1.2        # 相比基线的变化（正=提升，负=下降）
+    test_count_delta: +5        # 测试数量变化
+    regression: false           # 是否有回归
+```
+
+---
+
+# ════════════════════════════════════════════════════════
+#  Java 后端单元测试（Spring Boot + JUnit5）
+# ════════════════════════════════════════════════════════
+
+> **适用技术栈**: Spring Boot 3.x / JDK21 / JUnit5 / Mockito
+> **参考规则**: `rules/project/java-backend.md` §13 测试规范
+
+---
+
+## 执行命令
+
+```bash
+# === 编译 + 全量测试 ===
+mvn clean test                              # 运行全部单元测试
+
+# === 带覆盖率报告 ===
+mvn clean verify                            # 包含 JaCoCo 覆盖率
+
+# === 运行指定测试类 ===
+mvn test -Dtest=UserServiceTest             # 指定类
+mvn test -Dtest="com.jieshun.service.**"    # 通配符匹配包
+
+# === 跳过测试编译/执行 ===
+mvn clean compile -DskipTests               # 仅编译，跳过测试
+mvn clean package -Dmaven.test.skip         # 完全跳过测试阶段
+
+# === 快速诊断（显示详细错误）===
+mvn test -e                                 # 显示完整错误堆栈
+mvn test -Dsurefire.useFile=false           # 直接输出到控制台
+
+# === 并行测试加速 ===
+mvn test -T 4                               # 4 线程并行
+```
+
+---
+
+## JUnit5 核心注解体系
+
+### 基础注解
+
+| 注解 | 用途 | 说明 |
+|------|------|------|
+| `@Test` | 标记测试方法 | 替代 JUnit4 的 `@Test` |
+| `@BeforeEach` | 每个测试前执行 | 替代 `@Before` |
+| `@AfterEach` | 每个测试后执行 | 替代 `@After` |
+| `@BeforeAll` | 类初始化时一次 | 必须配合 `static` |
+| `@AfterAll` | 类销毁时一次 | 必须配合 `static` |
+| `@DisplayName("描述")` | 测试名称 | 中文可读名称 |
+| `@Disabled` | 跳过测试 | 替代 `@Ignore` |
+| `@Tag("slow")` | 标签分组 | 用于选择性运行 |
+| `@Nested` | 内部测试类 | 组织相关测试 |
+| `@Timeout(3)` | 超时限制 | 单位：秒 |
+
+### 参数化测试
+
+```java
+@ParameterizedTest
+@ValueSource(strings = {"", " "})
+@DisplayName("空字符串应抛出异常")
+void shouldThrowOnBlank(String input) {
+    assertThatThrownBy(() -> service.process(input))
+        .isInstanceOf(BusinessException.class)
+        .hasMessageContaining("不能为空");
+}
+
+@ParameterizedTest
+@CsvSource({
+    "user-001, 张三, ACTIVE",
+    "user-002, 李四, INACTIVE"
+})
+@DisplayName("根据 ID 应返回正确用户状态")
+void shouldReturnCorrectStatus(String id, String name, String status) {
+    User user = userService.findById(id);
+    assertThat(user.getName()).isEqualTo(name);
+    assertThat(user.getStatus().name()).isEqualTo(status);
+}
+```
+
+---
+
+## Mockito Mock 模式
+
+### 常用注解配置
+
+```java
+@ExtendWith(MockitoExtension.class)   // 启用 Mockito
+class UserServiceTest {
+
+    @Mock
+    private UserRepository userRepository;       // Mock 依赖
+    
+    @Mock  
+    private RedisTemplate<String, String> redis; // Mock 外部服务
+    
+    @InjectMocks
+    private UserService userService;             // 自动注入 Mock
+
+    @BeforeEach
+    void setUp() {
+        // 额外配置（可选）
+        lenient().when(redis.hasKey(anyString())).thenReturn(false);
+    }
+}
+```
+
+### 常用 Mock 操作
+
+```java
+// ✅ 定义返回值
+when(userRepository.findById("user-001"))
+    .thenReturn(Optional.of(User.builder().id("user-001").name("张三").build()));
+
+// ✅ 定义异常抛出
+when(userRepository.findById("nonexist"))
+    .thenThrow(new EntityNotFoundException("用户不存在"));
+
+// ✅ 验证调用次数
+verify(userRepository, times(1)).save(any(User.class));
+verify(userRepository, never()).deleteById(anyString());
+verify(redis, atLeastOnce()).hasKey(anyString());
+
+// ✅ 参数捕获验证
+ArgumentCaptor<User> captor = ArgumentCaptor.forClass(User.class);
+verify(userRepository).save(captor.capture());
+assertThat(captor.getValue().getName()).contains("张三");
+
+// ❌ 不要这样做：Mock 返回 null 后未处理
+// when(service.call()).thenReturn(null); // 容易 NPE
+// 推荐：
+when(service.call()).thenReturn(Optional.empty());
+```
+
+### BDDMockito (行为驱动风格)
+
+```java
+@Test
+@DisplayName("BDD 风格：用户注册成功流程")
+void shouldRegisterUserSuccessfully() {
+    // GIVEN — 准备数据
+    UserReqVO req = UserReqVO.builder()
+        .phone("13800138000").name("王五").build();
+    when(userRepository.findByPhone(req.getPhone())).thenReturn(Optional.empty());
+
+    // WHEN — 执行操作
+    RespVO result = userService.registerUser(req);
+
+    // THEN — 验证结果
+    then(result).isNotNull();
+    then(result.getCode()).isEqualTo(0);
+    then(userRepository).should(times(1)).save(any(User.class));
+}
+```
+
+---
+
+## Spring Boot Test 配置
+
+### 单元测试（不启动容器）
+
+```java
+@ExtendWith(MockitoExtension.class)
+class OrderServiceTest {
+    // 纯 Service 层测试，不加载 Spring 上下文
+    // 速度快 (~100ms/test)，适合纯逻辑测试
+}
+```
+
+### Web 层切片测试
+
+```java
+@WebMvcTest(UserController.class)          // 只加载 Controller 层
+@AutoConfigureMockMvc
+class UserControllerTest {
+
+    @Autowired
+    private MockMvc mockMvc;
+
+    @MockBean
+    private UserService userService;         // Mock Service 层
+
+    @Test
+    @DisplayName("GET /api/v1/users/{id} 应返回用户信息")
+    void shouldReturnUser() throws Exception {
+        // given
+        given(userService.getUserById("user-001"))
+            .willReturn(RespVO.success(UserVO.builder().id("user-001").build()));
+
+        // when & then
+        mockMvc.perform(get("/api/v1/users/user-001"))
+            .andExpect(status().isOk())
+            .andExpect(jsonPath("$.code").value(0))
+            .andExpect(jsonPath("$.data.id").value("user-001"));
+    }
+}
+```
+
+### 集成测试（启动完整上下文）
+
+```java
+@SpringBootTest
+@Testcontainers                          // 自动管理 Docker 容器
+@ActiveProfiles("test")                  // 使用 application-test.yml
+class UserRepositoryIntegrationTest {
+
+    @Container
+    static MySQLContainer mysql = new MySQLContainer("mysql:8.0")
+        .withDatabaseName("test_db")
+        .withUsername("test")
+        .withPassword("test");
+
+    @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 UserRepository userRepository;
+
+    @Test
+    @DisplayName("数据库 CRUD 操作正常")
+    void shouldCRUD() {
+        User saved = userRepository.save(User.builder().name("集成测试").build());
+        assertThat(saved.getId()).isNotNull();
+        assertThat(userRepository.findById(saved.getId())).isPresent();
+    }
+}
+```
+
+---
+
+## JaCoCo 覆盖率配置
+
+### pom.xml 插件配置
+
+```xml
+<plugin>
+    <groupId>org.jacoco</groupId>
+    <artifactId>jacoco-maven-plugin</artifactId>
+    <version>0.8.11</version>
+    <executions>
+        <execution>
+            <goals>
+                <goal>prepare-agent</goal>      <!-- 准备 agent -->
+            </goals>
+        </execution>
+        <execution>
+            <id>report</id>
+            <phase>test</phase>
+            <goals>
+                <goal>report</goal>              <!-- 生成报告 -->
+            </goals>
+        </execution>
+        <execution>
+            <id>check</id>
+            <phase>verify</phase>
+            <goals>
+                <goal>check</goal>              <!-- 门禁检查 -->
+            </goals>
+            <configuration>
+                <rules>
+                    <rule>
+                        <element>BUNDLE</element>
+                        <limits>
+                            <!-- 分支覆盖率 -->
+                            <limit>
+                                <counter>BRANCH</counter>
+                                <value>COVEREDRATIO</value>
+                                <minimum>0.80</minimum>
+                            </limit>
+                            <!-- 行覆盖率 -->
+                            <limit>
+                                <counter>LINE</counter>
+                                <value>COVEREDRATIO</value>
+                                <minimum>0.80</minimum>
+                            </limit>
+                            <!-- 方法覆盖率 -->
+                            <limit>
+                                <counter>METHOD</counter>
+                                <value>COVEREDRATIO</value>
+                                <minimum>0.80</minimum>
+                            </limit>
+                            <!-- 类覆盖率 -->
+                            <limit>
+                                <counter>CLASS</counter>
+                                <value>MISSEDCOUNT</value>
+                                <maximum>0</maximum>  <!-- 不允许有未覆盖的类 -->
+                            </limit>
+                        </limits>
+                    </rule>
+                </rules>
+            </configuration>
+        </execution>
+    </executions>
+</plugin>
+```
+
+### 排除不需要覆盖的代码
+
+```xml
+<configuration>
+    <excludes>
+        <!-- 配置类、实体、DTO、VO 不需要单测 -->
+        <exclude>**/config/**</exclude>
+        <exclude>**/entity/**</exclude>
+        <exclude>**/dto/**</exclude>
+        <exclude>**/vo/**</exclude>
+        <exclude>**/*Application.*</exclude>
+        <exclude>**/*Config.*</exclude>
+        <exclude>**/exception/**</exclude>
+        <!-- 枚举通常也不需要 -->
+        <exclude>**/enums/**</exclude>
+    </excludes>
+</configuration>
+```
+
+### 覆盖率查看
+
+```bash
+# 报告位置
+target/site/jacoco/index.html          # HTML 可视化报告
+
+# CLI 查看简要数据
+cat target/site/jacoco/jacoco.csv     # CSV 格式的逐行覆盖率
+```
+
+---
+
+## AAA 模式 Java 示例
+
+### 标准 AAA 结构
+
+```java
+class UserServiceTest {
+
+    @Test
+    @DisplayName("根据有效 ID 返回用户信息")
+    void shouldReturnUserByValidId() {
+        // ========== ARRANGE (准备) ==========
+        String userId = "user-001";
+        User expected = User.builder()
+            .id(userId).name("测试用户").phone("13800138000")
+            .status(UserStatus.ACTIVE).build();
+
+        when(userRepository.findById(userId)).thenReturn(Optional.of(expected));
+
+        // ========== ACT (执行) ==========
+        RespVO result = userService.getUserById(userId);
+
+        // ========== ASSERT (断言) ==========
+        assertThat(result.getCode()).isEqualTo(0);
+        assertThat(result.getData())
+            .usingRecursiveComparison()   // 递归比较所有字段
+            .ignoringFields("createTime", "updateTime")
+            .isEqualTo(expected);
+    }
+
+    @Test
+    @DisplayName("ID 为空时应抛出参数校验异常")
+    void shouldThrowOnEmptyId() {
+        // Arrange
+        String emptyId = "";
+
+        // Act & Assert (使用 AssertJ 断言库)
+        assertThatThrownBy(() -> userService.getUserById(emptyId))
+            .isInstanceOf(ConstraintViolationException.class)
+            .hasMessageContaining("ID 不能为空");
+        
+        // 验证不会访问 Repository
+        verify(userRepository, never()).findById(anyString());
+    }
+
+    @Test
+    @DisplayName("用户不存在时返回业务异常")
+    void shouldThrowWhenNotFound() {
+        // Arrange
+        String nonExistId = "ghost-999";
+        when(userRepository.findById(nonExistId)).thenReturn(Optional.empty());
+
+        // Act & Assert
+        assertThatThrownBy(() -> userService.getUserById(nonExistId))
+            .isInstanceOf(JscicdBizException.class)
+            .hasFieldOrPropertyWithValue("errorCode", "USER_NOT_FOUND");
+    }
+}
+```
+
+### 异步测试示例
+
+```java
+@Test
+@DisplayName("异步发送通知成功")
+void shouldSendNotificationAsync() throws Exception {
+    // Arrange
+    NotificationDTO dto = NotificationDTO.builder()
+        .userId("user-001").type(NotificationType.SMS).content("验证码1234").build();
+
+    // Act
+    CompletableFuture<RespVO> future = notificationService.sendAsync(dto);
+
+    // Assert — 使用 CompletableFuture.get(timeout) 等待完成
+    RespVO result = future.get(5, TimeUnit.SECONDS);
+    
+    assertThat(result.getCode()).isEqualTo(0);
+    verify(smsClient, times(1)).send(anyString(), anyString());
+}
+```
+
+---
+
+## 失败诊断步骤
+
+```text
+Java 单元测试失败时的诊断路径：
+
+1. 查看失败信息
+   ├── 编译错误? → 检查 import / 泛型擦除 / Lombok 注解处理器
+   ├── AssertionError? → 检查期望值和实际值的差异 (AssertJ 会给出详细 diff)
+   ├── Exception in test? → 查看是否为 expected exception 或真正的 bug
+   └── NoBeanDefFoundError? → 缺少 @MockBean / @SpyBean
+
+2. 定位原因
+   ├── Mock 未生效? → 检查 @ExtendWith(MockitoExtension.class)
+   ├── Spring 上下文启动慢? → 减少使用 @SpringBootTest，优先切片测试
+   ├── 数据库连接失败? → 使用 @Testcontainers 或 H2 内存数据库
+   └── 并发问题? → 检查 @Transactional 回滚 / ThreadLocal 清理
+
+3. 修复并验证
+   ├── 修复代码或测试
+   ├── mvn test -Dtest=FailedTestClass#failedMethodName  (只跑失败的)
+   └── mvn jacoco:report  确认覆盖率未下降
+```
+
+---
+
+## 测试结果输出模板 (Java)
+
+```yaml
+test_result_java:
+  timestamp: "2026-05-20T22:00:00Z"
+  framework: "JUnit5 + Mockito + Spring Boot Test"
+  build_tool: "Maven"
+  status: pass | fail
+  
+  summary:
+    total_tests: 248
+    passed: 245
+    failed: 2
+    errors: 1
+    skipped: 5
+    duration_seconds: 45.2
+    
+  coverage_jacoco:
+    instructions: 82.3
+    branches: 78.5
+    lines: 84.1
+    methods: 88.2
+    classes: 95.0
+    
+  failed_tests:
+    - name: "com.jieshun.service.UserServiceTest > shouldUpdateUserProfile"
+      file: "src/test/java/com/jieshun/service/UserServiceTest.java:87"
+      error: "expected: <ACTIVE> but was: <INACTIVE>"
+      
+  surefire_report:
+    location: "target/surefire-reports/"
+    xml_report: "TEST-com.jieshun.service.UserServiceTest.xml"
+
+  baseline_comparison:
+    coverage_delta: +1.5
+    test_count_delta: +12
+    regression: false
+```