FiftyOne 端到端测试指南:基于 Playwright 的 e2e-pw 测试套件实战
FiftyOne 端到端测试指南:基于 Playwright 的 e2e-pw 测试套件实战
本篇技术指南以 FiftyOne 仓库中的 e2e-pw/README.md 为主体,系统讲解该仓库如何基于 Playwright 构建覆盖 FiftyOne App 核心交互(网格浏览、模态框标注、Canvas 绘制、3D 场景、截图回归)的端到端测试套件。读完本文,你将掌握 e2e-pw 的本地环境搭建、spec 组织规范、Page Object Model(POM)编写模板、Canvas 无头交互测试方法、数据集工厂的底层原理,以及稳定性与排障的完整实践。
一、项目概览:e2e-pw 在 FiftyOne 仓库中的定位
e2e-pw 是 FiftyOne 仓库(根目录为 fiftyone/)下独立的端到端测试工程,位于 e2e-pw/。它以 Playwright(@playwright/test,见 e2e-pw/package.json)为测试框架,直接面向 FiftyOne App 的前端交互层做黑盒测试:从数据集选择器进入网格视图,在模态框中打开单个样本,驱动鼠标键盘在标注画布上操作,并对结果进行截图断言。由于 spec 同时会被 fiftyone-teams 的 CI 复用,本套件在编写上尤其强调测试足够小、足够稳定、可并行。
工程顶层结构如下:
src/oss/:开源版 FiftyOne 的测试代码,其中specs/存放全部测试用例,poms/存放页面对象(POM),fixtures/存放加载器与测试夹具;src/shared/:与 OSS / Teams 共享的工具层,包括dataset-factory/(数据集工厂)、utils.ts(ID 工具)、abstract-loader.ts(加载器抽象)、event-utils/、network-utils/、python-runner/等;scripts/:check-flaky.sh(重复运行探测 flaky)、kill-port.sh(清理占用端口的进程)等辅助脚本;playwright.config.ts:Playwright 配置;eslint.config.cjs:ESLint 新版 flat config。
二、本地环境搭建与运行
2.1 安装与启动步骤
按 e2e-pw/README.md 的 Getting Started 流程,本地运行需要依次完成:
- 安装 VSCode 的 Playwright 扩展,便于在编辑器内直接运行、调试单条测试;
- 准备环境变量文件:将
.env.dev.template复制为.env.dev并填入实际值(该模板文件位于 e2e-pw/.env.dev.template); - 安装依赖:执行
yarn,Node 版本至少 18.x(推荐 20.x,文档建议nvm install 20 && nvm use 20); - 运行测试:
- 命令行运行全部测试:
yarn e2e(等价于playwright test -c playwright.config.ts); - 打开 Playwright UI 模式:
yarn e2e:ui(等价于playwright test --ui -c playwright.config.ts),UI 模式下可以单步调试、录制、查看每个 action 的 DOM 快照; - 也可以直接从 VSCode 的 Playwright 扩展运行;
- 命令行运行全部测试:
- 升级 Playwright 后需执行
yarn playwright install重新下载对应版本的浏览器二进制。
2.2 使用 App 本地开发服务器
默认情况下测试会构建并启动生产模式的 App。若希望针对本地开发服务器运行测试(例如在改 App 源码时做热更新验证):
- 在
.env.dev中设置export USE_DEV_BUILD=true; - 在单独终端执行
yarn devserver启动 App 开发服务器; - 照常从 CLI、VSCode 或 Playwright UI 运行测试。
从 e2e-pw/package.json 可以看到 devserver 脚本的真实组成:
VITE_API=http://localhost:8787 VITE_NO_STATE=true FIFTYONE_DEFAULT_APP_PORT=5193 && (cd ../app && yarn dev --host 0.0.0.0)
即:指定后端 API 地址为 localhost:8787、关闭状态持久化,并在 app/ 下以 yarn dev 启动前端开发服务器。注意:开发构建模式不支持并行执行测试(Parallelization doesn't work with dev build),这是 README 明确提示的已知限制。
2.3 ESLint 编辑器集成
套件采用 ESLint 新版 flat config 格式(配置文件为 e2e-pw/eslint.config.cjs)。若编辑器未能自动识别,可在 VSCode 设置中将 eslint.options 指定为:
{
"overrideConfigFile": "eslint.config.cjs"
}
由于旧版 ESLint 扩展不支持 flat config,必要时需升级扩展。package.json 中的 lint 脚本会先执行 eslint ./src,再执行 tsc --skipLibCheck --noImplicitAny --sourceMap false 做类型检查,是提交前推荐的本地校验方式。
三、配置解读:playwright.config.ts 的关键取舍
e2e-pw/playwright.config.ts 体现了该套件为"CI 稳定 + 本地快速"所做的配置权衡,值得逐一理解:
- 环境变量加载:
dotenv.config({ path: process.env.CI ? ".env.ci" : ".env.dev" }),CI 与本地使用不同的环境文件; - 测试目录与匹配:
testDir: "./src",testMatch: "**/?(*.)+(spec).ts?(x)",即只匹配*.spec.ts/*.spec.tsx; - 超时:默认
timeout: Duration.Seconds(90),注释说明"最慢的合法测试约 30 秒,90 秒的紧上限用于限制挂起测试在重试中的浪费",个别慢 spec 自行设置更长超时; - 并行与重试:
fullyParallel: true;CI 下retries: 1且workers: 1(曾尝试 4 核机器上 2 个 worker,因资源竞争导致 20 个用例超时,最终改为通过 CI 分片扩展并发);本地forbidOnly开启,防止把test.only误提交进 CI; - Reporter:CI 下使用
line+blob(blob 报告跨分片合并后生成权威 PR 评论与 HTML 报告);本地使用line并开启printSteps打印步骤; - Trace:CI 下
on-all-retries,本地retain-on-failure; - testId 属性:
testIdAttribute: "data-cy",即测试中getByTestId匹配data-cy属性(注释说明未来将迁移到data-testid); - 截图容差:
expect.toHaveScreenshot.maxDiffPixelRatio: 0.02,允许 2% 的像素差异——因为标注标签的颜色分配是非确定性的,截图对比需要留出余地; - 浏览器项目:仅配置
chromium一个 project,使用Desktop Chrome设备描述,额外开启clipboard-read/clipboard-write权限、bypassCSP: true,并以--disable-web-security参数启动。
四、Spec 组织与编写模式
4.1 组织规范
所有 spec 直接平铺在 e2e-pw/src/oss/specs/ 目录下,不使用子目录,命名格式为 <short-description>.spec.ts,例如 my-regression-test.spec.ts。从仓库实际文件看,现有约 200 个 spec 覆盖了标注(2D/3D/视频)、网格分页、颜色方案、直方图、嵌入面板、MCAP 播放、点云(PLY/PCD)等主题,每个 spec 相邻的 *-snapshots/ 目录存放其截图基线。
4.2 核心编写模式(Patterns)
README 总结了几条重要的编写纪律:
- 优先使用 POM(Page Object Model):页面、以及 grid、modal、sidebar 这类通用组件都应封装为 POM;
- 断言不进 POM:不要直接在 POM 中写断言逻辑,而是通过组合方式创建包含断言类的 POM(见下文模板中的
MyPOMAsserter); - 禁止
page.waitForTimeout():几乎总有更好的替代方案,例如等待自定义事件(套件在addInitScript中注入了cursor-change、global-loading-screen等自定义事件供 spec 等待); - 保持单个测试足够小:这些 spec 会在 fiftyone-teams CI 中以约 2–4 倍时长运行(服务器启动慢、页面加载慢、截图稳定化耗时),单测超过约 60 秒在那里就有超时风险,大流程应拆成聚焦的小测试;
- 避免
test.describe.serial:除非测试确实依赖彼此状态。串行模式下一次失败会在每次重试时重跑整个文件(重复支付 web 服务器启动与数据集创建成本),且健康的兄弟用例会被标记为 retried,干扰 flake 归因。当测试会改动共享数据(如标注自动保存)时,更推荐让每个测试拥有自己的样本(numSamples配合indexToId定位 ID),而不是把文件串行化; - 截图前先让画布稳定:完成拖拽、把指针移到中性位置后再执行
toHaveScreenshot。截图断言会等待连续相同的帧,因此针对不断重绘的画布每次断言都要付出数秒的稳定化循环。
4.3 Flaky 检测:check-flaky
若怀疑某个测试不稳定,可用 check-flaky 脚本重复运行以确认是否稳定失败:
yarn check-flaky -r 10 -s "video plays with correct label for each slice"
-s传入 spec 文件名或测试标题(必填);-r重复次数(默认 5);-wPlaywright worker 数(默认 1,串行运行)。
其实现位于 e2e-pw/scripts/check-flaky.sh,本质是调用 npx playwright test --workers=<w> --repeat-each=<r> -g "<spec>",结束后打印 FLAKE ANALYSIS REPORT:全部通过则输出 "No flakiness detected",否则输出 "Flakiness detected" 并返回非零退出码,便于接入 CI 门禁。
五、POM 模板:结构与命名规范
README 给出了标准的 POM 模板(e2e-pw/README.md 的 Template for POMs 小节),其核心结构如下:
class MyPOM {
readonly semanticLocator1: Locator;
readonly semanticLocator2: Locator;
readonly assert: MyPOMAsserter;
constructor(private readonly page) {
this.semanticLocator1 = this.page.locator("...");
this.semanticLocator2 = this.page.locator("...");
this.assert = new MyPOMAsserter(this);
}
/**
* All methods that return static locators should be decorated with `get`.
*/
get someElement() {
return this.page.locator("...");
}
/**
* All methods that return dynamic locators should be prefixed with `get`.
*/
getMyElement(param: string) {
return this.page.locator(`...${param}...`);
}
/**
* All actions should be verbs or prefixed with a verb.
*/
async doSomeAction() {
await this.someElement.click();
}
}
class MyPOMAsserter {
constructor(private readonly myPOM: MyPOM) {}
async isFooVisible() {
await expect(this.myPOM.someElement).toBeVisible();
}
}
模板背后是一套严格的命名约定:
- 静态 locator 用
get修饰符(每次访问返回同一元素); - 动态 locator 的方法名以
get为前缀(如getMyElement(param)); - 动作方法用动词或动词前缀(
doSomeAction()); - 断言统一收敛到
XxxAsserter类,通过this.assert暴露,POM 本身不出现expect。
仓库中 e2e-pw/src/oss/poms/modal/sample-canvas/index.ts 的 SampleCanvasPom 就是该模板的工程化实例:它持有 readonly assert: SampleCanvasAsserter,内部维护鼠标坐标状态(#mouseX/#mouseY),对外暴露 click、dblclick、rightClick、move、down、up 等仅含原始指针/键盘语义的原子操作,而断言(cursor、截图、canvas 类型)全部委托给 assert。
六、截图测试(Screenshot Testing)
截图基线是平台相关的,这是本套件最需要注意的坑:
- 官方建议先阅读 Playwright 的 test-snapshots 文档了解快照机制;
- 基线以 CI 容器为准:CI 对比的是在 CI 容器镜像(
ghcr.io/voxel51/fiftyone-e2e)内渲染出的*-chromium-linux.png基线;其他环境的字体栈会有像素级差异,因此只有该镜像的渲染结果是权威的; - 更新 Linux 基线的标准流程:从 CI 失败运行中下载合并报告,取出 actual 截图覆盖基线:
# 下载失败运行的合并报告
gh run download <run-id> -n playwright-report-merged -D /tmp/report
# /tmp/report/data/ 中每个失败截图的 trace zip 记录了
# <name>-{expected,actual,diff}.png 到同名目录 sha 命名文件的映射;
# 用 *actual* 覆盖基线:
cp /tmp/report/data/<actual-sha>.png \
src/oss/specs/<spec>.spec.ts-snapshots/<name>-chromium-linux.png
- 只接受审查过 diff 的 actual:尺寸变化或高亮的 UI 元素属于行为差异而非渲染噪声,不能当作基线更新。
对应到 Playwright 配置,toHaveScreenshot 的 maxDiffPixelRatio: 0.02 为标签颜色非确定性分配留出了 2% 的容差(见 e2e-pw/playwright.config.ts)。
七、测试数据准备:DatasetFactory 与固定 ID
7.1 推荐用法
凡测试需要 FiftyOne 数据集,都应使用 DatasetFactory.createDataset(位于 e2e-pw/src/shared/dataset-factory/index.ts)。它负责生成空白 PNG 图片、为性能考虑直接把样本插入底层 MongoDB 集合,并应用附加的 schema 字段与保存视图:
import { DatasetFactory } from "src/shared/dataset-factory";
await DatasetFactory.createDataset({
datasetName: "my-test-dataset",
numSamples: 5,
numbered: true,
schema: {
ground_truth: "Detection",
uniqueness: "FloatField",
},
// Optional: customize generated image size and fill color.
// Defaults to { fillColor: "white", width: 50, height: 50 }.
imageOptions: {
fillColor: "#ff0000",
width: 100,
height: 100,
},
withSampleData: ({ _id, filepath, index }, { createId }) => ({
// _id, filepath, index are already attached to the sample
ground_truth: {
_cls: "Detection",
label: "cat",
bounding_box: [0.1, 0.1, 0.5, 0.5],
confidence: 0.9,
},
uniqueness: 0.97,
}),
});
从源码可以印证其完整能力与约束:
numSamples必须是> 0且<= 100的整数,否则直接抛错;schema支持Classification/Classifications/Detection/Detections/Polyline/Polylines六种标签类型,以及IntField/FloatField/StringField/DictField标量类型;标签类型会被自动映射为EmbeddedDocumentField并带上embedded_doc_type(见isLabelType与add_sample_field生成的 Python 代码);labelSchemas通过dataset.update_label_schema(field, schema)应用标注标签 schema,并写入dataset.active_label_schemas,全部在创建数据集的单次子进程中完成,无需后续 SDK 调用;savedViews通过dataset.save_view(name, view)保存视图;- 底层 Python 代码直接调用
dataset._sample_collection.insert_many(...)批量写入样本,从而绕开逐条add_sample的开销。
7.2 固定样本 ID:indexToId
每个样本自动获得一个由索引推导的稳定 _id,形式为 000000000000000000000000(24 位十六进制、零填充),方便在断言中按 ID 引用样本:
import { indexToId } from "src/shared/utils";
const firstSampleId = indexToId(0); // "000000000000000000000000"
其实现位于 e2e-pw/src/shared/utils.ts:将非负整数转为 24 位零填充十六进制字符串(负数先按无符号 32 位处理),如 indexToId(255) 返回 "0000000000000000000000ff"。配合 createId(生成 MongoDB 风格 { $oid } 包装),spec 可以精确构造 _id 引用。
7.3 直通模态框:跳过网格导航
若测试只关心模态框(modal)功能、不需要走网格导航,可以直接用固定 ID 过滤出单样本数据集,把 ID 作为 id search 参数传给 waitUntilGridVisible,模态框会立即在该样本上打开:
await fiftyoneLoader.waitUntilGridVisible(page, datasetName, {
searchParams: new URLSearchParams({ id: indexToId(0) }),
});
waitUntilGridVisible 由 e2e-pw/src/oss/fixtures/loader.ts 中的 OssLoader 实现:它会注入初始化脚本(清理 localStorage/sessionStorage、监听 cursor-change 与 global-loading-screen 事件、设置 window.IS_PLAYWRIGHT = true),跳转到 /datasets/<name> 并等待网格或自定义渲染器就绪;失败时自动清理浏览器状态并重试一次。
7.4 其他工厂方法
DatasetFactory 还提供另外两个方法:
createGroupDataset({ datasetName, numGroups, slices }):创建分组数据集,image slice 用生成的 PNG,3D slice 用 PLY 网格包一层.fo3d场景文件,默认布局为left(image)、right(image)、3d(fo3d);seedDetections({ datasetName, field, detections, sampleIndex }):向既有数据集的指定样本写入fo.Detections,detections中每个元素支持maskSize(附加全 1 的方形 mask,生成 mask-detection),替代在 spec 里内联executePythonCode,让生成的 Python 代码集中在一处可审计。
八、Canvas 测试:对黑盒画布的命令式驱动
8.1 为什么不能使用常规定位器
Canvas 交互必须命令式地通过 SampleCanvas POM 的键盘与鼠标方法驱动(挂在 ModalPom 上,即 modal.sampleCanvas)。禁止对 canvas 元素使用 Playwright locator 或无障碍查询——从 DOM 的视角看,canvas 是一个黑盒。其实现 e2e-pw/src/oss/poms/modal/sample-canvas/index.ts 中所有坐标都是相对容器的 [0, 1] 归一化坐标(而非媒体内的坐标)。
8.2 基础交互 API
// Move the pointer to a canvas-relative position (0–1 in both axes)
await modal.sampleCanvas.move(0.5, 0.5);
// Optionally, assert a cursor value change on move
await modal.sampleCanvas.move(0.9, 0.9, "grab");
// Move the pointer by a pixel offset relative to its current position
await modal.sampleCanvas.movePixels(10, -5);
await modal.sampleCanvas.movePixels(10, -5, "grab"); // with optional cursor assertion
// Press and release the mouse button
await modal.sampleCanvas.down();
await modal.sampleCanvas.up();
// Click or double-click at a position
await modal.sampleCanvas.click(0.9, 0.9);
await modal.sampleCanvas.dblclick(0.9, 0.9);
画布对 DOM 不透明,因此可用的断言信号只有截图与光标值:
// Assert the CSS cursor at the current pointer position
await modal.sampleCanvas.assert.hasCursor("default");
await modal.sampleCanvas.assert.hasCursor("nwse-resize");
// Assert the canvas state via screenshot
await modal.sampleCanvas.assert.hasScreenshot("my-test-state.png");
// Assert the canvas type
import { SampleCanvasType } from "src/oss/poms/modal/sample-canvas";
await modal.sampleCanvas.assert.is(SampleCanvasType.LIGHTER);
await modal.sampleCanvas.assert.is(SampleCanvasType.LOOKER);
await modal.sampleCanvas.assert.is(SampleCanvasType.LOOKER3D);
SampleCanvasType 枚举在源码中定义:LIGHTER = "lighter-sample-renderer"、LOOKER = "modal-looker-container"、LOOKER3D = "looker3d",分别对应轻量标注渲染器、2D Looker 与 3D 场景——同一个 POM 通过 assert.is() 即可区分当前样本的渲染器类型。光标断言依赖 waitUntilGridVisible 注入的 __FO_PLAYWRIGHT_CURRENT_CURSOR 状态与 cursor-change 自定义事件(e2e-pw/src/oss/fixtures/loader.ts)。
8.3 截图前的指针归位
编写 canvas 测试时,截图前要把指针移到视口右边缘,避免 hover 状态污染基线:
await modal.sampleCanvas.moveMouseToViewportEdge();
8.4 设计原则:POM 只提供原语,spec 组合语义
SampleCanvasPom 刻意不包含任何语义化动作——不要添加编码具体功能知识的方法(如 clickDetectionHandle、openQuickEdit),键盘与鼠标动作的序列应该在 spec 中表达功能。POM 只提供原始指针/键盘操作,由 spec 把这些原语组合成有意义的交互。
这样做的收益是 canvas 测试在不同媒体类型间保持统一:无论测试目标是 image、video 还是 3D 样本,交互都以同一种方式表达——move、down、up、click。功能在不同媒体类型下可能长得不一样,但测试方式完全一致;写测试的人只需要学习一套模式,spec 因此更易读、更易协作。
九、已知问题与排障清单
README 整理了三个高频问题的处理方式:
Browser / Target has been closed:最可能的原因是某处缺少await。利用 VSCode 的 ESLint 集成(eslint-plugin-playwright已配置在 e2e-pw/package.json)可以提示缺失的await;Error: No tests found:从 VSCode 运行时偶发,执行 "Developer: Reload Window" 即可修复;- 通用 Troubleshooting(按从最可能到最不可能的顺序):
- 运行
yarn kill-port 8787清理占用 8787 端口的残留进程(该脚本位于 e2e-pw/scripts/kill-port.sh); - 重载 VSCode 开发者窗口;
- 关闭此前测试运行遗留的所有浏览器窗口;
- 重启 dev server。
- 运行
另外 package.json 还提供了 yarn unittests(vitest,用于测试非 E2E 的纯逻辑)、yarn lint(eslint + tsc)以及 yarn remove-pw-dbs(清理测试数据库,见 e2e-pw/scripts/del-pw-dbs.sh),可用于日常开发自检。
十、小结
e2e-pw 用一套纪律把"覆盖复杂视觉交互"的端到端测试做到了可维护、可并行、可归因:POM 组合断言类保证结构清晰;命令式 canvas 原语 + 光标/截图断言统一了 2D/3D/视频的测试方式;DatasetFactory 通过固定 _id 与直插 MongoDB 让数据准备又快又确定;截图基线以 CI 容器为唯一权威;check-flaky 与严苛的配置(90 秒超时、单 worker 分片)共同把 flake 控制住。对于任何希望为视觉密集型 Web 应用建立稳定 E2E 体系的团队,这套模式都值得直接借鉴——其完整实现与数百个 spec 实例都可以在仓库 e2e-pw/src/oss/specs/ 中继续研读。