ECC e2e-runner 深度解析：Kiro 平台端到端测试 Agent 的工具链、工作流与 Flaky 测试治理

在 Everything Claude Code（ECC）仓库中，.kiro/agents/e2e-runner.md 定义了 Kiro 平台上的端到端（E2E）测试专家 Agent——e2e-runner。本文以该 Agent 定义为核心，系统讲解其六大职责、以 Agent Browser 为主 / Playwright 为回退的双工具链、Plan → Create → Execute 三段式工作流、定位器与等待策略等关键原则、Flaky 测试的隔离与识别方法，以及可量化的成功指标；并结合仓库中配套的 e2e-testing 技能与安装脚本，说明该 Agent 如何真正落地到你的项目中。读完本文，你可以直接在 Kiro IDE/CLI 中调用该 Agent 生成、维护并执行关键用户旅程的 E2E 测试。

一、e2e-runner 在 ECC 中的定位

e2e-runner 是 ECC 面向 Kiro 平台的 Agent 之一。在仓库根目录的 AGENTS.md 中，它被列为标准 Agent 之一，用途为 "End-to-end Playwright testing"，适用场景是 "Critical user flows"（关键用户流程）；在 docs/COMMAND-AGENT-MAP.md 中，/e2e 命令也映射到该 Agent。

仓库中该 Agent 存在两种载体，内容同源：

• .kiro/agents/e2e-runner.md：面向 Kiro IDE 的 Markdown 格式 Agent，YAML frontmatter 中声明 name: e2e-runner 与 allowedTools: read, write, shell，即允许读写文件与执行 shell 命令——这恰好覆盖"写测试文件 + 跑测试 + 上传产物"的全部操作面；
• **.kiro/agents/e2e-runner.json**：面向 kiro-cli 的 JSON 格式 Agent，allowedTools 为 fs_read / fs_write / shell，prompt 字段内嵌与 MD 版完全一致的提示词。

根据 .kiro/README.md 的说明，ECC 的 .kiro/ 目录提供"双格式"Agent 以最大化兼容性：Markdown 供 IDE 使用（自动选择或显式调用），JSON 供 CLI 使用（/agent swap 切换）。README 对 e2e-runner 的一句话描述是："End-to-end testing specialist. Creates and maintains E2E tests using Playwright or Cypress."

适用前提：e2e-runner 是提示词驱动的 Agent 配置，模型由 Kiro 当前选择决定（README 明确说明 Agent 配置不指定模型）；它本身不是可执行脚本，而是指导 Agent 按既定方法论执行 E2E 测试任务的"角色说明书"。

二、六大核心职责

原文档将职责固化为六条，这也是该 Agent 的"能力契约"：

1. Test Journey Creation（旅程测试创建）——为用户流程（auth、核心功能、支付、CRUD 等）编写测试，优先使用 Agent Browser，回退到 Playwright；
2. Test Maintenance（测试维护）——UI 变更后同步更新测试，防止选择器漂移导致的静默失效；
3. Flaky Test Management（不稳定测试治理）——识别不稳定测试并将其隔离（quarantine），避免污染 CI 信号；
4. Artifact Management（产物管理）——捕获截图、视频、trace，为失败定位提供证据链；
5. CI/CD Integration（流水线集成）——确保测试在 CI 中可靠执行；
6. Test Reporting（测试报告）——生成 HTML 报告与 JUnit XML，供人类和流水线消费。

这六条职责与后文的工作流、原则、Flaky 处理章节是一一对应的闭环：创建 → 维护 → 隔离 → 产物 → CI → 报告。

三、首选工具：Agent Browser

文档明确指出："Prefer Agent Browser over raw Playwright"——理由是它具备语义选择器、AI 优化、自动等待能力，且底层就是构建在 Playwright 之上。这意味着用 Agent Browser 驱动探索式交互时，行为与 Playwright 测试生态兼容，而选择器维护成本更低。

文档给出的完整操作序列如下（可直接复制执行）：

# Setup
npm install -g agent-browser && agent-browser install

# Core workflow
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         # 截图

其核心机制是"引用（ref）"：snapshot -i 先对页面做结构化快照，为每个可交互元素分配 @e1、@e2 之类的短引用，后续操作直接按引用寻址。这规避了传统 CSS/XPath 选择器在 DOM 重构后大面积失效的问题，与后文"语义定位器优先"的原则一脉相承。

四、回退方案：Playwright 直驱

当 Agent Browser 不可用（例如 CI 环境未预装、或需要写长期维护的回归套件）时，Agent 回退到直接使用 Playwright。文档列出的命令面覆盖了日常执行、调试与报告的完整链路：

命令	作用
npx playwright test	运行全部 E2E 测试
npx playwright test tests/auth.spec.ts	只运行指定文件
npx playwright test --headed	有头模式，肉眼观察浏览器行为
npx playwright test --debug	以 inspector 调试逐步执行
npx playwright test --trace on	全程记录 trace，用于失败回溯
npx playwright show-report	本地查看 HTML 报告

其中 --debug 与 --trace on 组合是定位"偶发失败"的标准手段：inspector 允许单步执行到失败动作前，trace 则记录完整的 DOM 快照、网络请求与操作时间线。

五、三段式工作流：Plan → Create → Execute

5.1 Plan（规划）

• 识别关键用户旅程：auth（认证）、核心功能、支付、CRUD；
• 为每条旅程定义三类场景：happy path（主路径）、edge cases（边界）、error cases（异常）；
• 按风险分级排优先级：HIGH（资金相关、认证）、MEDIUM（搜索、导航）、LOW（UI 细节打磨）。

风险分级的意义在于资源分配：CI 预算有限时，HIGH 级旅程必须有完整覆盖与更高重试容忍度，LOW 级则可以从简。

5.2 Create（编写）

• 采用 Page Object Model（POM） 模式组织页面层；
• 定位器优先级：data-testid 属性选择器 > CSS 选择器 > XPath；
• 在关键步骤加断言（fail fast）；
• 在关键点截图取证；
• 使用正确的等待策略，严禁 waitForTimeout。

配套仓库中的 skills/e2e-testing/SKILL.md 给出了该原则的可复制实现。POM 示例中，ItemsPage 类把选择器封装在构造器里，search() 方法演示了"条件等待"的完整写法——先 fill 输入，再用 waitForResponse 等待 /api/search 请求返回，最后 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')
}

对应的测试结构用 beforeEach 统一导航，两个用例分别覆盖"搜索命中"与"无结果"两条路径，并在命中用例末尾 page.screenshot({ path: 'artifacts/search-results.png' }) 留存证据——这正是原文档"关键步骤加断言、关键点截图"两条原则的组合示范。

5.3 Execute（执行）

• 本地连续运行 3–5 次，用重复性暴露 flakiness；
• 将不稳定的测试用 test.fixme() 或 test.skip() 隔离；
• 将产物（报告、截图、trace、视频）上传 CI，保证失败可回溯。

六、关键原则：稳定性从写法开始

原文档的 Key Principles 是该 Agent 的方法论内核，六条原则可归纳为"三个永远不要"：

1. 语义定位器优先：[data-testid="..."] > CSS > XPath。data-testid 是与展示样式解耦的稳定契约，UI 重排不会导致测试失效。
2. 等条件，不等时间：waitForResponse() > waitForTimeout()。固定时长等待在慢环境下必挂、在快环境下白等，是 flaky 的第一大来源。
3. 用自动等待的定位器：page.locator().click() 内建 actionability 等待（可见、稳定、可交互）；裸 page.click(selector) 不做等待。
4. 测试彼此隔离：每个测试独立、无共享状态——这是 CI 并行执行（fullyParallel: true）的前提。
5. 快速失败：每个关键步骤都用 expect() 断言，避免错误在长链路末端才暴露。
6. 重试时留 trace：配置 trace: 'on-first-retry'，只在失败重试时记录 trace，兼顾磁盘开销与可调试性。

skills/e2e-testing/SKILL.md 中"Common Causes & Fixes"一节用 Bad/Good 对照进一步落实了这些原则，例如竞态条件场景：

// Bad: assumes element is ready
await page.click('[data-testid="button"]')

// Good: auto-wait locator
await page.locator('[data-testid="button"]').click()

动画时序场景则推荐"先 waitFor({ state: 'visible' }) + waitForLoadState('networkidle')，再 click"的三步组合。

七、Flaky 测试治理：隔离、识别、归因

7.1 隔离（Quarantine）

原文档给出的隔离范式是给测试加 test.fixme() 并附上 issue 号，让它在报告中以"已知失败"呈现而非"新失败"，从而不干扰对真实回归的判断：

// Quarantine
test('flaky: market search', async ({ page }) => {
  test.fixme(true, 'Flaky - Issue #123')
})

e2e-testing 技能还补充了条件隔离——只在 CI 中跳过（本地仍能跑，保留人工验证通道）：

test('conditional skip', async ({ page }) => {
  test.skip(process.env.CI, 'Flaky in CI - Issue #123')
})

7.2 识别（Identify）

文档与技能给出的识别手段是重复执行放大偶发率：

npx playwright test --repeat-each=10          # 每个用例重复 10 遍
npx playwright test tests/search.spec.ts --repeat-each=10
npx playwright test tests/search.spec.ts --retries=3

7.3 归因（Diagnose）

文档总结的三大常见根因与对策：

根因	对策
竞态条件（元素未就绪）	改用自动等待的 locator() 链式操作
网络时序（数据未返回）	waitForResponse() 等待具体接口
动画时序（点击落在动画中途）	等待 networkidle / 元素稳定后再操作

八、配套能力：e2e-testing 技能提供的工程化模板

原文档在结尾声明：详细的 Playwright 模式、POM 示例、配置模板、CI/CD 流程与产物管理策略见 e2e-testing 技能。仓库中该技能同时存在于 .kiro/skills/e2e-testing/SKILL.md（Kiro 安装后位于 .kiro/skills/）与 skills/e2e-testing/SKILL.md（ECC 主技能库），内容一致。它把 Agent 的职责清单补全为可直接落地的工程产物，以下要点值得逐条对照配置。

8.1 测试目录组织

按"旅程域"分目录，测试文件与 fixtures 分离：

tests/
├── e2e/
│   ├── auth/        # login.spec.ts / logout.spec.ts / register.spec.ts
│   ├── features/    # browse.spec.ts / search.spec.ts / create.spec.ts
│   └── api/         # endpoints.spec.ts
├── fixtures/        # auth.ts / data.ts
└── playwright.config.ts

8.2 生产级 Playwright 配置模板

技能给出了一份带完整注释语义的 playwright.config.ts，逐项对应 Agent 的职责要求：

import { defineConfig, devices } from '@playwright/test'

export default defineConfig({
  testDir: './tests/e2e',
  fullyParallel: true,                 // 测试隔离原则的直接落地
  forbidOnly: !!process.env.CI,        // CI 中禁止 .only 残留
  retries: process.env.CI ? 2 : 0,     // CI 允许 2 次重试
  workers: process.env.CI ? 1 : undefined, // CI 串行降低相互干扰
  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',          // 对应原则 6
    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,
  },
})

几个值得注意的设计取舍：workers 在 CI 中取 1，是用吞吐换确定性，与"Flaky rate < 5%"指标配套；三 reporter 并存分别服务人类、CI 平台与后处理脚本，正好满足 Agent 第六项职责"生成 HTML 报告和 JUnit XML"。

8.3 CI/CD 集成与产物上传

技能给出的流水线示例覆盖 Node 20 环境准备、浏览器依赖安装、环境变量注入与产物上传：

# .github/workflows/e2e.yml（示例）
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

if: always() 是细节上的关键点：测试失败时 playwright-report/ 仍然存在且是排障的唯一入口，若不加该条件，失败现场的 HTML 报告会丢失。

8.4 产物三件套与报告模板

• 截图：整页 fullPage: true、元素级 locator().screenshot() 均可；
• Trace：配置级 trace: 'on-first-retry' 是默认方案，深度调试时可显式 startTracing/stopTracing；
• 视频：video: 'retain-on-failure' + videosPath 只保留失败录像。

技能还附了一份测试报告模板（Date/Duration/Status/Summary/Failed Tests/Artifacts 五段结构），要求对每个失败用例给出文件行号、错误信息、截图路径与"Recommended Fix"——这为 Agent 的"Test Reporting"职责提供了统一格式。

8.5 两类高价值场景模板

• 金融/关键流程：对真实资金操作加 test.skip(process.env.NODE_ENV === 'production', ...)，先断言预览金额再确认，最后用带 resp.status() === 200 条件的 waitForResponse 等待 /api/trade 返回，超时显式设为 30s；
• 钱包/Web3：用 context.addInitScript 注入 mock 的 window.ethereum provider，使连接流程可在无真实钱包的 CI 中确定性地执行。

九、成功指标（量化验收线）

原文档给出了该 Agent 工作质量的五条可度量标准，可作为 CI 看板与复盘的基线：

指标	目标值
关键旅程通过率	100%
整体通过率	> 95%
Flaky 率	< 5%
测试总时长	< 10 分钟
产物	已上传且可访问

"关键旅程 100% + 整体 >95%"的分层指标设计值得借鉴：允许长尾用例有可控失败率，但资金、认证类旅程不允许任何漏网。

十、安装与调用

10.1 安装到 Kiro 项目

.kiro/ 目录自带安装脚本 .kiro/install.sh，采用非破坏性拷贝（不覆盖已有文件），支持三种目标：

cd .kiro
./install.sh /path/to/your/project   # 安装到指定项目
./install.sh                        # 安装到当前目录
./install.sh ~                      # 全局安装到 ~/.kiro/（所有 Kiro 项目生效）

脚本会创建 agents / skills / steering / hooks / scripts / settings 六个子目录并逐类拷贝；e2e-runner.json 与 e2e-runner.md 都会进入目标项目的 .kiro/agents/，e2e-testing 技能进入 .kiro/skills/，二者即构成 Agent + 技能的完整能力面。

10.2 调用方式

根据 .kiro/README.md：

• IDE：在 Kiro 会话中通过 / 显式调用，如 /e2e-runner，或由 IDE 按任务自动选择；
• CLI：kiro-cli --agent e2e-runner 直接以该 Agent 启动会话，或在会话中 /agent swap e2e-runner 切换。

另外，仓库保留了 legacy-command-shims/commands/e2e.md 作为 /e2e 的兼容入口：它只是委托层，声明"维护中的工作流在 skills/e2e-testing/SKILL.md"，行为约定为——为请求的用户流程生成/更新 Playwright 覆盖、只运行相关测试（除非用户明确要求全量）、捕获常规产物并汇报失败与 flaky 风险。/e2e 与 e2e-runner 之间的映射亦见 docs/COMMAND-AGENT-MAP.md。

10.3 在 ECC 多平台体系中的位置

ECC 同时为 Claude Code 等平台维护了同名的 agents/e2e-runner.md，其工具面为 Read, Write, Edit, Bash, Grep, Glob 并额外包含一段"Prompt Defense Baseline"（防提示注入基线）安全条款，正文方法论与 Kiro 版完全一致。可以推断：ECC 通过"同一提示词、多平台封装"的方式，把 e2e-runner 的测试方法论复用到 Claude Code、Kiro 等多个宿主，而各平台的差异仅体现在工具白名单与安全前缀上。

十一、小结

.kiro/agents/e2e-runner.md 定义的 e2e-runner 不是一个孤立的脚本，而是一套可执行的方法论契约：以"六大职责"划定边界，以 Agent Browser / Playwright 双工具链保证可用性，以 Plan → Create → Execute 三段流程规范过程，以"语义定位器、条件等待、自动等待、测试隔离、快速失败、重试留 trace"六原则约束代码风格，以隔离-识别-归因三步治理 flaky，最后用五条量化指标验收。仓库中的 e2e-testing 技能（skills/e2e-testing/SKILL.md、.kiro/skills/e2e-testing/SKILL.md）则把这套方法论落成了 POM 模板、生产级配置、CI 流水线与报告格式。两者配合，覆盖了 E2E 测试从编写到流水线交付的完整生命周期——正如文档结尾的提醒：E2E 测试是生产环境前最后一道防线，它捕获的是单元测试永远看不到的集成问题。