FiftyOne 端到端测试指南:基于 Playwright 的 e2e-pw 测试套件实战

原创2026-09-15 09:46:361,752 阅读
文章标签:计算机视觉人工智能机器学习深度学习数据集数据标注数据可视化数据分析AI 评测前端多模态点云Embedding

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 流程,本地运行需要依次完成:

  1. 安装 VSCode 的 Playwright 扩展,便于在编辑器内直接运行、调试单条测试;
  2. 准备环境变量文件:将 .env.dev.template 复制为 .env.dev 并填入实际值(该模板文件位于 e2e-pw/.env.dev.template);
  3. 安装依赖:执行 yarn,Node 版本至少 18.x(推荐 20.x,文档建议 nvm install 20 && nvm use 20);
  4. 运行测试:
    • 命令行运行全部测试: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 扩展运行;
  5. 升级 Playwright 后需执行 yarn playwright install 重新下载对应版本的浏览器二进制。

2.2 使用 App 本地开发服务器

默认情况下测试会构建并启动生产模式的 App。若希望针对本地开发服务器运行测试(例如在改 App 源码时做热更新验证):

  1. 在 .env.dev 中设置 export USE_DEV_BUILD=true;
  2. 在单独终端执行 yarn devserver 启动 App 开发服务器;
  3. 照常从 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 总结了几条重要的编写纪律:

  1. 优先使用 POM(Page Object Model):页面、以及 grid、modal、sidebar 这类通用组件都应封装为 POM;
  2. 断言不进 POM:不要直接在 POM 中写断言逻辑,而是通过组合方式创建包含断言类的 POM(见下文模板中的 MyPOMAsserter);
  3. 禁止 page.waitForTimeout():几乎总有更好的替代方案,例如等待自定义事件(套件在 addInitScript 中注入了 cursor-change、global-loading-screen 等自定义事件供 spec 等待);
  4. 保持单个测试足够小:这些 spec 会在 fiftyone-teams CI 中以约 2–4 倍时长运行(服务器启动慢、页面加载慢、截图稳定化耗时),单测超过约 60 秒在那里就有超时风险,大流程应拆成聚焦的小测试;
  5. 避免 test.describe.serial:除非测试确实依赖彼此状态。串行模式下一次失败会在每次重试时重跑整个文件(重复支付 web 服务器启动与数据集创建成本),且健康的兄弟用例会被标记为 retried,干扰 flake 归因。当测试会改动共享数据(如标注自动保存)时,更推荐让每个测试拥有自己的样本(numSamples 配合 indexToId 定位 ID),而不是把文件串行化;
  6. 截图前先让画布稳定:完成拖拽、把指针移到中性位置后再执行 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);
  • -w Playwright 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)

截图基线是平台相关的,这是本套件最需要注意的坑:

  1. 官方建议先阅读 Playwright 的 test-snapshots 文档了解快照机制;
  2. 基线以 CI 容器为准:CI 对比的是在 CI 容器镜像(ghcr.io/voxel51/fiftyone-e2e)内渲染出的 *-chromium-linux.png 基线;其他环境的字体栈会有像素级差异,因此只有该镜像的渲染结果是权威的;
  3. 更新 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
  1. 只接受审查过 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 整理了三个高频问题的处理方式:

  1. Browser / Target has been closed:最可能的原因是某处缺少 await。利用 VSCode 的 ESLint 集成(eslint-plugin-playwright 已配置在 e2e-pw/package.json)可以提示缺失的 await;
  2. Error: No tests found:从 VSCode 运行时偶发,执行 "Developer: Reload Window" 即可修复;
  3. 通用 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/ 中继续研读。

登录后查看全文
fiftyone