Pruebas en TypeScript/JavaScript

Pruebas en TypeScript/JavaScript

【免费下载链接】ECCThe agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.项目地址: https://gitcode.com/GitHub_Trending/ev/ECC

Este archivo extiende common/testing.md con contenido específico de TypeScript/JavaScript.

Testing E2E

UsarPlaywrightcomo framework de testing E2E para flujos de usuario críticos.

Soporte de Agentes

• e2e-runner- Especialista en testing E2E con Playwright

其 YAML frontmatter 的 `paths` 决定了规则的自动触发范围（所有 TS/TSX/JS/JSX 文件）： ```yaml paths: - "**/*.ts" - "**/*.tsx" - "**/*.js" - "**/*.jsx"

按 rules/README.md 中「语言特定规则优先于通用规则」的约定（类似 CSS 特异性），本文件是对通用测试要求的唯一 TypeScript 覆盖点；它本身没有对通用层的覆盖率门槛或 TDD 做任何放宽，因此必须与 rules/common/testing.md 一起阅读生效。安装时应整目录复制（避免/*展开破坏../common/相对引用），参见 rules/README.md。

二、底层红线：80% 覆盖率与三类测试全量必选

该语言规则没有降低通用层的强制要求。rules/common/testing.md 明确规定了每个 TypeScript/JavaScript 项目都必须同时具备：

其中 E2E 层的框架选择，正是本语言规则唯一明确指定的事项：Playwright。这条规则同时出现在 rules/typescript/testing.md 及其西班牙语镜像 docs/es/rules/typescript/testing.md 中，说明它是跨翻译版本被一致执行的语言级决策。

三、强制 TDD：先写测试（RED → GREEN → IMPROVE）

通用规则要求所有 TypeScript 功能开发遵循 TDD 强制流程（rules/common/testing.md）：

1. 先写测试（RED）——测试应先失败；
2. 运行测试，确认失败；
3. 编写最小实现（GREEN）——让测试通过；
4. 重构（IMPROVE）；
5. 校验覆盖率 ≥ 80%。

配套的 agent 是tdd-guide（见 agents/tdd-guide.md），其职责是在新功能开发时主动（PROACTIVELY）强制执行「先写测试」。规则还特别强调排障纪律：优先调用 tdd-guide、检查测试隔离性、核对 mock 是否正确，并且在测试本身无误时修改实现而非修改测试。

四、测试结构规范：AAA 模式与行为化命名

4.1 AAA（Arrange-Act-Assert）三段式

通用规则以 TypeScript 示例约定了测试的标准结构（rules/common/testing.md）：

test('calculates similarity correctly', () => { // Arrange const vector1 = [1, 0, 0] const vector2 = [0, 1, 0] // Act const similarity = calculateCosineSimilarity(vector1, vector2) // Assert expect(similarity).toBe(0) })

4.2 行为化命名

测试名必须描述被测行为而非实现细节：

test('returns empty array when no markets match query', () => {}) test('throws error when API key is missing', () => {}) test('falls back to substring search when Redis is unavailable', () => {})

这种命名的价值在 E2E 场景被进一步放大：行为化描述天然映射到用户旅程（user journey），便于 e2e-runner 在生成用例时直接翻译为「用户动作 + 断言」。

五、E2E 层深挖：Playwright 与专职 agent e2e-runner

语言规则在 E2E 上的落地不止是选型，还绑定了执行主体e2e-runner（完整定义见 agents/e2e-runner.md），其核心职责包括：

1. Test Journey Creation——为关键用户流程编写测试（优先 Agent Browser，回退 Playwright）；
2. Test Maintenance——随 UI 变更维护用例；
3. Flaky Test Management——识别并隔离不稳定测试；
4. Artifact Management——采集截图、视频、trace；
5. CI/CD Integration——保证流水线内稳定运行；
6. Test Reporting——产出 HTML 报告与 JUnit XML。

在 ECC 的命令体系中，这一能力通过/e2e命令暴露给用户（见 docs/es/commands/e2e.md），典型触发场景包括登录、交易、支付等高风险关键流程，以及在发布前验证前后端集成。

5.1 工具优先级：Agent Browser 优先，Playwright 兜底

e2e-runner 的默认偏好是Agent Browser（语义化选择器、AI 优化、内置自动等待，底层构建于 Playwright）：

npm install -g agent-browser && agent-browser install agent-browser open https://example.com agent-browser snapshot -i # 获取带 [ref=e1] 引用的元素 agent-browser click @e1 # 按引用点击 agent-browser fill @e2 "text" # 填充输入框 agent-browser wait visible @e5 # 等待元素可见 agent-browser screenshot result.png

当 Agent Browser 不可用时，回退到原生 Playwright：

npx playwright test # 运行全部 E2E 用例 npx playwright test tests/auth.spec.ts # 只跑指定文件 npx playwright test --headed # 有头模式查看浏览器 npx playwright test --debug # 调试器逐行运行 npx playwright test --trace on # 带 trace 运行 npx playwright show-report # 打开 HTML 报告

5.2 Playwright 配置基线

sdks 中提供了可直接落地的playwright.config.ts，覆盖多浏览器项目、CI 差异化重试与多种报告器：

import { defineConfig, devices } from '@playwright/test' export default defineConfig({ testDir: './tests/e2e', fullyParallel: true, forbidOnly: !!process.env.CI, retries: process.env.CI ? 2 : 0, workers: process.env.CI ? 1 : undefined, reporter: [ ['html', { outputFolder: 'playwright-report' }], ['junit', { outputFile: 'playwright-results.xml' }], ['json', { outputFile: 'playwright-results.json' }] ], use: { baseURL: process.env.BASE_URL || 'http://localhost:3000', trace: 'on-first-retry', screenshot: 'only-on-failure', video: 'retain-on-failure', actionTimeout: 10000, navigationTimeout: 30000, }, projects: [ { name: 'chromium', use: { ...devices['Desktop Chrome'] } }, { name: 'firefox', use: { ...devices['Desktop Firefox'] } }, { name: 'webkit', use: { ...devices['Desktop Safari'] } }, { name: 'mobile-chrome', use: { ...devices['Pixel 5'] } }, ], webServer: { command: 'npm run dev', url: 'http://localhost:3000', reuseExistingServer: !process.env.CI, timeout: 120000, }, })

关键参数解读：

• trace: 'on-first-retry'：首次失败自动重试并捕获 trace，是最省存储的失败调试策略；
• screenshot: 'only-on-failure'+video: 'retain-on-failure'：只在失败时保留证据，对应 e2e-runner 的制品管理职责；
• retries/workers在 CI 与本地差异化：CI 上收紧并发（workers: 1）换取稳定性；
• 三个reporter并行输出：HTML 给人看，JUnit/JSON 喂给 CI 与脚本。

5.3 Page Object Model（POM）范式

e2e-runner 的用例生成与 skill 均强调 POM，将页面选择器与交互封装为类：

import { Page, Locator } from '@playwright/test' export class ItemsPage { readonly page: Page readonly searchInput: Locator readonly itemCards: Locator readonly createButton: Locator constructor(page: Page) { this.page = page this.searchInput = page.locator('[data-testid="search-input"]') this.itemCards = page.locator('[data-testid="item-card"]') this.createButton = page.locator('[data-testid="create-btn"]') } async goto() { await this.page.goto('/items') await this.page.waitForLoadState('networkidle') } async search(query: string) { await this.searchInput.fill(query) await this.page.waitForResponse(resp => resp.url().includes('/api/search')) await this.page.waitForLoadState('networkidle') } async getItemCount() { return await this.itemCards.count() } }

配套的测试骨架遵循test.describe+beforeEach组织用例，并在关键步骤放置expect断言（skills/e2e-testing/SKILL.md）：

import { test, expect } from '@playwright/test' import { ItemsPage } from '../../pages/ItemsPage' test.describe('Item Search', () => { let itemsPage: ItemsPage test.beforeEach(async ({ page }) => { itemsPage = new ItemsPage(page) await itemsPage.goto() }) test('should search by keyword', async ({ page }) => { await itemsPage.search('test') const count = await itemsPage.getItemCount() expect(count).toBeGreaterThan(0) await expect(itemsPage.itemCards.first()).toContainText(/test/i) await page.screenshot({ path: 'artifacts/search-results.png' }) }) test('should handle no results', async ({ page }) => { await itemsPage.search('xyznonexistent123') await expect(page.locator('[data-testid="no-results"]')).toBeVisible() expect(await itemsPage.getItemCount()).toBe(0) }) })

六、关键用户流程的端到端验证实战

docs/es/commands/e2e.md 给出了 e2e-runner 的完整工作样例：将「搜索市场 → 查看结果 → 点击进入 → 查看详情」的用户旅程翻译为多场景用例，并在每个关键步骤验证 API 响应、页面状态与截图取证。

6.1 场景设计三要素

E2E 中等待的真实形态是等待条件而非固定时长，这正是 unstable 测试的主要来源之一：

// 错误：任意超时 await page.waitForTimeout(5000) // 正确：等待具体网络条件 await page.waitForResponse(resp => resp.url().includes('/api/data')) // 正确：使用自动等待的 locator await page.locator('[data-testid="button"]').click()

6.2 高风险流程：金融/交易与 Web3

对于金融与支付类关键流程，skill 强调三个原则：绝不针对生产环境执行真实资金操作、通过 mock 注入链上/provider 行为、对交易确认使用带{ timeout }的响应等待：

test('trade execution', async ({ page }) => { // Skip on production — real money test.skip(process.env.NODE_ENV === 'production', 'Skip on production') await page.goto('/markets/test-market') await page.locator('[data-testid="position-yes"]').click() await page.locator('[data-testid="trade-amount"]').fill('1.0') const preview = page.locator('[data-testid="trade-preview"]') await expect(preview).toContainText('1.0') await page.locator('[data-testid="confirm-trade"]').click() await page.waitForResponse( resp => resp.url().includes('/api/trade') && resp.status() === 200, { timeout: 30000 } ) await expect(page.locator('[data-testid="trade-success"]')).toBeVisible() })

七、不稳定测试（Flaky）治理：隔离、重跑与指标

e2e-runner 与 skill 共同定义了 flaky 治理闭环：

定位问题（本地重跑放大）：

npx playwright test tests/search.spec.ts --repeat-each=10 npx playwright test tests/search.spec.ts --retries=3

隔离问题用例（quarantine）：

test('flaky: complex search', async ({ page }) => { test.fixme(true, 'Flaky - Issue #123') }) test('conditional skip', async ({ page }) => { test.skip(process.env.CI, 'Flaky in CI - Issue #123') })

三类高频成因与修法（来自 skills/e2e-testing/SKILL.md）：

成功指标（agents/e2e-runner.md）：关键流程通过率 100%、整体通过率 > 95%、flaky 率 < 5%、单次测试时长 < 10 分钟、制品可访问。

八、CI/CD 集成与报告产物

规则要求 E2E 在合入主干（merge to main）前执行。Playwright 官方 GitHub Actions 流程可直接对接：

name: E2E Tests on: [push, pull_request] jobs: test: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: actions/setup-node@v4 with: node-version: 20 - run: npm ci - run: npx playwright install --with-deps - run: npx playwright test env: BASE_URL: ${{ vars.STAGING_URL }} - uses: actions/upload-artifact@v4 if: always() with: name: playwright-report path: playwright-report/ retention-days: 30

产物规范：每次运行生成 HTML 报告与 JUnit XML（供 CI 消费）；仅失败时保留截图、视频、trace 压缩包、网络与控制台日志。本地排查命令：

npx playwright show-report # HTML 报告 npx playwright show-trace artifacts/trace.zip # 单步回放 trace

【免费下载链接】ECCThe agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.项目地址: https://gitcode.com/GitHub_Trending/ev/ECC