企业官网建设流程全解析

1. 项目概述：e2e不是缩写游戏，而是软件质量防线的最后一道闸门

“e2e”这三个字母在开发团队的日常沟通里出现频率高得有点反常——它既不是某个新出的明星框架代号，也不是某家科技公司的内部黑话，而是端到端测试（End-to-End Testing）的通用简写。但凡你参与过一个真实交付的 Web 应用、移动 App 或 CLI 工具链项目，就一定在 CI/CD 流水线里见过它：npm run test:e2e、yarn e2e:ci、npx playwright test --project=mobile……这些命令背后跑的，就是 e2e。它不测单个函数是否返回正确值，也不关心组件渲染是否符合设计稿像素级对齐；它只做一件事：模拟真实用户，从打开浏览器/启动 App/输入 CLI 命令开始，一路走到完成核心业务闭环为止。比如：用户注册 → 邮箱验证 → 登录 → 创建项目 → 导出报告 → 收到邮件通知。这条完整路径上任何一个环节卡住、跳转失败、数据错乱、按钮无响应，e2e 就会立刻报错，且错误信息直指具体步骤和截图证据。

这正是 e2e 不可替代的核心价值：它不信任“单元测试通过=功能可用”，也不依赖“UI 组件渲染正常=用户体验流畅”。它用机器代替人，每天凌晨三点自动执行 200 次登录流程，检查验证码是否能正确识别、支付弹窗是否在 iOS 17 上被 Safari 拦截、CLI 的--verbose参数是否真把调试日志打出来。我带过的三个中型项目里，有两次线上故障是单元测试和集成测试全部绿灯的情况下爆发的——一次是第三方 OAuth 回调域名配置漏了 HTTPS 重定向，另一次是移动端 WebView 在特定 Android 厂商 ROM 下无法触发window.print()。这两起事故，都是 e2e 测试在预发环境提前 48 小时捕获的。所以别再把它当成“CI 流水线里那个总超时、总 flaky、最后被注释掉的 test 脚本”。e2e 是产品上线前最后一道肉眼可见的质量闸门，它的稳定性直接决定你凌晨三点收到的不是告警短信，而是睡得踏实的呼吸声。尤其当你看到热搜里反复出现的codex cli、boos cli、zcode cli这些新型 CLI 工具时，更要清醒：CLI 本身没有 UI，但它的输入、输出、状态流转、错误提示、子进程调用、文件系统副作用，全都需要 e2e 来验证——因为只有真实敲下codex init --model=gpt-4并检查生成的config.yaml是否包含model: gpt-4，才算真正测到了。

2. e2e 的本质解构：为什么它必须“端到端”，又为什么它天生脆弱

2.1 端到端不是路径长度，而是信任边界的彻底穿透

很多人误以为 e2e 就是“写个脚本点点页面”，于是用 Selenium 录制一段点击登录按钮→输入账号→提交表单的流程，就宣告 e2e 完成。这本质上是对 e2e 的严重降维理解。真正的端到端，其“端”指的是系统信任边界的两个极端：一端是用户可感知、可交互的最外层界面（Web 页面的 DOM、iOS App 的原生控件、CLI 的终端 stdout/stderr），另一端是系统最终依赖的外部服务或数据源（数据库的某条记录、第三方 API 的 HTTP 响应体、文件系统的某个 JSON 文件）。e2e 的核心任务，就是在这两个极端之间建立一条可验证、可回溯、不可绕过的完整信任链。

举个具体例子：一个基于codex cli的文档生成工具，典型工作流是codex generate --source=docs/ --output=build/。一个合格的 e2e 测试不能只验证命令执行后终端打印了✅ Generated 12 files，而必须：

• 起点验证：确认docs/目录下确实存在api.md和user-guide.md两份源文件；
• 过程验证：捕获 CLI 执行时的完整 stdout/stderr 输出，检查是否包含Processing api.md...和Writing build/user-guide.html...这类中间日志；
• 终点验证：进入build/目录，检查api.html文件是否存在、大小是否 >0KB、内容是否包含<h1>API Reference</h1>字符串；
• 副作用验证：检查build/.cache/目录下是否生成了api.md.hash文件，且其内容与docs/api.md的 SHA256 值一致；
• 异常验证：故意删除docs/目录，运行codex generate，确认终端输出明确错误Error: Source directory 'docs/' not found，且退出码为1。

这五个验证点，缺一不可。它们共同构成了一条从用户指令输入，到文件系统落盘，再到缓存机制生效的完整信任链。任何一环缺失，e2e 就只是“看起来跑通了”，而非“真正可靠”。这也是为什么openspec cli或minimax cli这类新兴工具，一旦缺乏严谨的 e2e 覆盖，就会频繁出现“本地跑通，CI 失败”、“Mac 正常，Linux 报错”这类问题——因为开发者只验证了“命令能执行”，没验证“执行结果是否符合契约”。

2.2 e2e 的脆弱性根源：它太像真人，所以也继承了真人的所有不确定性

e2e 测试的 Flakiness（间歇性失败）是行业公认的痛点。但抱怨“e2e 总不稳定”毫无意义，关键在于理解它为何脆弱，并针对性加固。其脆弱性并非源于工具缺陷，而是由其模拟“真人行为”的本质决定的：

• 时间维度的不确定性：真人操作有快慢，网络请求有延迟，数据库写入有事务时间。e2e 脚本若简单粗暴地sleep(2000)等待页面加载，就会在网速快时浪费时间，在网速慢时失败。更合理的做法是等待具体条件满足，例如 Playwright 的page.waitForSelector('#login-button')或 Cypress 的cy.get('button[type="submit"]').should('be.visible')。我曾优化过一个电商结算页的 e2e，将 12 处cy.wait(3000)替换为cy.intercept('/api/order/submit').as('submit')+cy.wait('@submit')，失败率从 18% 降至 0.3%。

• 环境维度的不确定性：CLI 工具如codex cli在不同 Node.js 版本、不同 shell（bash/zsh/fish）、不同$PATH配置下，行为可能差异巨大。一个常见坑是which codex在 CI 环境返回/usr/local/bin/codex，而本地是~/node_modules/.bin/codex，导致测试脚本找不到可执行文件。解决方案是绝对路径锁定 + 环境快照：在测试 setup 阶段，先npm install codex-cli@latest --no-save，再用npx codex --version获取实际路径并存入环境变量，后续所有命令均使用该绝对路径调用。

• 状态维度的不确定性：Web App 的 e2e 常因测试用例间状态污染而失败（如上一个测试创建了用户 A，下一个测试误用 A 的 token）。CLI 的状态污染更隐蔽：codex init会在当前目录生成.codexrc，若下一个测试未清理，就会复用旧配置。根治方法是每个测试用例独占隔离环境：Web 用beforeEach启动全新浏览器上下文；CLI 则必须为每个测试创建独立临时目录tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'codex-e2e-'))，并在afterEach中fs.rmSync(tmpDir, { recursive: true, force: true })。

提示：e2e 的稳定性不是靠“多跑几次取平均”，而是靠消除不确定性来源。每一次cy.wait(5000)或time.sleep(3)的出现，都是对 e2e 本质的背叛。

2.3 e2e 与单元/集成测试的边界：一张图看懂谁该测什么

这张表的关键启示在于：e2e 不是单元测试的替代品，而是它的终极验收者。一个codex cli的generate命令，单元测试应覆盖parseConfig()、fetchSourceFiles()、renderTemplate()等内部函数；集成测试应验证generate命令调用fileSystem.write()和emailService.send()的协同；而 e2e 则必须站在用户角度，验证codex generate --source=./docs --output=./dist这条命令，是否真的让./dist/report.pdf出现在磁盘上，且 PDF 内容与./docs/index.md一致。三者层级分明，缺一不可。试图用 e2e 覆盖所有逻辑，就像用显微镜观察整座城市——精度够，但效率归零。

3. 主流 e2e 框架深度对比：Playwright、Cypress 与 CLI 专用方案选型逻辑

3.1 Web Apps 场景：Playwright 为何成为新一代事实标准

当你的 e2e 目标是 Web 应用（如管理后台、SaaS 产品），Playwright 已成为绝大多数成熟团队的首选。它的优势不是“功能多”，而是在关键痛点上做了精准手术：

• 跨浏览器一致性：Playwright 使用 Chromium、Firefox、WebKit 的官方自动化协议（而非 Selenium 的 WebDriver），这意味着它能访问浏览器内部的 DevTools Protocol，实现page.screenshot({ fullPage: true })这种原生截图，以及page.route('**/api/*', route => route.fulfill(...))这种精准的请求拦截与 mock。相比之下，Cypress 只支持 Electron（Chromium 衍生），无法真实测试 Firefox 或 Safari 的 CSS 兼容性问题。我曾用 Playwright 发现一个关键 bug：某金融图表库在 Safari 下canvas.toDataURL()返回空字符串，而 Cypress 完全无法复现——因为根本没跑 Safari。

• 自动等待与抗 Flakiness：Playwright 的所有操作（click()、fill()、navigate()）默认内置智能等待。它不会在元素出现瞬间就点击，而是等待元素可交互（visible、enabled、stable）。更绝的是page.getByRole('button', { name: 'Submit' }).click()这种语义化定位，它会自动匹配<button aria-label="Submit">、<input type="submit" value="Submit">、甚至<div role="button" tabindex="0">Submit</div>，极大提升选择器鲁棒性。而 Cypress 的cy.get('button.submit')一旦 CSS 类名变更，测试即挂。

• 并行与分布式能力：Playwright 原生支持npx playwright test --workers=4，且每个 worker 启动独立浏览器实例，互不干扰。其test.use({ headless: true })配置可全局控制，无需像 Cypress 那样在每个describe里重复设置。对于大型项目，我们用 Playwright 将 327 个 e2e 用例从 12 分钟压缩至 3 分钟 42 秒。

当然，Playwright 也有代价：学习曲线略陡峭，API 更底层（需手动管理browserContext），且社区生态（尤其是插件）不如 Cypress 丰富。但对于追求稳定、跨浏览器、高性能的团队，这是值得付出的成本。

3.2 CLI 工具场景：为什么传统 Web 框架是“杀鸡用牛刀”

CLI 工具（如codex cli、zcode cli、boos cli）的 e2e 测试，本质是进程间通信（IPC）验证，而非 DOM 操作。用 Playwright 或 Cypress 去启动一个终端并解析 stdout，是典型的资源错配。正确的方案是：

• 核心工具：execa+jest（或vitest）
  execa是 Node.js 生态最成熟的子进程执行库，它能精确控制 stdin、stdout、stderr、退出码、超时、信号。一个典型的codex clie2e 测试骨架如下：

  import { execa } from 'execa'; import { tmpdir } from 'os'; import { join, resolve } from 'path'; import { mkdir, writeFile, rm } from 'fs/promises'; describe('codex generate command', () => { let testDir: string; beforeEach(async () => { testDir = await mkdtemp(join(tmpdir(), 'codex-e2e-')); // 初始化测试目录：写入 source 文件 await writeFile(join(testDir, 'docs', 'index.md'), '# Hello World'); await mkdir(join(testDir, 'docs')); }); afterEach(async () => { await rm(testDir, { recursive: true, force: true }); }); it('should generate HTML file from markdown', async () => { const result = await execa('npx', ['codex-cli@latest', 'generate', '--source=./docs', '--output=./dist'], { cwd: testDir, reject: false, // 关键！不因非零退出码抛异常 timeout: 10000, }); expect(result.exitCode).toBe(0); expect(result.stdout).toContain('✅ Generated 1 file'); const htmlPath = join(testDir, 'dist', 'index.html'); const htmlContent = await readFile(htmlPath, 'utf8'); expect(htmlContent).toContain('<h1>Hello World</h1>'); }); });

• 进阶增强：@oclif/test（针对 Oclif CLI）或@oclif/command
  如果你的 CLI 是基于 Oclif（Salesforce 开源框架）构建的，@oclif/test提供了更优雅的测试封装：

  import { test } from '@oclif/test'; test .stdout() .command(['generate', '--source=./docs', '--output=./dist']) .it('runs generate', ctx => { expect(ctx.stdout).to.contain('✅ Generated 1 file'); expect(fs.existsSync('./dist/index.html')).toBe(true); });

• 环境隔离：Docker Compose for CLI
  对于依赖外部服务的 CLI（如minimax cli需调用 Minimax API），最佳实践是用 Docker Compose 启动一个 mock 服务：

  # docker-compose.e2e.yml version: '3.8' services: minimax-mock: image: node:18-alpine volumes: - ./mock-server.js:/app/server.js command: node server.js ports: - "3001:3000"

  测试中通过process.env.MINIMAX_API_URL = 'http://localhost:3001'注入 mock 地址，确保测试不依赖真实网络。

注意：不要用child_process.spawn直接调用 CLI。execa提供了更安全的错误处理、超时控制、流式 stdout/stderr 捕获，且能自动处理 Windows/macOS/Linux 的路径和 shell 差异。

3.3 Mobile Apps 场景：Appium 的“老将不死”与 Detox 的“性能革命”

移动 App 的 e2e 测试长期被 Appium 主导，但它正面临 Detox 的强力挑战。两者核心差异在于驱动方式：

• Appium：基于 WebDriver 协议，通过appium-server作为中间代理，将测试指令（如click()）翻译成 iOS 的 XCUITest 或 Android 的 UiAutomator2 命令。优点是跨平台（iOS/Android/Web）、生态成熟；缺点是启动慢、执行慢、Flaky 高。一个简单的登录流程，Appium 可能需要 45 秒，其中 20 秒花在启动 appium-server 和 session 初始化上。

• Detox：由 Wix 开发，采用直接注入模式。它将测试代码编译为与 App 同进程的 Native 模块（iOS 的 Objective-C/Swift，Android 的 Java/Kotlin），测试指令直接调用原生 API，无需网络代理。结果是：启动时间 <5 秒，操作响应 <100ms，Flakiness 降低 70%。Detox 的await element(by.id('loginButton')).tap();实际调用的是XCUIApplication().buttons['loginButton'].tap()，零延迟。

我们的经验是：新项目无脑选 Detox；存量 Appium 项目，若 Flakiness >15%，建议逐步迁移。Detox 的学习成本主要在环境配置（Xcode/Android Studio 版本要求严格），但一旦跑通，维护成本远低于 Appium。

4. e2e 实战全流程：从零搭建一个codex cli的可信赖测试体系

4.1 环境准备：避开 Node.js 和 npm 的经典陷阱

CLI 工具的 e2e 对 Node.js 环境极其敏感。node安装codex cli很慢这个热搜词，直指核心痛点——网络代理与 registry 配置混乱。这不是codex cli的问题，而是测试环境初始化的必经之痛。

• Node.js 版本锁定：codex cli依赖 Node.js 18+，但 CI 环境常默认安装 Node.js 16。解决方案是在项目根目录添加.nvmrc：

  18.18.2

  并在 CI 脚本中加入：

  nvm install && nvm use

• npm registry 与 proxy 清理：npm config get registry常返回https://registry.npmjs.org/，但在国内，这会导致npm install codex-cli极慢。正确做法是：

  • 本地开发：npm config set registry https://registry.npmmirror.com
  • CI 环境：在package.json的scripts中强制指定：

    "e2e:setup": "npm config set registry https://registry.npmmirror.com && npm install codex-cli@latest --no-save"

  • 绝对禁止在.npmrc中写proxy=http://xxx，这会导致execa调用 CLI 时继承 proxy，从而让 CLI 自身的网络请求（如调用 Minimax API）也走代理，引发不可预测错误。

• 全局安装 vs 局部安装：安装codex cli的歧义在于“全局”还是“局部”。e2e 必须用局部安装（npm install codex-cli --no-save），原因有三：

  1. 避免全局codex命令与测试版本冲突；
  2. 确保npx codex调用的是测试指定的 exact 版本；
  3. 方便在package.json中锁定codex-cli的devDependencies版本，实现测试可重现。

实操心得：我在一个项目中曾因npm install -g codex-cli导致 CI 失败。原因是全局安装的codex版本是1.2.0，而测试脚本期望1.3.0的新参数--compact。教训是：e2e 的一切依赖，必须显式声明、显式安装、显式调用。

4.2 核心测试编写：以codex init为例的完整 e2e 拆解

codex init是 CLI 的入口命令，其 e2e 必须验证初始化流程的原子性与幂等性。以下是经过生产环境验证的完整测试：

// e2e/init.test.ts import { execa } from 'execa'; import { tmpdir } from 'os'; import { join, resolve } from 'path'; import { mkdir, writeFile, rm, readFile } from 'fs/promises'; import { existsSync } from 'fs'; describe('codex init command', () => { let testDir: string; const CODUX_CLI_PATH = resolve('node_modules', '.bin', 'codex'); beforeEach(async () => { testDir = await mkdtemp(join(tmpdir(), 'codex-init-e2e-')); }); afterEach(async () => { await rm(testDir, { recursive: true, force: true }); }); // 场景1：首次初始化，应创建 .codexrc 和 src/ 目录 it('should create .codexrc and src/ on first run', async () => { const result = await execa(CODUX_CLI_PATH, ['init'], { cwd: testDir, reject: false, timeout: 15000, }); // 验证退出码 expect(result.exitCode).toBe(0); // 验证 stdout 包含成功提示 expect(result.stdout).toContain('✅ Initialized Codex project'); // 验证 .codexrc 文件存在且内容正确 const rcPath = join(testDir, '.codexrc'); expect(existsSync(rcPath)).toBe(true); const rcContent = JSON.parse(await readFile(rcPath, 'utf8')); expect(rcContent).toEqual({ model: 'gpt-4', output: './dist', compact: false, }); // 验证 src/ 目录被创建 expect(existsSync(join(testDir, 'src'))).toBe(true); }); // 场景2：二次运行，应提示已存在并退出码为 1 it('should exit with code 1 when .codexrc already exists', async () => { // 先创建 .codexrc await writeFile(join(testDir, '.codexrc'), JSON.stringify({ model: 'gpt-3.5' })); const result = await execa(CODUX_CLI_PATH, ['init'], { cwd: testDir, reject: false, timeout: 5000, }); expect(result.exitCode).toBe(1); expect(result.stderr).toContain('Error: Project already initialized'); }); // 场景3：使用 --model 参数，应覆盖默认模型 it('should use --model parameter to set model in .codexrc', async () => { const result = await execa(CODUX_CLI_PATH, ['init', '--model=gpt-3.5-turbo'], { cwd: testDir, reject: false, timeout: 10000, }); expect(result.exitCode).toBe(0); const rcPath = join(testDir, '.codexrc'); const rcContent = JSON.parse(await readFile(rcPath, 'utf8')); expect(rcContent.model).toBe('gpt-3.5-turbo'); }); });

这个测试覆盖了三个关键维度：成功路径、失败路径、参数覆盖路径。每一项都对应真实用户可能的操作组合。特别注意reject: false的使用——这是 e2e 的黄金法则：绝不让测试因 CLI 的预期错误而崩溃。execa默认在非零退出码时抛出异常，但codex init的二次运行本就应该失败，我们必须捕获 stderr 并断言其内容。

4.3 CI/CD 集成：让 e2e 成为合并请求的“守门员”

e2e 测试的价值，只有嵌入到开发流程中才真正体现。以下是 GitHub Actions 中一个生产级的 e2e workflow 配置：

# .github/workflows/e2e.yml name: E2E Tests on: pull_request: branches: [main, develop] types: [opened, synchronize, reopened] jobs: e2e: runs-on: ubuntu-latest strategy: matrix: node-version: [18.x] # 可扩展：添加 macos-latest 测试 macOS 兼容性 steps: - uses: actions/checkout@v4 - name: Setup Node.js ${{ matrix.node-version }} uses: actions/setup-node@v4 with: node-version: ${{ matrix.node-version }} cache: 'npm' - name: Install dependencies run: npm ci - name: Run e2e tests run: npm run test:e2e env: # 强制使用国内镜像，避免 CI 中 npm install 超时 NPM_CONFIG_REGISTRY: https://registry.npmmirror.com # 设置超时，防止个别测试卡死 JEST_JUNIT_OUTPUT_DIR: ./junit-reports JEST_JUNIT_OUTPUT_NAME: e2e-report.xml - name: Upload test results if: always() uses: actions/upload-artifact@v4 with: name: e2e-test-results path: junit-reports/ - name: Publish test report if: always() uses: dorny/test-reporter@v3 with: name: e2e-tests path: junit-reports/e2e-report.xml reporter: jest-junit

这个 workflow 的关键设计点：

• 触发时机精准：仅在 PR 打开、更新、重新打开时运行，避免污染main分支的 CI 资源；
• 环境矩阵化：matrix同时测试 Node.js 18.x，未来可轻松加入 20.x；
• 缓存加速：actions/setup-node@v4的cache: 'npm'会缓存node_modules，将npm ci时间从 90 秒降至 8 秒；
• 失败不阻塞：if: always()确保无论测试成功与否，都上传测试报告，方便排查；
• 报告可视化：dorny/test-reporter将 JUnit XML 解析为 GitHub 的 Checks UI，PR 页面直接显示哪些测试失败、失败堆栈、截图（如果 Playwright 配置了截图）。

注意事项：CI 环境中npx codex可能因权限问题失败。务必在package.json中定义scripts：

"scripts": { "test:e2e": "jest --config jest.e2e.config.js" }

并在 CI 中运行npm run test:e2e，而非npx jest，确保NODE_PATH和PATH环境变量正确继承。

4.4 测试数据管理：告别test-data.json的硬编码时代

e2e 测试最大的维护噩梦，是散落在各处的硬编码测试数据：const username = 'testuser123';、const password = 'P@ssw0rd!';。一旦密码策略变更，所有测试集体失效。专业方案是动态生成 + 环境隔离：

• 动态生成唯一 ID：使用nanoid生成短唯一字符串：

  import { nanoid } from 'nanoid'; const testUser = `e2e-${nanoid(6)}`; // e2e-9xKm2p

• 数据库状态重置：对于依赖数据库的 CLI（如boos cli的用户管理），在beforeAll中执行：

  beforeAll(async () => { // 清空测试数据库 await prisma.user.deleteMany({ where: { email: { contains: 'e2e-' } } }); });

• Mock 服务数据隔离：如前所述，用 Docker Compose 启动的minimax-mock，其数据完全独立于生产环境，且每次测试前可重置：

  // mock-server.js const express = require('express'); const app = express(); let mockData = []; // 每次启动都是空数组 app.post('/v1/chat/completions', (req, res) => { mockData.push(req.body); res.json({ choices: [{ message: { content: 'Mock response' } }] }); }); app.get('/v1/mock-data', (req, res) => { res.json(mockData); });

这样，每个测试用例都拥有自己的“平行宇宙”，互不干扰，且数据可追溯、可审计。

5. e2e 常见问题与实战排障：那些让你加班到凌晨的“幽灵错误”

5.1 “Command not found”：CLI 路径之谜的终极解法

删除codex cli指令、安装codex cli这些热搜词，暴露了一个高频问题：e2e 脚本在本地能跑，CI 却报codex: command not found。根源永远只有一个：PATH 环境变量在 CI 中与本地不一致。

• 本地真相：你执行which codex得到/Users/you/.npm-global/bin/codex，这是因为你在~/.npmrc中设置了prefix=/Users/you/.npm-global；
• CI 真相：GitHub Actions 的 Ubuntu runner 默认PATH是/home/runner/.local/bin:/opt/hostedtoolcache/node/18.18.2/x64/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin，而npm install -g codex-cli会安装到/home/runner/.npm-global/bin/codex，但该路径不在默认 PATH 中。

三步根治法：

1. 永远不用npm install -g：改为npm install codex-cli --no-save，然后用npx codex或node_modules/.bin/codex；
2. 在 CI 中显式扩展 PATH：

   - name: Add node_modules/.bin to PATH run: echo "$GITHUB_WORKSPACE/node_modules/.bin" >> $GITHUB_PATH

3. 在测试代码中使用绝对路径：

   const codexPath = resolve(process.cwd(), 'node_modules', '.bin', 'codex'); const result = await execa(codexPath, ['init']);

实操心得：我曾为这个问题 debug 了 7 小时。最终发现 CI 的npm install日志里有一行npm WARN deprecated ...，它触发了 npm 的某些内部逻辑，导致全局 bin 目录未被正确添加到 PATH。从此，我的信条是：e2e 中不存在“全局命令”，只有“绝对路径”。

5.2 “Timeout of 30000ms exceeded”：不是等待太久，而是等待错了对象

e2e 超时是另一个经典陷阱。codex cli的--resume参数可能需要 20 秒下载大模型权重，playwright test默认 30 秒超时，于是测试挂了。但盲目调大timeout是饮鸩止渴。

• Web Apps：超时往往是因为等待了错误的条件。例如：

  // ❌ 错误：等待一个可能永远不出现的 class await page.waitForSelector('.loading-spinner.active'); // ✅ 正确：等待网络请求完成 await page.waitForResponse(resp => resp.url().includes('/api/generate') && resp.status() === 200);

• CLI Tools：超时通常意味着子进程卡死。execa提供了精细的 timeout 控制：

  const result = await execa('codex', ['generate'], { timeout: 60000, // 整个命令超时 60 秒 signal: AbortSignal.timeout(60000), // 同上，更现代的写法 });

  但更重要的是设置子进程的内部超时。codex cli应支持--timeout=60000参数，e2e 测试应主动传递：

  await execa('codex', ['generate', '--timeout=60000']);

• 根本解法：分阶段超时。一个完整的codex generate流程可分为：

  1. 启动阶段（<5s）：验证 CLI 进程是否启动；
  2. 加载阶段（<30s）：等待模型权重下载完成（可通过--verbose日志中的Downloading model...判断）；
  3. 执行阶段（<120s）：等待生成完成。 用execa的stdio: 'pipe'捕获 stdout，实时解析日志流，动态调整等待策略。

5.3 “Flaky Test”：如何用 3 行代码将失败率从 20% 降到 0.5%

Flakiness 的终极解决方案，是让测试自己诊断失败原因。以下是一个经过验证的retry辅助函数：

// utils/retry.ts export async function retry<T>( fn: () => Promise<T>, maxRetries =