ZeroLabsCo E2E

对线上站点 https://www.zerolabsco.com 的 Playwright 端到端测试套件。 独立项目,与 ZeroLabsCo 应用仓库完全解耦(不 import 应用代码,不共用依赖)。

快速开始

npm install              # 安装 @playwright/test 等
npm run test:e2e:install # 下载 Chromium + Firefox + WebKit 到 D:\browsers(仅首次)
npm run test:e2e         # 默认 Chrome 无头跑,跑完自动打开 HTML 报告

浏览器与多引擎

• 本机 Windows 浏览器统一装在 D:\browsers(C: 盘空间不足,用 PLAYWRIGHT_BROWSERS_PATH 指过去),见 playwright.config.ts 顶部。
• 配置里有 3 个 project:desktop-chromium / desktop-firefox / desktop-webkit(Safari 内核)。
• WebKit 在 Windows 上内存占用大:desktop-webkit project 单独设了 workers: 1 + video: 'off',避免并行开多个 WebKit 实例 + 录视频导致 OOM 崩溃(只影响本地;CI 的 Linux 上 WebKit 稳定,不受此限制)。所以本地跑 WebKit 会偏慢,属正常。

常用命令

命令	说明
npm run test:e2e	Chrome 无头跑全部用例,跑完自动打开 HTML 报告(CI 下不弹)
npm run test:e2e:headed	Chrome 有头
npm run test:e2e:firefox	Firefox 无头
npm run test:e2e:firefox:headed	Firefox 有头
npm run test:e2e:webkit	WebKit(Safari 内核)无头
npm run test:e2e:webkit:headed	WebKit 有头
npm run test:e2e:all	三个引擎全部无头跑一遍
npm run test:e2e:all:headed	三个引擎有头全跑
npm run test:e2e:ui	打开 Playwright UI 模式(可视逐步调试/回放每步页面快照)
npm run test:e2e:report	重新打开最近一次运行的 HTML 报告
npx playwright test e2e/products.spec.ts --project=desktop-firefox --headed	单文件 + 指定引擎 + 有头

本地指定引擎跑单个用例

--project=desktop-chromium|desktop-firefox|desktop-webkit 决定引擎,配合文件路径和 -g 精确到单个用例:

# 单个文件跑在某个引擎上
npx playwright test e2e/products.spec.ts --project=desktop-firefox

# 文件里只跑名字匹配的单个用例
npx playwright test e2e/products.spec.ts -g "category filters" --project=desktop-webkit

# 按行号跑文件中某条用例
npx playwright test e2e/products.spec.ts:31 --project=desktop-chromium --headed

CI

.github/workflows/e2e.yml 在 push / PR / 每日 cron 时跑 Chromium + Firefox + WebKit 三引擎全量 用例(npm run test:e2e:all)。

• 报告无论成败都上传 为 Actions artifact(playwright-report),在 run 页面底部 Artifacts 里下载,用 npx playwright show-report <目录> 打开看。
• push / 每日 cron 时自动部署到 GitHub Pages,部署完成后 run 页面顶部(environment 链接)可直接点开看,不用下载。一次性前置条件:仓库 Settings → Pages → Source 设为 "GitHub Actions"。
• github reporter 把通过/失败写进 run 页面摘要,不下载也能一眼看到三引擎各通过几条。
• PR 触发的 run 只上传 artifact、不部署 Pages(避免每个 PR 互相覆盖页面)。

手动触发参数

Actions → E2E → Run workflow,可填两个参数:

参数	取值	说明
project	all(默认)/ chromium / firefox / webkit	只跑指定引擎
spec	如 e2e/products.spec.ts,留空	只跑某个 spec 文件

自动触发(push / PR / cron)不受影响,始终三引擎全量。

目录结构

e2e/
  fixtures.ts           # 自定义 test:每例结束存全页截图并挂进 HTML 报告
  helpers.ts            # 期望的 URL 与双语文案常量 + scrollTo 稳健滚动
  home.spec.ts          # 首页渲染(中英)
  locale.spec.ts        # 根路径重定向 + 语言切换器
  navbar.spec.ts        # 桌面导航 / 移动端抽屉菜单
  theme.spec.ts         # 主题切换与持久化
  products.spec.ts      # 产品搜索 / 分类筛选 / URL 参数
  interactions.spec.ts  # 交互功能:复制邮箱 / 产品链接下拉切换 / Changelog 弹窗 / mailto
  back-to-top.spec.ts   # 返回顶部按钮

设计要点

• 直接测生产站:playwright.config.ts 无 webServer,baseURL 指向线上。
• 去 flake 手段:reducedMotion: 'reduce' 让 typewriter/mouse-hover 立即渲染全文;除重定向外全部用显式 /en、/zh 路径;语言切换是整页跳转,用 waitForURL。
• 确定性重定向:use.locale='en-US' 保证 / 落在 /en;zh 用例单独 test.use({ locale: 'zh-CN' })。
• 只断言外部链接的 href,不点击,避免离开被测站。
• 每例结束存一张全页截图(无论通过/失败):由 e2e/fixtures.ts 实现,既存到 screenshots/<project>/<用例标题>.png,也通过 testInfo.attach 挂进 HTML 报告,所以 npm run test:e2e:report 里每个用例都能直接看到最终截图。失败时的内置 trace 截图(screenshot: 'only-on-failure')仍照常生成,互不冲突。调试某一步想看得更细时,临时把 config 里 screenshot 改成 'on' 即可。
• WebKit 稳定性:WebKit 上 React hydration 会在 load 后重渲染 DOM,直接 scrollIntoViewIfNeeded 偶发 "Element is not attached"。统一用 helpers.ts 里的 scrollTo()(等 attached + 重试)替代。