Base UI 端到端测试指南Playwright Vite 的 e2e 基础设施解析【免费下载链接】base-uiUnstyled UI components for building accessible web apps and design systems. From the creators of Radix, Floating UI, and Material UI.项目地址: https://gitcode.com/GitHub_Trending/ba/base-ui端到端e2e测试是验证 Base UI 组件在真实浏览器环境下交互行为的关键一环。本文以仓库中 test/e2e/README.md 为骨架结合 test/e2e 目录下的实际源码与测试用例完整讲解 Base UI e2e 测试体系的架构、fixture 编写规范、Playwright 驱动方式以及全量命令的使用方法帮助读者掌握一套可直接复用的无头浏览器 可交互夹具测试范式。e2e 测试的整体架构两块职责一条链路Base UI 的端到端测试被清晰地拆分为两个部分见 test/e2e/README.md渲染出的 UI测试夹具 / test fixtures——即每个待测组件在浏览器中呈现的界面对夹具的编排instrumentation——用一个轻量的 Vite 应用把所有夹具组合起来并提供路由、挂载与调试入口。二者协作的完整链路是main.tsx负责汇总所有夹具并注册路由 → Vite 构建/启动页面 → Playwright 启动 Chromium 无头浏览器 → 通过renderFixture(fixturePath)加载单个夹具 → 回放真实用户操作并断言结果。对应到仓库结构上夹具位于 test/e2e/fixtures按field、menu、navigation-menu、slider等组件分类而测试逻辑位于 test/e2e/index.test.ts。Rendered UI夹具Fixture的组成与编写规范夹具的汇总入口main.tsx所有测试的拼装发生在 test/e2e/main.tsx。它的核心机制是 Vite 的glob importconst globbedFixtures import.meta.glob{ default: React.ComponentTypeunknown }( ./fixtures/**/*.{js,jsx,ts,tsx}, { eager: true, }, );这段代码会以eager: true的方式同步加载./fixtures下所有js/jsx/ts/tsx文件并约定每个文件默认导出一个 React 组件。随后按路径解析出suite组件套件名如field、menu和name注册成e2e-suite/fixturePath形式的路由const [suite, name] path .replace(./, ) .replace(/\.\w$/, ) .split(/); fixtures.push({ path, suite: e2e-${suite}, name, Component: globbedFixtures[path].default, });也就是说每新增一个夹具文件main.tsx会自动为它生成一条可访问的 URL形如/e2e-fixtures/menu/LinkItemNavigation无需手工注册。例如 test/e2e/fixtures/slider/Range.tsx 是一个双滑块Range夹具import * as React from react; import { Slider } from base-ui/react/slider; import styles from ./Range.module.css; export default function RangeSlider() { return ( Slider.Root defaultValue{[25, 30]} Slider.Control className{styles.Control} Slider.Thumb index{0} className{styles.ThumbRed} / Slider.Thumb index{1} className{styles.ThumbBlue} / /Slider.Control Slider.Value>const [ready, setReady] React.useState(false); React.useEffect(() { setReady(true); }, []); return ( div aria-busy{!ready}>div idreact-root/div script typemodule srcmain.tsx/script新增测试的编写规范README 明确给出了一条重要约束新增测试时优先新建组件文件而不是修改已有文件因为修改现有夹具可能无意中破坏既有测试例如改变了某个元素的testid、结构或默认值。从当前 fixtures 目录的组织方式看规范实践是按组件套件建目录field/、menu/、slider/、navigation-menu/等一个场景一个文件命名体现场景语义例如 test/e2e/fixtures/slider/RangeSliderMax.tsx最大值的重叠滑块、test/e2e/fixtures/slider/Inset.tsx内嵌滑块与夹具同名的*.module.css用于隔离样式关键交互元素通过data-testid暴露给测试如menu-trigger、link-one、output等。以 test/e2e/fixtures/menu/LinkItemNavigation.tsx 为例它验证Menu.LinkItem的导航行为夹具中提供了两个带data-testid的链接项和两个页面PageOne、PageTwo测试即可据此断言 URL 与页面内容的跳转。Instrumentation用 Playwright 回放用户操作renderFixture与测试就绪同步仓库使用 Playwright 回放用户操作README 明确说明。每个测试只测单个夹具通过renderFixture(fixturePath)加载例如renderFixture(FocusTrap/OpenFocusTrap)。在 test/e2e/index.test.ts 中renderFixture的实际实现是async function renderFixture(fixturePath: string) { await page.goto(${BASE_URL}/e2e-fixtures/${fixturePath}#no-dev); await page.waitForSelector([data-testidtestcase]:not([aria-busytrue])); }关键点有两个访问地址是http://localhost:5173/e2e-fixtures/fixturePath前缀e2e-fixtures与main.tsx中suite: \e2e-${suite} 的路由设计一一对应通过waitForSelector([data-testidtestcase]:not([aria-busytrue]))等待TestViewer完成渲染即上一节所述的被动副作用已冲刷的就绪信号。启动前容错attemptGoto重试机制考虑到测试运行器与 Vite 服务可能同时启动index.test.ts提供了带重试的导航函数async function attemptGoto(page: Page, url: string): Promiseboolean { const maxAttempts 10; const retryTimeoutMS 250; // 每 250ms 重试一次最多 10 次 for (let attempt 1; attempt maxAttempts; attempt 1) { try { await page.goto(url); didNavigate true; } catch (error) { await delay(retryTimeoutMS); } } return didNavigate; }beforeAll中先启动无头 Chromium再尝试导航若 10 次重试仍失败会抛出带明确指引的错误信息——提示开发者可能忘了先运行pnpm test:e2e:server和pnpm test:e2e:build。从测试用例看断言模式Base UI 的 e2e 测试断言完全基于用户可见/可感知的语义很少依赖实现细节。三个有代表性的例子1. 键盘与焦点Radio 焦点循环——test/e2e/index.test.ts 中Radio /用例验证方向键在选项间循环移动焦点await page.keyboard.press(Tab); await expect(page.getByTestId(one)).toBeFocused(); await page.keyboard.press(ArrowRight); await expect(page.getByTestId(two)).toBeFocused(); await page.keyboard.press(ArrowLeft); await expect(page.getByTestId(three)).toBeFocused(); // 从第一个向左循环到最后一个2. 鼠标拖拽Slider 重叠滑块——Slider /的用例用page.mouse.move/down/up模拟拖拽并断言Slider.Value输出的可访问文本await page.mouse.move(25, 10); await page.mouse.down(); await page.mouse.move(100, 10); await page.mouse.up(); await expect(page.getByRole(status)).toHaveText(25 – 100);3. 路由跳转Menu.LinkItem 导航——Menu /的用例点击链接项后用toHaveURL与页面内容双重断言同时验证了鼠标点击、Enter 键触发和 React RouterLink组合三种路径。这些用例共同印证了 README 中每个测试只测单个夹具的设计断言上下文清晰、失败时定位成本低。命令速查开发与 CI 的完整工作流README 给出了五条核心命令结合仓库根目录 package.json 中的脚本定义可以还原出每条命令背后的真实行为命令描述根 package.json 中的实际定义pnpm test:e2e全量运行cross-env NODE_ENVproduction pnpm test:e2e:build concurrently --success first --kill-others pnpm test:e2e:run pnpm test:e2e:serverpnpm test:e2e:dev准备夹具并启动 Vite 开发服务器vite --config test/e2e/vite.config.mjs -l info --port 5173pnpm test:e2e:run运行测试需先有 dev 服务器或 buildservercross-env VITEST_ENVchromium vitest run --project e2epnpm test:e2e:build构建 Vite 产物用于浏览夹具vite build --config test/e2e/vite.config.mjspnpm test:e2e:server托管夹具构建产物serve test/e2e -p 5173开发模式两个终端并行README 推荐的本地开发姿势是在两个终端分别运行pnpm test:e2e:dev与pnpm test:e2e:run --watchpnpm test:e2e:dev以--port 5173启动 Vite dev server同时在-l info级别输出日志pnpm test:e2e:run --watch让 Vitest 监听测试文件与夹具变更改动即重跑。由于测试文件与服务器地址约定为http://localhost:5173见index.test.ts中的BASE_URLdev server 与测试运行器天然对接迭代体验接近单元测试。全量运行构建 服务 测试的编排pnpm test:e2e是全量执行入口它的三步编排值得拆解先用NODE_ENVproduction执行test:e2e:build产出可浏览的夹具产物用concurrently同时启动test:e2e:run跑测试与test:e2e:server托管产物并以--success first --kill-others保证测试结束后服务随之退出避免进程悬挂。Vite / Vitest 的工程化配置e2e 的 Vite 配置位于 test/e2e/vite.config.mjs它通过mergeConfig复用仓库根目录的 test/vite.shared.config.mjs 公共配置并仅覆盖root为test/e2eexport default mergeConfig( sharedConfig, defineConfig({ root: path.join(process.cwd(), test/e2e), }), );对应的 Vitest 配置在 test/e2e/vitest.config.mts同样mergeConfig自 vitest.shared.mts并做三处关键设定test: { environment: node, testTimeout: (process.env.CIRCLECI true ? 4 : 2) * 1000, browser: { provider: playwright(), enabled: false, }, env: { VITEST_ENV: node, }, }testTimeout在 CircleCI低性能 CPU 环境下自动放宽到 4 秒本地则为 2 秒测试在 Node 环境运行而浏览器实例由测试内手动chromium.launch()创建与renderFixture的page交互vitest run --project e2e中的--project e2e对应根目录 vitest.config.mts 中projects数组里对test/e2e/vitest.config.mts的注册使得 e2e 测试作为独立 project 参与全仓库测试编排。本地调试技巧devtools 与夹具导航main.tsx内置了一套面向开发者的调试界面。通过在地址栏追加 hash 可以控制 devtools 面板#dev开启 devtools显示所有测试的导航列表details/summary idmy-test-summary每个夹具对应一个Link可点击直达对应路由#no-dev关闭 devtools隐藏导航renderFixture统一使用#no-dev确保测试页面无多余干扰元素。此外main.tsx会把testing-library/dom挂到window.DomTestingLibrary并暴露window.elementToString内部使用prettyDOM输出高亮、maxDepth: 1的 DOM 快照方便在 Playwright 的page.evaluate或浏览器控制台里直接检查元素的可读 DOM 结构。小结Base UI e2e 测试体系的设计要点回顾 test/e2e/README.md 与配套源码Base UI 的端到端测试有四个值得借鉴的设计夹具与测试分离fixtures/只管渲染什么index.test.ts只管怎么操作与断言职责单一、可复用约定优于配置glob 自动收集夹具并生成路由新增测试只需放一个默认导出组件的文件可访问性优先断言大量使用getByRole、toHaveText、toHaveURL等用户语义接口而非 DOM 实现细节与 Base UI 组件库accessible web apps的定位一致工程化完备dev/build/server/run 四态命令与 CI 超时适配、启动竞态重试机制保证了本地与持续集成环境下测试的稳定性。如需继续深入可依次阅读夹具样例 test/e2e/fixtures/Radio.tsxRadio 焦点循环、测试主体 test/e2e/index.test.ts 以及汇总入口 test/e2e/main.tsx并结合 test/e2e/vite.config.mjs 与 test/e2e/vitest.config.mts 理解整套构建与运行管线。【免费下载链接】base-uiUnstyled UI components for building accessible web apps and design systems. From the creators of Radix, Floating UI, and Material UI.项目地址: https://gitcode.com/GitHub_Trending/ba/base-ui创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考