Skip to main content
用可重复的端到端测试在多个浏览器中验证扩展行为。 Extension.js 项目可以使用 Playwright 来测试扩展流程、UI 渲染与集成行为,适用于持续集成 (CI) 与本地环境。

Playwright 测试能力

为什么使用

  • 捕获单元测试错过的运行时回归。
  • 在真实浏览器引擎上验证扩展行为。
  • 在发布前验证多浏览器变更。

典型设置

在项目中安装 Playwright 测试依赖:
创建 playwright.config.ts,定义浏览器项目与报告方式。

推荐基线

自动化契约(推荐)

为了确定性自动化,不要解析终端文本。请使用 Extension.js 生成的元数据文件:
  • dist/extension-js/<browser>/ready.json
  • dist/extension-js/<browser>/events.ndjson(watch/重建事件的换行分隔 JSON)
ready.json(schema v2)包含为脚本/Agent 设计的稳定字段:
  • statusstarting | ready | error | stopped
  • commanddev | start | preview | build
  • browser
  • distPath
  • manifestPath
  • port
  • pid
  • browserPid(启动的浏览器进程,用它来做清理)
  • runId
  • startedAt
  • compiledAt
  • errors
  • runtime:service worker 连接后为 "attached"
  • executorAttachedAt
把这份契约作为就绪和失败的真相来源。完整的字段参考,包括 extensionIdprofilePathcdpPort 以及各种错误状态,见 ready.json

运行测试

标准 Playwright 流程(对 AI 友好)

  1. 以 no-browser 模式启动 Extension.js。
  2. 等到 ready.json 报告 status: "ready"
  3. distPath 中的扩展产物启动 Playwright。
  4. 运行测试并关闭。
关于第 2 步有一个注意点:status: "ready" 只表示编译完成。如果你的测试通过 act 命令(evalstoragereloadopen)驱动扩展,还要等到契约中出现 runtime: "attached"。由 Playwright 启动的浏览器会自己加载 distPath,所以纯 UI 测试只需要 ready

开发模式 vs 测试模式

  • dev 用于 watch 模式迭代(extension dev --no-browser + extension dev --wait)。
  • start 用于生产风格的检查(extension start --no-browser + extension start --wait)。

重要区分:运行模式 vs 就绪门

  • --no-browser运行模式:在不启动浏览器的情况下启动扩展流水线。
  • 就绪门(extension dev --wait --browser=<browser>) 是同步步骤,告诉 Playwright 扩展何时就绪。
--no-browser 生成构建产物。wait 步骤在测试继续前确认就绪。如果你的环境无法运行第二个 CLI 进程,请直接轮询 ready.json 使用如下双进程模式:
  1. 进程 A:extension dev --no-browser
  2. 进程 B:extension dev --wait --browser=<browser> --output json
  3. 仅在 wait 步骤成功退出后再启动 Playwright
面向生产的变体:
  1. 进程 A:extension start --no-browser
  2. 进程 B:extension start --wait --browser=<browser> --output json
  3. 仅在 wait 步骤成功退出后再启动 Playwright
--output json 会在 stdout 上打印一个信封对象,给人看的文案移到 stderr。较旧的 --wait-format 别名仍然可用,但会在 stderr 上给出警告。
headless: false 是必须的,不是偏好。Playwright 默认的 headless 模式运行 Chromium 的 headless_shell 二进制文件,它根本不加载任何扩展。为 CI 把它改成 true 的测试套件 仍然会通过,因为它悄悄地测试了一个没有你的扩展的浏览器。如果要在没有可见窗口的情况下 运行,请保持 headless: false 并在 args 中加上 --headless=new,它使用的是确实支持 扩展的完整 Chromium headless 模式。

针对扩展的实用建议

  • 让测试夹具保持确定性;扩展启动可能对 profile 状态敏感。
  • 优先在扩展 UI 状态上做显式等待,而不是固定超时。
  • 在 CI 中同时跑 Chromium 与 Firefox 项目,获得跨引擎信心。
  • 在失败时捕获 trace/截图/录像,方便加速调试。
  • 在机器可靠性上,优先使用 ready.json/events.ndjson,而不是解析 stdout。

常见陷阱

  • 用固定超时取代基于状态的等待
  • 在 CI 中只跑一个浏览器目标
  • 失败运行未上传产物
  • 让测试耦合于本地 profile 或环境的假设

仓库参考

playwright 模板会搭建一套可用的配置,你可以直接照搬:

下一步

模板演示