OHIF Viewer 端到端测试指南:基于 Playwright 的用例编写、截图验证与运行调试
OHIF Viewer 端到端测试指南:基于 Playwright 的用例编写、截图验证与运行调试
本指南以 OHIF Viewer 官方 3.11 版 Playwright 测试文档为主体,结合当前仓库(monorepo 根目录的 playwright.config.ts、tests/ 目录下的工具源码)展开,系统讲解如何在 OHIF Viewer 上编写端到端测试:从选定指定研究实例与 Mode、通过 checkForScreenshot 做像素级视觉回归,到模拟鼠标拖拽、通过 page.evaluate 直接驱动 Cornerstone3D 与各 Service,以及如何使用 test:e2e:ui、test:e2e:ci、test:e2e:headed 等脚本和 Playwright VSCode 扩展录制测试。读完本文,你将能够独立为 OHIF 的任何工具、扩展或模式编写稳定、可复现、可纳入 CI 的端到端测试。
OHIF 的 Playwright 测试基础设施概览
OHIF Viewer 使用 Playwright 统一编排:
testDir: './tests':所有*.spec.ts测试文件都放在该目录下(如tests/ArrowAnnotate.spec.ts、tests/SEGHydration.spec.ts、tests/MPR.spec.ts等);globalSetup: './tests/globalSetup.ts':套件运行前先执行一次预热脚本;snapshotPathTemplate: './tests/screenshots{/projectName}/{testFilePath}/{arg}{ext}':截图基准(golden/snapshot)统一落在tests/screenshots/chromium/<spec 名>/<截图名>.png;outputDir: './tests/test-results':失败现场(trace、video 等)输出目录;reporter: [['html', { outputFolder: './tests/playwright-report' }]]:生成 HTML 报告,可用pnpm exec playwright show-report tests/playwright-report打开;use.baseURL: 'http://localhost:3335':所有测试默认访问 3335 端口;testIdAttribute: 'data-cy':OHIF 组件统一以data-cy作为测试定位属性(例如globalSetup.ts中等待[data-cy="Layout"]出现);webServer:每次运行前自动以config/e2e.js+COVERAGE=true+OHIF_PORT=3335启动应用,并开启nyc覆盖率采集;本地开发时reuseExistingServer为真,可复用已启动的 3335 服务。
需要说明的是,虽然 Playwright 官方支持多浏览器项目,当前配置中 firefox 与 webkit 项目被注释保留(注释中分别说明了 Firefox 测试待修复、WebKit 需等 SharedArrayBuffer 支持),当前实际执行的是 chromium 项目。
环境准备与常用运行命令
首次运行前的依赖安装
如果尚未安装过 Playwright 浏览器,需要先执行一次浏览器安装:
bun playwright install
运行测试
仓库根目录 package.json 中定义了完整的 e2e 脚本(底层统一是 pnpm exec playwright test,bun/yarn/pnpm 仅是包管理器前缀差异):
# 交互式 UI 模式运行(编写/调试测试最常用)
bun test:e2e:ui
# CI 模式运行(等价于 test:e2e)
yarn test:e2e:ci
# 有头模式(能看到浏览器窗口,方便观察执行过程)
yarn test:e2e:headed
# 调试模式(--debug,配合 Playwright Inspector)
yarn test:e2e:debug
# 查看详细 HTML 报告
yarn playwright show-report tests/playwright-report
这些脚本分别对应 package.json 中的 test:e2e:ui、test:e2e:ci、test:e2e:headed、test:e2e:debug 与 test:e2e:reporter。test:e2e:ci 在 CI 环境下会启用 fullyParallel、retries: 1、maxFailures: 10、workers: 18(见 playwright.config.ts),并行跑满整机资源,同时限制失败数量防止雪崩。本地开发时这些参数关闭,便于逐个定位问题。
更新截图基准
当功能有意变更导致渲染结果改变时,可以一键用当前渲染结果覆盖旧基准图:
pnpm test:e2e:update
该命令等价于 playwright test --update-snapshots,但注意默认带 -g shouldUpdateThis 过滤,请按实际需要去掉过滤条件后运行。
手动启动 Viewer 以加速开发
默认情况下,运行测试会自动先执行 yarn start(仓库根 package.json 中 start 指向 pnpm run dev,即 @ohif/app 的 dev:viewer)启动 Viewer,再跑测试。如果希望手动启动、让 Playwright 复用已有服务,可以直接先启动应用,再运行测试——配置中的 reuseExistingServer: !process.env.CI 会跳过 webServer 的启动步骤,直接连到已运行的服务上,显著缩短测试迭代周期。需要说明的是:官方文档写作时 Viewer 默认在 http://localhost:3000;当前仓库的 e2e 配置则统一使用 OHIF_PORT=3335,具体端口请以 playwright.config.ts 中的 baseURL 与实际启动命令为准。
编写第一个测试:指定研究实例与 Mode
OHIF 的测试通常按"功能 + 数据集"组织。在 test.beforeEach 中通过 visitStudy 打开指定研究实例,是几乎所有测试的标准入口。visitStudy.ts 提供了两个工具:
visitStudy(page, studyInstanceUID, mode, delay, datasources):最简形式;visitStudyOptions(page, studyInstanceUID, options):结构化选项形式,支持mode、delay、datasources、customization。
从实现看,visitStudy 最终构造的 URL 是:
/<mode>/<datasources>?StudyInstanceUIDs=<studyInstanceUID>
并依次等待 domcontentloaded 与 networkidle 后再按需 waitForTimeout(delay)。例如使用 StudyInstanceUID 2.16.840.1.114362.1.11972228.22789312658.616067305.306.2 和 Basic Viewer 模式:
import { test } from '@playwright/test';
import { visitStudy, checkForScreenshot, screenShotPaths } from './utils/index.js';
test.beforeEach(async ({ page }) => {
const studyInstanceUID = '2.16.840.1.114362.1.11972228.22789312658.616067305.306.2';
const mode = 'Basic Viewer';
await visitStudy(page, studyInstanceUID, mode);
});
test.describe('Some Test', async () => {
test('should do something.', async ({ page }) => {
// Your test code here...
});
});
真实测试(如 tests/ArrowAnnotate.spec.ts)的写法与此一致,只是 mode 通常取 'viewer'(对应 Basic Viewer 的 URL 形式),并传入 2000 毫秒的 delay 等待影像渲染稳定:
test.beforeEach(async ({ page }) => {
const studyInstanceUID = '1.3.6.1.4.1.25403.345050719074.3824.20170125095438.5';
const mode = 'viewer';
await visitStudy(page, studyInstanceUID, mode, 2000);
});
visitStudyOptions 还允许附加查询参数:customization 会被编码为 &customization=...(例如 Customization.spec.ts 通过 ?customization=veterinary/veterinaryOverlay 加载兽医覆盖层配置);datasources 用于切换数据源(默认 ohif)。测试数据本身由 pnpm test:data 命令通过 git submodule 拉取 testdata 目录提供。
视觉回归:用 checkForScreenshot 验证渲染结果
提前规划截图路径
截图是 OHIF 端到端测试最重要的断言手段。截图的"清单"集中在 tests/utils/screenShotPaths.ts,测试执行前就应规划好每个测试各阶段的截图命名。例如在添加测量之后截图,可以这样定义:
const screenShotPaths = {
your_test_name: {
measurementAdded: 'measurementAdded.png',
measurementRemoved: 'measurementRemoved.png',
},
};
仓库中实际的 screenShotPaths.ts 已为 length、angle、circle、ellipse、mpr、threeDOnly、segHydration、rtHydration、jumpToMeasurementMPR、splineContourSegmentation 等数十个测试预定义了大量路径,新增测试时遵循同样的命名模式即可。
在测试中截图断言
规划好路径后,在测试中调用 checkForScreenshot.ts 导出的 checkForScreenshot 即可:
import { test } from '@playwright/test';
import {
visitStudy,
checkForScreenshot,
screenShotPaths,
} from './utils/index.js';
test.beforeEach(async ({ page }) => {
const studyInstanceUID = '2.16.840.1.114362.1.11972228.22789312658.616067305.306.2';
const mode = 'Basic Viewer';
await visitStudy(page, studyInstanceUID, mode);
});
test.describe('Some test', async () => {
test('should do something', async ({ page }) => {
// Your test code here to add a measurement
await checkForScreenshot(
page,
page,
screenShotPaths.your_test_name.measurementAdded
);
});
});
checkForScreenshot 底层封装了 Playwright 的 expect(locator).toHaveScreenshot(),关键行为如下:
- 首次运行自动生成基准图,测试会"失败":第一次运行因没有基准图而报错,但同时会在
tests/screenshots/chromium/<spec 名>/<截图名>.png下生成基准图(当前配置只启用chromium项目,官方文档中提到的firefox/与webkit/目录对应旧版多浏览器配置)。请人工核验生成的基准图确实正确,再提交进仓库作为后续比对的基准。 - 内置重试机制:默认
attempts = 10、delay = 1250毫秒,截图比对不通过时自动重试,避免 GPU 渲染抖动导致偶发失败;若始终失败,抛出原始错误。 - 可调参数(见
CheckForScreenshotProps):maxDiffPixelRatio(默认0.02,允许的最大差异像素比例)、threshold(默认0.05,逐像素色差阈值)、normalizedClip(归一化裁剪区域,按 locator 包围盒比例裁剪)、fullPage(整页截图)、beforeAttempt(每次尝试前回调)。测试中若预期画面会逐渐变化,应优先调大attempts与delay,而不是盲目waitForTimeout后一次性截图。 - 中间产物清理:每次重试前会自动删除
<name>-actual.png、<name>-diff.png、<name>-expected.png等中间产物,保证tests/screenshots目录干净。
视口级截图
针对具体视口(viewport)的渲染断言,OHIF 还提供了 checkForViewportScreenshot(tests/utils/checkForViewportScreenshot.ts)。它把截图范围限定在视口 pane 内,并在每次捕获前通过 viewport.hideAllText() 隐藏全部叠加文字(覆盖层、标注文字、方位标记),避免字体渲染差异干扰像素比对,捕获结束后再 viewport.showAllText() 恢复。典型用法见 tests/ArrowAnnotate.spec.ts:
await checkForViewportScreenshot({
page,
viewport: activeViewport,
screenshotPath: screenShotPaths.arrowAnnotate.arrowAnnotateDisplayedCorrectly0,
});
等待渲染完成再截图
在 tests/utils/waitForViewportsRendered.ts 中提供了基于 Cornerstone3D 渲染状态机的一组等待函数:
waitForAnyViewportNeedsRender(page):等待至少一个视口进入needsRender状态;waitForViewportsRendered(page, options):等待所有视口viewportStatus === 'rendered',且(默认)所有关联 volume 的loadStatus.loaded为真;waitForViewportRenderCycle(page):两者的组合——先等needsRender再等rendered;waitForPaintToSettle(page):再等两个requestAnimationFrame周期加 150ms 空闲,确保 GPU 把最终帧真正提交(settle参数默认开启)。
这正是"渲染完成后截图像素稳定"的工程化答案:checkForScreenshot 处理像素级的轻微抖动,而这些等待函数从渲染管线层面保证截图发生在绘制已落定的时刻,两者配合可大幅降低截图测试的 flakiness。需要留意的是,这些函数依赖命令模块在交互时同步把视口状态置为 needsRender,个别操作(如切换挂载协议)目前不满足该前提,需用显式延迟替代。
模拟鼠标交互:拖拽、点击与双击
医学影像工具的核心交互是鼠标绘制。OHIF 封装了多组模拟工具,全部从 tests/utils/index.ts 统一导出。
拖拽(simulateDrag)
官方文档提及的 simulateDrag 在当前的仓库中对应 simulateDragOnElement.ts 导出的 simulateNormalizedDragOnElement。它最大的优势是使用归一化坐标:所有点位都按元素包围盒(boundingBox)的比例给出(0~1),内部换算成绝对像素,天然避免"拖出元素边界"的问题,也不需要维护易错且难读的绝对坐标。例如在 cornerstone-canvas 上模拟一次拖拽:
import {
visitStudy,
checkForScreenshot,
screenShotPaths,
simulateNormalizedDragOnElement,
} from './utils/index.js';
test.beforeEach(async ({ page }) => {
const studyInstanceUID = '2.16.840.1.114362.1.11972228.22789312658.616067305.306.2';
const mode = 'Basic Viewer';
await visitStudy(page, studyInstanceUID, mode);
});
test.describe('Some Test', async () => {
test('should do something..', async ({ page }) => {
const locator = page.locator('.cornerstone-canvas');
await simulateNormalizedDragOnElement({
locator,
start: { x: 0.3, y: 0.4 },
end: { x: 0.7, y: 0.6 },
});
});
});
simulateNormalizedDragOnElement 支持 button('left' | 'right' | 'middle',默认左键)、delay(每步间隔毫秒,默认 50)、steps(每段中间步数,默认 10,值越大拖拽轨迹越平滑)、mouseUp(是否在终点松开,默认 true)。其底层 simulateNormalizedPathDragOnElement 还支持沿多点路径连续拖拽(mousedown 在路径起点,平滑滑过所有中间点,mouseup 在终点),适合绘制 ROI、套索这类多段轨迹。
点击与双击
tests/utils/simulateClicksOnElement.ts 提供了一系列点击工具:
simulateClicksOnElement({ locator, points, button }):在多个绝对坐标点上依次点击;simulateDoubleClickOnElement({ locator, point }):绝对坐标双击(如 ArrowAnnotate 双击标注重新打开文本编辑框);simulateNormalizedClickOnElement({ locator, normalizedPoint, button }):归一化坐标单击;simulateNormalizedClicksOnElement(...):归一化坐标多次点击;simulateNormalizedDoubleClickOnElement(...):归一化坐标双击。
这些工具与 simulateNormalizedDragOnElement 一样按包围盒比例换算坐标,配合 tests/utils/mouseUtils.ts 的鼠标位置追踪(getMousePosition、initializeMousePositionTracker),可以精确断言鼠标落点。
深入应用内部:page.evaluate 访问 Services、Managers 与 Cornerstone
端到端测试有时需要越过 UI、直接驱动应用内部状态。OHIF 支持在测试中通过 page.evaluate 访问 Cornerstone3D、Services、CommandManager 等运行时对象。AppTypes.Test 类型(定义于 platform/core/src/types/AppTypes.ts 的 namespace AppTypes 中)标注了 window 上可用的句柄:services、commandsManager、extensionManager、config。
例如想直接调用 uiNotificationService 弹出一条 UI 通知:
await page.evaluate(({ services }: AppTypes.Test) => {
const { uiNotificationService } = services;
uiNotificationService.show({
title: 'Test',
message: 'This is a test',
type: 'info',
});
}, await page.evaluateHandle('window'));
注意第二参数 await page.evaluateHandle('window'):它将浏览器 window 对象作为 handle 传入,使回调的第一个参数即 window,从而解构出 services。这类能力在真实测试中广泛使用:
- 访问 Cornerstone3D 渲染引擎:在 tests/JumpToMeasurementMPR.spec.ts 等测试中通过
window.cornerstone.getRenderingEngines()获取渲染引擎与视口,进而调用viewport.getActors()、读取viewportStatus;waitForViewportsRendered.ts 内部也正是依赖window.cornerstone轮询渲染状态; - 读写自定义配置:
addOHIFGlobalCustomizations(tests/utils/OHIFConfiguration.ts)通过(window as any).services?.customizationService.setGlobalCustomization(...)在运行时动态注入定制项; - 断言标注统计:
getAnnotationStats、getSUV、getTMTVModalityUnit、getViewportCanvasStats等工具均基于page.evaluate读取窗口内对象或 canvas 像素数据(见 tests/utils/index.ts 的导出清单)。
page.evaluate 的返回值(如注解 UID 列表、统计数值)可以直接参与断言,这让端到端测试既能验证"用户看到什么",也能验证"内部状态是什么"。
测试工程化细节:预热、Fixture 与 e2e 配置
套件级预热(globalSetup)
globalSetup.ts 在整套测试开始前用 chromium.launch() 打开一次 viewer/ohif?StudyInstanceUIDs=1.3.6.1.4.1.14519...,等待 [data-cy="Layout"] 可见后关闭。目的是预热开发/预览服务器:触发 Rspack 首次(缓慢的)懒编译、填充浏览器与编解码器缓存、拉取研究元数据,否则第一个正式 spec 极易因冷启动超时(冷服务器编译)而失败。该步骤不做任何断言。
自定义 Fixture 与 Page Object
tests/utils/fixture.ts 用 test.extend 扩展了 Playwright 的 test 与 expect(来自 playwright-test-coverage,保证覆盖率采集与断言可用),并注入了两个关键能力:
- 全局自动 fixture
_applyGlobalE2EOHIFBaseline:每个测试开始前自动调用addOHIFConfiguration(page, {}),通过page.addInitScript覆写window.config,默认关闭视口滚动条的各种填充/加载图案显示(见 OHIFConfiguration.ts 的DEFAULT_E2E_OHIF_CUSTOMIZATIONS),消除渲染差异; - 一组 Page Object:
DOMOverlayPageObject、mainToolbarPageObject、leftPanelPageObject、rightPanelPageObject、viewportPageObject、notFoundStudyPageObject,实现定义在 tests/pages,把"点击工具栏图标""选中某个测量""视口内点击坐标"等操作封装为可复用方法。测试通过解构 fixture 参数直接使用,例如ArrowAnnotate.spec.ts中的mainToolbarPageObject.measurementTools.arrowAnnotate.click()。
专用的 e2e 应用配置
Playwright 的 webServer 以 platform/app/public/config/e2e.js 作为应用配置启动。该配置为测试量身定制:
modes: ['@ohif/mode-test']:只挂载测试模式,加快构建与启动;defaultDataSourceName: 'e2e',并定义了e2e、ohif、dicomweb、orthanc等多个数据源;其中e2e指向staticWado: true的/viewer-testdata(由testdata子模块提供静态 WADO 数据),wadoUriRoot/qidoRoot/wadoRoot统一指向本地;customizationUrlPrefixes允许测试通过?customization=加载额外定制;showStudyList: true、investigationalUseDialog.option: 'never'(跳过知情同意弹窗)、maxNumberOfWebWorkers: 3等,共同保证测试环境干净可控。
此外 webServer 命令带有 COVERAGE=true 与 nyc,配合 pnpm test:e2e:coverage 可产出端到端覆盖率报告。
用 Playwright VSCode 扩展录制与调试测试
在 VSCode 中搜索并安装 Playwright 官方扩展,可以获得图形化的测试运行器、用鼠标拾取定位器(locator)以及录制新测试等能力。录制的流程通常是:在扩展面板点击"Record new test"→ 在自动打开的浏览器中手动操作 Viewer(切换工具、绘制测量等)→ 扩展自动生成对应的 Playwright 测试代码,再结合本指南的 visitStudy、screenShotPaths、checkForScreenshot 等工具做规范化改造与断言增强。UI 模式(bun test:e2e:ui)同样提供时间轴回放、步骤断点、实时 locator 校验,是日常编写与调试 OHIF 测试的首选环境。
结语
OHIF Viewer 的 Playwright 测试体系可以概括为一条清晰的链路:用 visitStudy 打开指定研究实例 → 用 simulateNormalizedDragOnElement/点击工具模拟用户交互 → 用 waitForViewportRenderCycle 等待渲染落定 → 用 checkForScreenshot 做像素级视觉断言 → 必要时用 page.evaluate 直连 Services 与 Cornerstone3D 校验内部状态,最后由 playwright.config.ts 与 package.json 中的 test:e2e:ci 等脚本一键接入 CI。截图基准由"首次运行自动生成、人工核验后入库"的流程管理,配合 --update-snapshots 处理有意的渲染变更。这套既有上层交互模拟、又有底层状态验证的分层测试方案,是保障 OHIF 影像渲染与交互质量、并在多扩展/多模式架构下持续演进的基石。