jsharness 1.0.0

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

@@ -0,0 +1,461 @@
+# API 测试技能 (test-api)
+
+> **执行角色**: 测试验证 Agent / CI Pipeline
+> **触发时机**: API 变更后、PR 提交前、每日定时运行
+
+---
+
+## API 集成测试执行
+
+### 执行命令
+
+```bash
+# 运行 API 集成测试
+npm run test:api
+
+# 或使用指定框架
+npx jest --config jest.api.config.js
+npx vitest run --config vitest.api.config.ts
+
+# 带环境变量启动
+DATABASE_URL=test://localhost/testdb npm run test:api
+```
+
+### 环境准备
+
+```bash
+# 启动测试依赖服务
+docker compose up -d db redis
+
+# 执行数据库迁移（使用测试数据库）
+npm run migrate:test
+
+# 播种测试数据
+npm run seed:test
+```
+
+### 测试数据库原则
+
+- **隔离性**：每个测试套件使用独立事务，测试结束后回滚
+- **确定性**：种子数据固定，测试结果可重复
+- **轻量化**：只包含必要的关联数据
+
+---
+
+## 契约测试验证
+
+### 目的
+
+确保前后端接口约定不被破坏。即使内部实现改变，API 契约保持稳定。
+
+### 工具选择
+
+| 场景 | 推荐工具 |
+|------|---------|
+| REST API | Pact / Newman (Postman) |
+| GraphQL | Apollo Schema Checking |
+| OpenAPI 规范 | Dredd / Spector |
+
+### 契约测试结构
+
+```typescript
+import { pactum } from 'pactum';
+
+describe('用户 API 契约测试', () => {
+  const baseUrl = 'http://localhost:3000/api';
+  
+  before(() => {
+    pactum.request.setBaseUrl(baseUrl);
+  });
+
+  it('GET /api/v1/users/:id 应符合响应契约', async () => {
+    await pactum.spec()
+      .get('/users/{id}')
+      .withPathParams('id', 'user-001')
+      .expectStatus(200)
+      .expectHeaderContains('content-type', 'application/json')
+      .expectJsonMatchStrict({
+        code: 0,
+        data: {
+          id: 'user-001',
+          name: pactum.string(),           // 任意非空字符串
+          email: pactum.like('user@'),     // 匹配模式
+          createdAt: pactum.isoDateTime(), // ISO 时间格式
+        },
+        message: pactum.string(),
+        timestamp: pactum.r('^\\d+$'),     // 正则匹配
+      })
+      .toss();  // 发送请求并验证
+  });
+
+  it('POST /api/v1/users 应校验必填字段', async () => {
+    await pactum.spec()
+      .post('/users')
+      .withJson({ name: '' })  // 缺少 email
+      .expectStatus(400)
+      .expectJsonLike({
+        code: 10001,            // 参数错误码
+        message: 'email is required',
+      })
+      .toss();
+  });
+});
+```
+
+### 必须验证的契约维度
+
+| 维度 | 验证内容 |
+|------|----------|
+| **HTTP 方法** | GET/POST/PUT/DELETE 使用正确 |
+| **状态码** | 成功(200/201)、客户端错误(4xx)、服务端错误(5xx) |
+| **Content-Type** | 响应格式正确（application/json） |
+| **Response Schema** | 字段名、类型、嵌套结构符合定义 |
+| **分页参数** | page/pageSize/total/count 字段齐全 |
+| **错误格式** | 统一错误响应结构 |
+| **认证头** | Bearer Token 格式正确 |
+
+---
+
+## API 测试用例清单模板
+
+### 每个 API 端点必须覆盖
+
+```
+端点: POST /api/v1/users
+
+✅ 正常用例：
+  [ ] 所有必填字段齐全 → 201 Created
+  [ ] 所有可选字段都提供 → 完整对象返回
+  [ ] 含特殊字符（中文/emoji）→ 正确存储
+
+❌ 异常用例：
+  [ ] 缺少必填字段 → 400 + 明确的错误信息
+  [ ] 字段类型错误（字符串传数字）→ 400
+  [ ] 字段长度超限 → 400
+  [ ] 邮箱格式无效 → 400
+  [ ] 重复的唯一字段（如邮箱）→ 409 Conflict
+  [ ] 未认证访问 → 401 Unauthorized
+  [ ] 权限不足 → 403 Forbidden
+  [ ] 请求体非 JSON → 415 Unsupported Media Type
+  [ ] 超大 payload → 413 Payload Too Large
+
+🔒 安全用例：
+  [ ] SQL 注入尝试 → 400（被拦截）
+  [ ] XSS payload → 安全存储（转义后）
+  [ ] 越权操作（A 用户操作 B 的资源）→ 403
+```
+
+## API 测试结果输出模板
+
+```yaml
+test_result_api:
+  timestamp: "2026-05-20T22:00:00Z"
+  framework: "pactum" | "jest" | "newman"
+  status: pass | fail
+  
+  endpoints_tested: 24
+  total_assertions: 342
+  
+  summary:
+    passed: 338
+    failed: 4
+    
+  contract_compliance:
+    breaking_changes: 0    # 破坏性变更数量（门禁关键项）
+    new_fields: 2          # 新增字段（向后兼容）
+    removed_fields: 0      # 删除字段（阻塞项）
+    
+  failed_assertions:
+    - endpoint: "PATCH /api/v1/users/:id/profile"
+      assertion: "expect response phone to match pattern"
+      actual: '"13800138000"'
+      expected: 'pattern: /^1[3-9]\d{9}$/'
+      
+  performance_p95:
+    avg_response_time_ms: 85
+    max_response_time_ms: 320
+    slow_endpoints:
+      - path: "/api/v1/reports/export"
+        avg_ms: 280
+        
+  baseline_comparison:
+    regression: false
+```
+
+---
+
+# ════════════════════════════════════════════════════════
+#  Java 后端 API 集成测试（REST Assured + WireMock）
+# ════════════════════════════════════════════════════════
+
+> **适用技术栈**: Spring Boot / JDK21
+> **参考规则**: `rules/project/java-backend.md` §4 Controller + §5 Service
+
+---
+
+## REST Assured — Java HTTP 测试 DSL
+
+### Maven 依赖
+
+```xml
+<!-- pom.xml -->
+<dependency>
+    <groupId>io.rest-assured</groupId>
+    <artifactId>rest-assured</artifactId>
+    <version>5.4.0</version>
+    <scope>test</scope>
+</dependency>
+<dependency>
+    <groupId>io.rest-assured</groupId>
+    <artifactId>spring-mock-mvc-module</artifactId>
+    <version>5.4.0</version>
+    <scope>test</scope>
+</dependency>
+```
+
+### 核心测试结构
+
+```java
+@SpringBootTest
+@AutoConfigureMockMvc
+class UserApiIntegrationTest {
+
+    @Autowired
+    private MockMvc mockMvc;
+
+    @MockBean
+    private UserService userService;
+
+    @Autowired
+    private ObjectMapper objectMapper;
+
+    @Test
+    @DisplayName("POST /api/v1/users — 创建用户成功")
+    void shouldCreateUser() throws Exception {
+        // === GIVEN (准备) ===
+        UserReqVO req = UserReqVO.builder()
+            .phone("13800138000").name("张三").build();
+        
+        User created = User.builder().id("user-001").name("张三").build();
+        when(userService.createUser(any(UserReqVO.class)))
+            .thenReturn(RespVO.success(created));
+
+        // === WHEN & THEN (执行 + 断言) ===
+        mockMvc.perform(post("/api/v1/users")
+                .contentType(MediaType.APPLICATION_JSON)
+                .content(objectMapper.writeValueAsString(req)))
+            .andExpect(status().isCreated())                          // 201
+            .andExpect(jsonPath("$.code").value(0))
+            .andExpect(jsonPath("$.data.id").isNotEmpty())
+            .andExpect(jsonPath("$.data.name").value("张三"))
+            .andDo(print());                                          // 打印完整响应（调试用）
+    }
+
+    @Test
+    @DisplayName("GET /api/v1/users/{id} — 用户存在时返回 200")
+    void shouldReturnUserWhenExists() throws Exception {
+        // GIVEN
+        when(userService.getUserById("user-001"))
+            .thenReturn(RespVO.success(
+                UserVO.builder().id("user-001").name("李四")
+                .status("ACTIVE").build()));
+
+        // WHEN & THEN
+        mockMvc.perform(get("/api/v1/users/user-001"))
+            .andExpect(status().isOk())
+            .andExpect(content().contentType(MediaType.APPLICATION_JSON))
+            .andExpect(jsonPath("$.data.name").value("李四"));
+    }
+
+    @Test
+    @DisplayName("POST /api/v1/users — 缺少必填字段返回 400")
+    void shouldReturn400WhenMissingFields() throws Exception {
+        // 缺少 phone 字段
+        String invalidJson = "{\"name\":\"\"}";
+
+        mockMvc.perform(post("/api/v1/users")
+                .contentType(MediaType.APPLICATION_JSON)
+                .content(invalidJson))
+            .andExpect(status().isBadRequest())
+            .andExpect(jsonPath("$.code").value(10001))       // 参数错误码
+            .andExpect(jsonPath("$.message").isNotEmpty());
+    }
+}
+```
+
+### 契约测试维度检查清单
+
+| 维度 | 验证方式 | 示例断言 |
+|------|---------|---------|
+| **HTTP 方法** | `.getMethod()` 匹配 | `.request().method(HttpMethod.POST)` |
+| **状态码** | `.andExpect(status())` | `isOk()` / `isCreated()` / `isBadRequest()` / `isUnauthorized()` |
+| **Content-Type** | header 检查 | `.contentType(MediaType.APPLICATION_JSON)` |
+| **Response Schema** | jsonPath 字段存在性 | `jsonPath("$.data.id").exists()` |
+| **分页结构** | 分页字段完整性 | `jsonPath("$.data.list")` + `jsonPath("$.total")` |
+| **错误格式** | 统一错误响应 | `jsonPath("$.code").isNumber()` + `jsonPath("$.message")` |
+| **认证头** | 未携带 Token 时 | `isUnauthorized()` 或 `isForbidden()` |
+
+---
+
+## WireMock — 服务端 Mock
+
+### Maven 依赖
+
+```xml
+<dependency>
+    <groupId>org.wiremock</groupId>
+    <artifactId>wiremock-standalone</artifactId>
+    <version>3.3.1</version>
+    <scope>test</scope>
+</dependency>
+```
+
+### Mock 外部服务
+
+```java
+@ExtendWith(WireMockExtension.class)
+@WireMockConfig(wiremockPort = 9090)
+class PaymentServiceIntegrationTest {
+
+    @RegisterExtension
+    static WireMockExtension wireMock = WireMockExtension.newInstance()
+        .options(wireMockConfig().port(9090))
+        .build();
+
+    @Test
+    @DisplayName("调用支付网关成功")
+    void shouldCallPaymentGateway() {
+        // Stub：模拟支付网关响应
+        stubFor(post(urlEqualTo("/api/pay"))
+            .willReturn(aResponse()
+                .withStatus(200)
+                .withHeader("Content-Type", "application/json")
+                .withBody("{\"code\":0,\"tradeNo\":\"T202605210001\"}")));
+
+        // 执行业务代码
+        PayResult result = paymentService.pay(PayRequest.builder()
+            .amount(new BigDecimal("100.00")).orderId("ORD-001").build());
+
+        // 断言
+        assertThat(result.getTradeNo()).isEqualTo("T202605210001");
+        
+        // 验证确实调用了外部服务
+        verify(postRequestedFor(urlEqualTo("/api/pay"))
+            .withRequestBody(containing("100.00")));
+    }
+}
+```
+
+---
+
+## 数据库迁移测试
+
+### Flyway 集成
+
+```bash
+# 迁移命令
+mvn flyway:migrate           # 执行所有待执行的迁移
+mvn flyway:info              # 查看迁移历史和状态
+mvn flyway:validate          # 校验迁移文件一致性
+
+# 清理重建（仅开发环境）
+mvn flyway:clean migrate     # ⚠️ 会删除所有数据！仅本地使用
+```
+
+### 迁移脚本规范
+
+```sql
+-- 文件命名格式: V{版本号}__{描述}.sql
+-- 例: V20260521_001__add_user_phone_encryption.sql
+
+-- ✅ 正确做法：增量 ALTER 脚本
+ALTER TABLE t_user ADD COLUMN phone_encrypted VARCHAR(128) DEFAULT '';
+CREATE INDEX idx_user_phone_encrypted ON t_user(phone_encrypted);
+
+-- ❌ 错误做法：DROP 后重建（会丢失数据！）
+-- DROP TABLE t_user;
+-- CREATE TABLE t_user (...);
+```
+
+---
+
+## Postman Newman — API 回归测试
+
+### 从 CI/CD 运行
+
+```bash
+# 安装 newman
+npm install -g newman newman-reporter-htmlextra
+
+# 运行集合
+newman run postman_collections/backend-api.json \
+  -e postman_environments/staging.json \
+  --reporters cli,htmlextra \
+  --reporter-htmlextra-export api-test-report.html \
+  --bail                    # 第一个失败即停止
+
+# Jenkins/GitLab CI 集成
+# newman run ... --reporters junit --reporter-junit-export results.xml
+```
+
+### 集合组织建议
+
+```
+backend-api.collection/
+├── auth/
+│   ├── POST_login.json
+│   └── POST_refresh-token.json
+├── user/
+│   ├── GET_users-id.json
+│   ├── POST_users.json
+│   └── PUT_users-id-profile.json
+├── order/
+│   ├── GET_orders.json
+│   └── POST_orders.json
+└── health/
+    └── GET_health.json
+```
+
+---
+
+## Java API 测试结果输出模板
+
+```yaml
+test_result_api_java:
+  timestamp: "2026-05-20T22:00:00Z"
+  framework: "REST Assured (Spring MockMvc) + Newman"
+  status: pass | fail
+  
+  endpoints_tested: 32
+  total_assertions: 486
+  
+  summary:
+    passed: 482
+    failed: 4
+    
+  contract_compliance:
+    breaking_changes: 0
+    new_fields: 1
+    removed_fields: 0
+    deprecated_fields: 0
+    
+  failed_assertions:
+    - endpoint: "PUT /api/v1/users/:id/profile"
+      method: "PUT"
+      assertion: "expect response.phone to match regex ^1[3-9]\\d{9}$"
+      actual: '"13800138000"'
+      expected: 'pattern match'
+      
+  security_checks:
+    sql_injection_attempt_blocked: true
+    xss_payload_sanitized: true
+    unauthorized_access_rejected: true
+    missing_auth_returns_401: true
+    
+  performance_p95:
+    avg_response_time_ms: 65
+    max_response_time_ms: 280
+    
+  baseline_comparison:
+    regression: false
+```