@alanwang-merit/meritdata-platform-skill-package 1.0.9 → 1.0.11

package/skills/meritdata-platform-test-case/references/guide.md

@@ -1,290 +0,0 @@
-# 测试用例基础指南（test-case）
-
-> 测试用例设计原则 + 覆盖率要求。
-
----
-
-## 1. 测试类型
-
-| 类型 | 范围 | 工具 |
-|------|------|------|
-| 单元测试 | 方法 / 类 | JUnit 5 + Mockito |
-| 集成测试 | Controller / Repository / Feign | @SpringBootTest + Testcontainers |
-| E2E 测试 | 完整流程 | Playwright / Cypress |
-| 性能测试 | 压力 / 负载 | JMeter / k6 |
-
-## 2. 覆盖率要求
-
-| 层级 | 覆盖率 | 说明 |
-|------|--------|------|
-| Service 层 | ≥ 80% | 业务核心 |
-| Controller 层 | ≥ 70% | 接口验证 |
-| Util | ≥ 90% | 工具方法 |
-| Repository 层 | ≥ 60% | 自定义查询方法 |
-
-CI 门禁：覆盖率 < 80% 阻断合并。
-
-## 3. 测试用例结构
-
-```java
-// AAA 模式：Arrange / Act / Assert
-@Test
-void createOrder_success() {
-    // Arrange（准备）
-    OrderRequest req = new OrderRequest("ORD001", new BigDecimal("1000"), "10001");
-
-    // Act（执行）
-    OrderDTO result = orderService.create(req);
-
-    // Assert（断言）
-    assertNotNull(result);
-    assertEquals("ORD001", result.getOrderNo());
-    assertEquals(OrderStatus.PENDING, result.getStatus());
-}
-```
-
-## 4. 命名规范
-
-```
-{方法名}_{场景}_{预期}
-```
-
-例：
-- `createOrder_success`
-- `createOrder_invalidAmount_throwsException`
-- `approveOrder_alreadyApproved_throwsException`
-- `findByUserId_emptyResult`
-
-## 5. 边界值测试
-
-### 5.1 数字字段
-
-```java
-@Test void amount_negative() { ... }     // 负数
-@Test void amount_zero() { ... }            // 零
-@Test void amount_max() { ... }           // 最大值
-@Test void amount_overflow() { ... }      // 溢出
-@Test void amount_decimal() { ... }       // 小数
-```
-
-### 5.2 字符串字段
-
-```java
-@Test void name_null() { ... }
-@Test void name_empty() { ... }
-@Test void name_blank() { ... }            // 全空格
-@Test void name_maxLength() { ... }
-@Test void name_specialChar() { ... }     // 特殊字符
-@Test void name_sqlInjection() { ... }   // ' " ; -- 等
-```
-
-### 5.3 日期字段
-
-```java
-@Test void date_null() { ... }
-@Test void date_invalid() { ... }        // 不合理日期
-@Test void date_future() { ... }
-@Test void date_format() { ... }
-```
-
-### 5.4 集合字段
-
-```java
-@Test void list_null() { ... }
-@Test void list_empty() { ... }
-@Test void list_single() { ... }
-@Test void list_huge() { ... }            // 性能
-```
-
-## 6. 异常路径测试
-
-```java
-@Test
-void createOrder_invalidAmount_throwsException() {
-    OrderRequest req = new OrderRequest("ORD001", new BigDecimal("-100"), "10001");
-
-    assertThrows(BizException.class, () -> {
-        orderService.create(req);
-    });
-
-    // 验证：订单未被创建
-    verify(orderRepository, never()).save(any(Order.class));
-}
-```
-
-## 7. Mock 使用
-
-### 7.1 Mock Repository
-
-```java
-@ExtendWith(MockitoExtension.class)
-class OrderServiceTest {
-
-    @Mock
-    private OrderRepository orderRepository;
-
-    @InjectMocks
-    private OrderServiceImpl orderService;
-
-    @Test
-    void getById_exists() {
-        Order order = new Order();
-        order.setId("ORD001");
-        when(orderRepository.findById("ORD001")).thenReturn(Optional.of(order));
-
-        OrderDTO result = orderService.getById("ORD001");
-
-        assertEquals("ORD001", result.getId());
-    }
-}
-```
-
-### 7.2 Mock Feign
-
-```java
-@MockBean
-private IUserClient userClient;
-
-@Test
-void listOrders() {
-    when(userClient.listByIds(any())).thenReturn(List.of(
-        new UserDTO("10001", "张三")
-    ));
-
-    // ...
-}
-```
-
-## 8. 数据准备
-
-### 8.1 @BeforeEach
-
-```java
-@BeforeEach
-void setUp() {
-    // 每个测试前执行
-    order = new Order();
-    order.setId("ORD001");
-    order.setStatus(OrderStatus.PENDING);
-}
-```
-
-### 8.2 Test Data Builder
-
-```java
-public class OrderBuilder {
-    private String orderNo = "ORD001";
-    private BigDecimal amount = new BigDecimal("1000");
-    private String userId = "10001";
-
-    public OrderBuilder withAmount(BigDecimal amount) {
-        this.amount = amount;
-        return this;
-    }
-
-    public Order build() {
-        Order order = new Order();
-        order.setOrderNo(orderNo);
-        order.setAmount(amount);
-        order.setUserId(userId);
-        return order;
-    }
-}
-
-// 用法
-Order order = new OrderBuilder().withAmount(new BigDecimal("5000")).build();
-```
-
-## 9. 软删除实体特殊用例
-
-详见 [code-dev-rules §八](../../rules/code-dev-rules.md)。
-
-```java
-// GEN-SOFT-DELETE：编号生成器跳过软删除
-@Test
-void generateNo_skipSoftDeleted() {
-    Project soft = new Project();
-    soft.setProjectNo("P001");
-    soft.setDeleted(true);
-    projectRepo.save(soft);
-
-    String next = generator.generateNext("P");
-    assertEquals("P002", next);
-}
-
-// DUP-SOFT-DELETE：service 校验拒软删除
-@Test
-void validateProjectNo_softDeleted_duplicate() {
-    Project soft = new Project();
-    soft.setProjectNo("P001");
-    soft.setDeleted(true);
-    projectRepo.save(soft);
-
-    assertThrows(ProjectNoDuplicateException.class, () -> {
-        service.createProject("P001");
-    });
-}
-```
-
-## 10. ❌ 反模式
-
-### 10.1 ❌ 测试方法无断言
-
-```java
-@Test
-void testCreate() {
-    orderService.create(req);  // 没断言
-}
-
-// ✅ 正确
-@Test
-void testCreate() {
-    OrderDTO result = orderService.create(req);
-    assertNotNull(result);
-    assertEquals("ORD001", result.getOrderNo());
-}
-```
-
-### 10.2 ❌ 测试互相依赖
-
-```java
-// ❌ 错：测试顺序依赖
-@Test
-void testA() { /* 创建数据 */ }
-
-@Test
-void testB() { /* 依赖 testA 创建的数据 */ }
-
-// ✅ 正确：每个测试独立
-@BeforeEach
-void setUp() { /* 创建数据 */ }
-```
-
-### 10.3 ❌ Mock 所有东西
-
-```java
-// ❌ 错：全 Mock，测的是 mock 行为
-when(userRepo.findById(any())).thenReturn(user);
-when(orderRepo.save(any())).thenReturn(order);
-when(notification.send(any())).thenReturn(true);
-orderService.create(req);  // 测的是 Mockito，不是业务
-
-// ✅ 正确：Mock 边界（外部依赖）
-when(userRepo.findById(any())).thenReturn(user);  // 外部
-orderService.create(req);  // 真业务
-```
-
-### 10.4 ❌ 只测正常路径
-
-```java
-// ❌ 错：只测正常
-@Test void createOrder() { ... }
-// 缺：异常路径、边界值
-```
-
-## 11. 关联阅读
-
-- [unit-test.md](unit-test.md) — 单元测试
-- [integration-test.md](integration-test.md) — 集成测试
-- [rules/test-case-dev-rules.md](../../rules/test-case-dev-rules.md)
-- [SKILL.md](../SKILL.md)

package/skills/meritdata-platform-test-case/references/integration-test.md

@@ -1,352 +0,0 @@
-# 集成测试（test-case）
-
-> Controller / Repository / Feign 集成测试。
-
----
-
-## 1. Controller 集成测试
-
-### 1.1 @WebMvcTest
-
-```java
-@WebMvcTest(OrderController.class)
-class OrderControllerTest {
-
-    @Autowired
-    private MockMvc mockMvc;
-
-    @MockBean
-    private IOrderService orderService;
-
-    @Autowired
-    private ObjectMapper objectMapper;
-
-    @Test
-    void createOrder_success() throws Exception {
-        OrderDTO result = new OrderDTO();
-        result.setOrderNo("ORD001");
-        when(orderService.create(any())).thenReturn(result);
-
-        mockMvc.perform(post("/api/v1/orders")
-                .contentType(MediaType.APPLICATION_JSON)
-                .content(objectMapper.writeValueAsString(newOrderRequest())))
-            .andExpect(status().isOk())
-            .andExpect(jsonPath("$.data.orderNo").value("ORD001"));
-    }
-
-    @Test
-    void createOrder_invalidParams_badRequest() throws Exception {
-        mockMvc.perform(post("/api/v1/orders")
-                .contentType(MediaType.APPLICATION_JSON)
-                .content("{}"))  // 缺必填
-            .andExpect(status().isBadRequest());
-    }
-}
-```
-
-### 1.2 @SpringBootTest（完整集成）
-
-```java
-@SpringBootTest
-@AutoConfigureMockMvc
-class OrderControllerIntegrationTest {
-
-    @Autowired
-    private MockMvc mockMvc;
-
-    @Autowired
-    private OrderRepository orderRepository;
-
-    @BeforeEach
-    void setUp() {
-        orderRepository.deleteAll();  // 清理
-    }
-
-    @Test
-    void fullFlow() throws Exception {
-        // 1. 创建
-        mockMvc.perform(post("/api/v1/orders")
-                .header("Authorization", "Bearer " + getTestToken())
-                .contentType(MediaType.APPLICATION_JSON)
-                .content("..."))
-            .andExpect(status().isOk());
-
-        // 2. 验证 DB
-        List<Order> orders = orderRepository.findAll();
-        assertEquals(1, orders.size());
-    }
-}
-```
-
-## 2. Repository 集成测试
-
-### 2.1 @DataJpaTest
-
-```java
-@DataJpaTest
-class OrderRepositoryTest {
-
-    @Autowired
-    private OrderRepository orderRepository;
-
-    @Autowired
-    private TestEntityManager entityManager;
-
-    @Test
-    void findByOrderNo_businessQuery() {
-        // 业务查询（受 @Where 过滤）
-        Order order = new Order();
-        order.setOrderNo("ORD001");
-        entityManager.persist(order);
-        entityManager.flush();
-
-        Optional<Order> found = orderRepository.findByOrderNo("ORD001");
-        assertTrue(found.isPresent());
-    }
-
-    @Test
-    void findByOrderNoIncludingDeleted() {
-        // 准备软删除数据
-        Order order = new Order();
-        order.setOrderNo("ORD001");
-        order.setDeleted(true);
-        entityManager.persist(order);
-        entityManager.flush();
-
-        // 业务查询看不到
-        assertFalse(orderRepository.findByOrderNo("ORD001").isPresent());
-
-        // 全量查询能看到
-        assertTrue(orderRepository.findByOrderNoIncludingDeleted("ORD001").isPresent());
-    }
-}
-```
-
-### 2.2 Testcontainers（真实 DB）
-
-```java
-@SpringBootTest
-@Testcontainers
-class OrderRepositoryIntegrationTest {
-
-    @Container
-    static MySQLContainer<?> mysql = new MySQLContainer<>("mysql:8.0")
-        .withDatabaseName("test")
-        .withUsername("test")
-        .withPassword("test");
-
-    @DynamicPropertySource
-    static void configure(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 OrderRepository orderRepository;
-
-    @Test
-    void complexQuery() {
-        // ...真实 MySQL 测试
-    }
-}
-```
-
-## 3. Feign 集成测试
-
-### 3.1 @MockBean Feign Client
-
-```java
-@SpringBootTest
-class OrderServiceFeignIntegrationTest {
-
-    @MockBean
-    private IUserClient userClient;
-
-    @Autowired
-    private OrderService orderService;
-
-    @Test
-    void listOrders_batchLoadUsers() {
-        when(userClient.listByIds(any())).thenReturn(List.of(
-            new UserDTO("10001", "张三"),
-            new UserDTO("10002", "李四")
-        ));
-
-        List<OrderDTO> orders = orderService.list();
-
-        // 验证 Feign 被调用一次（批量）
-        verify(userClient, times(1)).listByIds(any());
-    }
-}
-```
-
-### 3.2 WireMock（真实 HTTP）
-
-```java
-@SpringBootTest
-@AutoConfigureWireMock(port = 0)
-class OrderServiceWireMockTest {
-
-    @Autowired
-    private OrderService orderService;
-
-    @Test
-    void listOrders_realHttp() {
-        // 模拟平台用户服务响应
-        stubFor(get(urlEqualTo("/api/v1/users"))
-            .willReturn(aResponse()
-                .withStatus(200)
-                .withHeader("Content-Type", "application/json")
-                .withBody("[{\"userId\":\"10001\",\"realName\":\"张三\"}]")));
-
-        List<OrderDTO> orders = orderService.list();
-
-        assertEquals(1, orders.size());
-        verify(getRequestedFor(urlEqualTo("/api/v1/users")));
-    }
-}
-```
-
-## 4. 测试配置
-
-### 4.1 application-test.yml
-
-```yaml
-spring:
-  datasource:
-    url: jdbc:h2:mem:test
-    username: sa
-    password: ""
-  jpa:
-    hibernate:
-      ddl-auto: create-drop
-
-nacos:
-  server-addr: localhost:8848
-  discovery:
-    enabled: false
-
-# 关闭不需要的服务
-feign:
-  hystrix:
-    enabled: false
-```
-
-### 4.2 测试 Profile
-
-```java
-@ActiveProfiles("test")
-@SpringBootTest
-class IntegrationTest { ... }
-```
-
-## 5. 测试用例隔离
-
-### 5.1 @Transactional（自动回滚）
-
-```java
-@SpringBootTest
-@Transactional   // 每个测试回滚
-class OrderServiceIntegrationTest {
-
-    @Test
-    void createOrder() {
-        orderService.create(req);
-        // 测试结束自动回滚
-    }
-}
-```
-
-### 5.2 手动清理
-
-```java
-@AfterEach
-void cleanUp() {
-    orderRepository.deleteAll();
-    userRepository.deleteAll();
-}
-```
-
-### 5.3 测试数据隔离
-
-```java
-// 用 @Sql 加载测试数据
-@Sql(scripts = "/sql/test-data.sql")
-@Test
-void listOrders() { ... }
-
-// 用 @Sql 清空
-@Sql(scripts = "/sql/clean-data.sql", executionPhase = AFTER_TEST_METHOD)
-@Test
-void test() { ... }
-```
-
-## 6. 异步 / MQ 测试
-
-```java
-@SpringBootTest
-class MessagePublishTest {
-
-    @Autowired
-    private MessagePublisher publisher;
-
-    @MockBean
-    private KafkaTemplate<String, String> kafkaTemplate;
-
-    @Test
-    void publishMessage() {
-        publisher.publish("test-topic", "test-message");
-
-        verify(kafkaTemplate).send(eq("test-topic"), eq("test-message"));
-    }
-}
-```
-
-## 7. ❌ 反模式
-
-### 7.1 ❌ 集成测试当单元测试写
-
-```java
-// ❌ 错：起整个 Spring 测一个简单方法
-@SpringBootTest
-class CalculatorTest {
-    @Test
-    void add() {
-        assertEquals(4, calculator.add(2, 2));
-    }
-}
-
-// ✅ 正确：单元测试
-class CalculatorTest {
-    Calculator calculator = new Calculator();
-    @Test void add() { assertEquals(4, calculator.add(2, 2)); }
-}
-```
-
-### 7.2 ❌ 测试间数据污染
-
-```java
-// ❌ 错：不清理
-@Test void testA() { repo.save(user); }
-@Test void testB() {  // testA 的 user 残留
-    List<User> all = repo.findAll();  // 含 testA 的 user
-}
-```
-
-✅ @Transactional 回滚 / @AfterEach 清理。
-
-### 7.3 ❌ 集成测试用真实外部服务
-
-```java
-// ❌ 错
-@FeignClient(url = "https://api.real-platform.com")  // 真实环境
-```
-
-✅ WireMock / @MockBean。
-
-## 8. 关联阅读
-
-- [guide.md](guide.md) — 测试用例基础
-- [unit-test.md](unit-test.md) — 单元测试
-- [SKILL.md](../SKILL.md)