jsharness 1.0.0

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

@@ -0,0 +1,431 @@
+# E2E 测试技能 (test-e2e)
+
+> **执行角色**: 测试验证 Agent / CI Pipeline
+> **触发时机**: 关键功能开发完成、预发布前、版本发布前
+
+---
+
+## E2E 测试环境准备
+
+### 环境启动
+
+```bash
+# 启动 E2E 测试环境（Docker Compose）
+docker compose -f docker-compose.e2e.yml up -d
+
+# 等待所有服务就绪
+# 等待顺序：数据库 → 后端 API → 前端应用
+
+# 验证服务状态
+curl -f http://localhost:3000/api/health || echo "Backend not ready"
+curl -f httplocalhost:3000 || echo "Frontend not ready"
+```
+
+### 环境配置要点
+
+| 配置项 | E2E 环境 | 注意事项 |
+|--------|----------|----------|
+| 数据库 | 使用独立测试数据库 | 每次测试前重置 |
+| API 地址 | `http://localhost:3000/api` | 非 production URL |
+| 认证方式 | 使用测试专用 Token | 不过期或长有效期 |
+| 外部服务 | 使用 Mock 服务 | 支付/邮件/短信等 |
+
+---
+
+## 关键路径测试执行
+
+### 执行命令
+
+```bash
+# 运行全部 E2E 测试
+npm run test:e2e
+
+# 运行特定 spec 文件
+npx playwright test login.spec.ts
+
+# UI 模式（调试用）
+npx playwright test --ui
+
+# headed 模式（显示浏览器）
+npx playwright test --headed
+```
+
+### 必测的关键路径
+
+每个 Web 应用必须维护以下核心 E2E 场景：
+
+#### 用户认证流程
+```
+注册 → 邮箱验证 → 登录 → 密码修改 → 退出登录
+登录态过期 → 自动跳转登录页 → 重新登录 → 回到原页面
+```
+
+#### 核心业务流程（按产品定制）
+
+```
+示例：电商场景
+浏览商品 → 加入购物车 → 结算 → 选择支付方式 → 支付成功 → 订单详情
+示例：管理后台
+登录 → 数据看板 → CRUD 操作 → 导出数据 → 操作日志审计
+```
+
+#### 关键功能回归
+```
+每次发版前必须跑通的 TOP10 页面/功能
+（由 PM 和 QA 共同确定优先级列表）
+```
+
+### E2E 用例结构（Playwright 示例）
+
+```typescript
+import { test, expect } from '@playwright/test';
+
+test.describe('用户认证流程', () => {
+  test.beforeEach(async ({ page }) => {
+    await page.goto('/login');
+  });
+
+  test('正确邮箱密码可以成功登录', async ({ page }) => {
+    // Arrange
+    await page.fill('[data-testid="email"]', 'test@example.com');
+    await page.fill('[data-testid="password"]', 'ValidPass123!');
+    
+    // Act
+    await page.click('[data-testid="submit-btn"]');
+    
+    // Assert
+    await expect(page).toHaveURL(/\/dashboard/);
+    await expect(page.locator('[data-testid="user-avatar"]')).toBeVisible();
+  });
+
+  test('错误密码显示提示信息', async ({ page }) => {
+    await page.fill('[data-testid="email"]', 'test@example.com');
+    await page.fill('[data-testid="password"]', 'WrongPassword');
+    await page.click('[data-testid="submit-btn"]');
+    
+    await expect(page.locator('[data-testid="error-message"]'))
+      .toHaveText('邮箱或密码错误');
+    await expect(page).toHaveURL(/\/login/);  // 未跳转
+  });
+});
+```
+
+---
+
+## 截图与日志收集
+
+### 失败自动截图
+
+```typescript
+// playwright.config.ts
+export default defineConfig({
+  use: {
+    screenshot: 'only-on-failure',  // 仅失败时截图
+    video: 'retain-on-failure',     // 仅失败时保留视频
+    trace: 'on-first-retry',        // 重试时记录 trace
+  },
+  outputDir: 'test-results/',
+});
+```
+
+### 日志收集策略
+
+| 日志类型 | 收集方式 | 用途 |
+|----------|----------|------|
+| **浏览器 Console** | Playwright `console` 事件 | 捕获前端运行时错误 |
+| **网络请求** | Playwright `route` / HAR | 检查 API 调用是否正常 |
+| **后端日志** | Docker logs / 文件 | 服务端错误排查 |
+| **性能指标** | Performance Timing | 页面加载时间分析 |
+
+```typescript
+// 收集控制台日志
+test('页面无 JS 错误', async ({ page }) => {
+  const logs: string[] = [];
+  page.on('console', msg => {
+    if (msg.type() === 'error') logs.push(msg.text());
+  });
+  
+  await page.goto('/');
+  
+  expect(loges).toEqual([]);  // 不应有 console.error
+});
+```
+
+## E2E 测试结果输出模板
+
+```yaml
+test_result_e2e:
+  timestamp: "2026-05-20T22:00:00Z"
+  framework: "playwright"
+  browser: "chromium" | "firefox" | "webkit"
+  status: pass | fail
+  
+  environment:
+    backend_url: "http://localhost:3000"
+    database: "postgresql-test"
+    external_services: mocked
+    
+  summary:
+    total_specs: 12
+    total_tests: 48
+    passed: 47
+    failed: 1
+    skipped: 2
+    duration_ms: 120000
+    
+  failed_tests:
+    - name: "购物车结算流程 > 应正确计算总价"
+      spec: "checkout.spec.ts"
+      error: "期望 ¥99.00 但实际为 ¥99.50"
+      screenshot: "test-results/checkout-failure-1.png"
+      trace: "test-results/trace.zip"
+      
+  performance:
+    page_load_avg_ms: 1200
+    api_response_avg_ms: 230
+    
+  baseline_comparison:
+    regression: false
+    new_failures: 1
+```
+
+---
+
+# ════════════════════════════════════════════════════════
+#  Java 后端 E2E 测试（Testcontainers + Spring Profiles）
+# ════════════════════════════════════════════════════════
+
+> **适用技术栈**: Spring Boot / JDK21 / Testcontainers
+> **参考规则**: `rules/project/java-backend.md` §13 测试规范
+
+---
+
+## Spring Boot Profile 配置
+
+### application-test.yml（单元/集成测试）
+
+```yaml
+# src/test/resources/application-test.yml
+spring:
+  datasource:
+    url: jdbc:h2:mem:testdb;MODE=MySQL;DB_CLOSE_DELAY=-1;DB_CLOSE_ON_EXIT=FALSE
+    driver-class-name: org.h2.Driver
+    username: sa
+    password:
+  jpa:
+    hibernate:
+      ddl-auto: create-drop          # 每次测试自动建表/销毁
+    show-sql: false                  # 生产关闭 SQL 日志
+  redis:
+    host: localhost                   # 需要 Redis 在本地运行，或用 Testcontainers
+    port: 6379
+
+logging:
+  level:
+    root: WARN                       # 减少日志噪音
+    com.jieshun: DEBUG              # 项目包开启 DEBUG
+
+# 测试专用配置
+app:
+  security:
+    sm4-enabled: false               # 测试环境关闭 SM4 加密
+  external:
+    sms-mock: true                   # Mock 短信发送
+    email-mock: true                 # Mock 邮件发送
+```
+
+### application-e2e.yml（端到端测试）
+
+```yaml
+# src/test/resources/application-e2e.yml
+spring:
+  datasource:
+    # 由 Testcontainers 动态注入 URL/用户名/密码
+  redis:
+    # 由 Testcontainers 启动 GenericContainer
+
+# E2E 专用：模拟真实生产配置
+app:
+  security:
+    sm4-enabled: true                # E2E 需要完整安全链路
+  rate-limit:
+    enabled: false                   # E2E 禁用限流避免干扰
+```
+
+---
+
+## Testcontainers — 容器化测试基础设施
+
+### Maven 依赖
+
+```xml
+<!-- pom.xml (test scope) -->
+<dependency>
+    <org.testcontainers>testcontainers</groupId>
+    <artifactId>testcontainers</artifactId>
+    <version>1.19.7</version>
+    <scope>test</scope>
+</dependency>
+<dependency>
+    <org.testcontainers>junit-jupiter</groupId>
+    <artifactId>testcontainers</artifactId>
+    <version>1.19.7</version>
+    <scope>test</scope>
+</dependency>
+<dependency>
+    <org.testcontainers>mysql</groupId>
+    <artifactId>mysql</artifactId>
+    <version>1.19.7</version>
+    <scope>test</scope>
+</dependency>
+<dependency>
+    <org.testcontainers>generic</groupId>
+    <artifactId>testcontainers</artifactId>
+    <version>1.19.7</version>
+    <scope>test</scope>
+</dependency>
+```
+
+### 常用容器模板
+
+```java
+@Testcontainers                          // 自动管理容器生命周期
+@SpringBootTest
+@ActiveProfiles("e2e")
+class OrderE2ETest {
+
+    @Container
+    static MySQLContainer mysql = new MySQLContainer<>("mysql:8.0")
+        .withDatabaseName("jieshun_e2e")
+        .withUsername("e2e_user")
+        .withPassword("e2e_pass")
+        .withInitScript("sql/init-test-data.sql");   // 初始化种子数据
+
+    @Container
+    static GenericContainer<?> redis = new GenericContainer<>("redis:7-alpine")
+        .withExposedPorts(6379)
+        .waitingFor(Wait.forListeningPort());
+
+    // 动态注入连接信息到 Spring 配置
+    @DynamicPropertySource
+    static void configureProperties(DynamicPropertyRegistry registry) {
+        registry.add("spring.datasource.url", () -> {
+            // Testcontainers 提供的 JDBC URL
+            String jdbcUrl = mysql.getJdbcUrl() + 
+                "?useSSL=false&serverTimezone=Asia/Shanghai&allowPublicKeyRetrieval=true";
+            return jdbcUrl;
+        });
+        registry.add("spring.datasource.username", mysql::getUsername);
+        registry.add("spring.datasource.password", mysql::getPassword);
+        registry.add("spring.data.redis.host", redis::getHost);
+        registry.add("spring.data.redis.port", redis::getFirstMappedPort);
+    }
+
+    @Autowired
+    private OrderService orderService;
+
+    @Autowired
+    private ProductService productService;
+
+    @Test
+    @DisplayName("E2E: 下单 → 支付 → 发货 全流程")
+    void shouldCompleteFullOrderLifecycle() {
+        // 1. 创建订单
+        OrderReqVO orderReq = OrderReqVO.builder()
+            .userId("user-001").productId("prod-100").quantity(2).build();
+        RespVO<OrderVO> createResult = orderService.createOrder(orderReq);
+        assertThat(createResult.getCode()).isEqualTo(0);
+
+        // 2. 支付订单
+        PayReqVO payReq = PayReqVO.builder()
+            .orderId(createResult.getData().getId()).amount(new BigDecimal("199.00")).build();
+        RespVO payResult = orderService.pay(payReq);
+        assertThat(payResult.getCode()).isEqualTo(0);
+
+        // 3. 查询确认状态
+        OrderVO updated = orderService.getOrderById(createResult.getData().getId());
+        assertThat(updated.getStatus()).isEqualTo(OrderStatus.PAID);
+    }
+}
+```
+
+---
+
+## Maven E2E 执行命令
+
+```bash
+# === 运行所有 E2E 测试 ===
+mvn verify -P e2e                    # 通过 profile 触发
+
+# === 仅运行 E2E 测试类（带标签）===
+mvn test -Dgroups="e2e" -P e2e      # 使用 JUnit5 Tag
+
+# === 跳过 E2E（日常开发）===
+mvn test -DexcludedGroups="e2e"     # 排除 E2E 标签的测试
+
+# === 带覆盖率报告 ===
+mvn verify -P e2e jacoco:report      # 包含 JaCoCo
+
+# === 并行加速（多模块项目）===
+mvn verify -P e2e -T 4              # 4 线程并行
+```
+
+### pom.xml Profile 定义
+
+```xml
+<profiles>
+    <profile>
+        <id>e2e</id>
+        <properties>
+            <!-- 覆盖 Surefire 的 groups 参数 -->
+            <surefire.groups>e2e</surefire.groups>
+            <!-- 或使用 include/exclude 文件 -->
+        </properties>
+    </profile>
+</profiles>
+```
+
+---
+
+## Java E2E 测试结果输出模板
+
+```yaml
+test_result_e2e_java:
+  timestamp: "2026-05-20T22:00:00Z"
+  framework: "JUnit5 + Testcontainers + Spring Boot"
+  containers_used:
+    - type: "MySQLContainer"
+      image: "mysql:8.0"
+      status: running
+    - type: "GenericContainer (Redis)"
+      image: "redis:7-alpine"
+      status: running
+      
+  status: pass | fail
+  
+  summary:
+    total_tests: 18
+    passed: 17
+    failed: 1
+    skipped: 0
+    duration_seconds: 245
+    
+  failed_tests:
+    - name: "OrderE2ETest > shouldCompleteFullOrderLifecycle > step_3_query_status"
+      file: "src/test/java/com/jieshun/e2e/OrderE2ETest.java:78"
+      error: "Expected status PAID but was CREATED — payment callback not received"
+      
+  container_logs:
+    mysql_init_success: true
+    redis_connected: true
+    
+  performance:
+    avg_test_duration_ms: 13600
+    slowest_test:
+      name: "shouldHandleConcurrentOrders"
+      duration_ms: 45000
+      
+  baseline_comparison:
+    regression: false
+    new_failures: 1
+```