Carbon 设计系统测试指南从 E2E 包验证到 Playwright 组件回归测试【免费下载链接】carbonA design system built by IBM项目地址: https://gitcode.com/GitHub_Trending/carbo/carbon本篇技术指南基于 CarbonIBM 开源设计系统仓库中的 docs/testing.md 编写系统梳理该仓库的端到端测试体系Jest 负责包级packaging测试Playwright 负责组件级视觉与行为回归测试。读完本文你将掌握 Carbon 全套测试命令的用法、avt无障碍测试标签的规范、基于 Storybook 编写 Playwright 测试的方法以及 Chromatic 视觉回归测试的默认模式与g90主题按需开启的配置方式并能在本地复现整套测试流程。一、测试命令速查表Carbon 仓库根目录的 package.json 中定义了测试相关的脚本。文档给出的常用任务与对应命令如下任务命令运行包级测试package testyarn test:e2e运行 Playwright 测试yarn playwright test运行指定的某个 Playwright 测试yarn playwright test path/to/test-e2e.js在指定浏览器中运行 Playwright 测试yarn playwright test --browserchromium在指定项目中运行 Playwright 测试yarn playwright test --projectchromium调试 Playwright 测试yarn playwright test --debug以可见浏览器窗口运行 Playwright 测试yarn playwright test --projectchromium --headed运行匹配指定标签的 Playwright 测试yarn playwright test --grep tag-name运行不匹配指定标签的 Playwright 测试yarn playwright test --grep-invert tag-name几点使用提示yarn test:e2e对应根目录 package.json 中的脚本cross-env BABEL_ENVtest jest -c jest.e2e.config.js其底层配置见 jest.e2e.config.jstestMatch为[rootDir/e2e/**/*-test.js]并复用jest-config-carbon预设。--browser与--project都能限定浏览器--browser是 Playwright 的内建参数直接指定 chromium / firefox / webkit--project则匹配 playwright.config.js 中定义的 project当前仅注册了chromium使用devices[Desktop Chrome]的设备描述。--grep/--grep-invert按测试标题中的文本如avt、vrt过滤用例在 CI 与本地按需挑选测试子集时非常实用。二、测试体系总览Jest 与 Playwright 的分工文档明确指出端到端测试用于验证库的打包产物packaging以及设计系统中组件的观感与行为。两套测试各司其职包级package端到端测试使用 Jest 运行测试目录位于e2e下文件匹配*-test.js。它们验证构建后的包对外暴露的公共 API 是否符合预期。组件级测试使用 Playwright 运行针对真实浏览器中的组件渲染结果覆盖视觉、交互与无障碍行为。以图标包测试为例e2e/icons/PublicAPI-test.js 通过readPackageExports(carbon/icons)读取构建产物的导出列表并与快照比对断言没有语义化版本变更就不应更新导出类似的 e2e/icons-react/PublicAPI-test.js、e2e/pictograms/PublicAPI-test.js 等对 React / Vue / pictogram 各包做相同校验。工具实现见 e2e/test-utils/icon-package.js它在独立 Node 进程中调用icon-package.mjs检查器e2e/test-utils/icon-package.mjs分别验证入口点导出与图标直接路径导入两类失败情况并返回 JSON 结果供快照比对。Playwright 同时被用于其他场景以防视觉回归例如 elements 站点elements包。这类测试同样放置在e2e目录中。三、Playwright 测试的组织方式与配置文件3.1 目录与命名约定文档规定Playwright 组件测试编写在e2e目录中文件匹配模式为*-test.e2e.js。仓库中实际命名更细致例如 e2e/components/Button/Button-test.avt.e2e.js、e2e/components/OverflowMenu/OverflowMenu-test.avt.e2e.js 等。根目录 playwright.config.js 通过正则收紧匹配范围testMatch: /.*-test(.avt|.vrt)?.e2e\.m?js$/,即只有带.avt或.vrt标记的-test.e2e.js文件才会被 Playwright 收集这也与文档中avt标签体系见下文呼应。3.2 关键配置项从 playwright.config.js 可以提炼出以下值得关注的配置testDir指向e2e目录testIgnore排除e2e/icons、e2e/icons-react、e2e/icons-vue、e2e/pictograms、e2e/pictograms-react等图标/ Pictogram 包目录这些由 Jest 快照测试覆盖避免重复timeout: 10000 * 30与expect: { timeout: 100000 }单个测试与断言的长超时设置以容纳 Storybook 页面加载与字体资源就绪forbidOnly: !!process.env.CI、retries: process.env.CI ? 2 : 0CI 环境下禁止test.only且失败自动重试 2 次use.baseURL: http://localhost:3000所有测试页面默认基于本地 Storybook 地址use.trace: on-first-retry首次重试时记录 trace便于排查 CI 偶发失败projects当前仅注册chromiumDesktop ChromereporterCI 使用简洁的dot、本地使用line同时始终输出blob与 JSON 报告含一份用于无障碍状态报告的INTERNAL_AVT_REPORT_DO_NOT_USE.json。3.3 内置的自定义匹配器配置文件还通过expect.extend注入了两个仓库级自定义匹配器测试中可直接使用toHaveNoACViolations(page, id)基于accessibility-checker的IBM_Accessibility规则集做无障碍合规扫描并内置一份denylist如html_lang_exists、page_title_exists、skip_main_exists等站点级规则生成自定义规则集后执行断言返回失败时附带stringifyResults的完整报告。toContainAStory(page, options)通过断言页面存在cds--layout类元素来判断 Storybook story 是否真实渲染而非错误页失败信息会输出 component / story / id / globals / args 便于排查。四、avt 无障碍测试标签体系文档规定Playwright 测试按标签分类avt标签用于填充 carbondesignsystem.com 组件页面上的无障碍测试状态。对于 avt 测试测试标题必须始终包含以下标签之一标签说明avt高层级/根标签应包裹所有 avt 测试通常放在describe块标题中avt-default-stateavt的子标签标记覆盖组件默认状态的单个测试avt-advanced-statesavt的子标签标记覆盖组件高级状态的单个测试打开/关闭、invalid、expanded 等avt-keyboard-navavt的子标签标记覆盖键盘导航流程的单个测试实际用例可参考 e2e/components/Button/Button-test.avt.e2e.jstest.describe(avt Button, () { test(avt-default-state, async ({ page }) { await visitStory(page, { component: Button, id: components-button--default, globals: { theme: white }, }); await expect(page).toHaveNoACViolations(Button); }); test(avt-keyboard-nav, async ({ page }) { await visitStory(page, { component: Button, id: components-button--default, globals: { theme: white }, }); await expect(page.getByRole(button).first()).toBeVisible(); await page.keyboard.press(Tab); await expect(page.getByRole(button).first()).toBeFocused(); }); });可以看到avt置于describe标题默认状态、键盘导航分别落在独立test的标题中无障碍断言统一走toHaveNoACViolations交互断言则借助 Playwright 的 role 选择器与keyboard.press(Tab)验证焦点流转。借助--grep avt即可只跑无障碍测试子集。五、本地开发启动 Storybook 并编写组件测试文档强调在本地使用 Playwright 时必须先启动被测服务。对于 React 组件需要在仓库根目录执行cd packages/react yarn storybookStorybook 加载完成后即可用 e2e/test-utils/storybook 中的工具编写并运行测试。该工具的入口是 e2e/test-utils/storybook.js其visitStory(page, options)承担了从参数到 URL 的全部构造逻辑支持component/story/id定位 story无id时自动拼接为components-${component}--${story}支持globals如主题theme: g10与args组件参数如disabled: true分别以globals...、args...追加到 URL页面地址在 CI 下使用/iframe?id...viewModestory静态 Storybook 会去掉.html后缀本地使用/iframe.html?id...viewModestory页面加载后先断言toContainAStory再等待document.fonts.ready确保 IBM Plex 字体资源完整加载保证视觉回归VRT截图稳定。文档给出的标准测试骨架如下// e2e/components/component/component-test.e2e.js use strict; const { test } require(playwright/test); const { themes } require(../../test-utils/env); const { visitStory } require(../../test-utils/storybook); test.describe(component-name vrt, () { themes.forEach((theme) { test(theme, async ({ page }) { await visitStory(page, { component: component, story: story-name, globals: { theme }, }); }); }); });其中themes来自 e2e/test-utils/env.jsconst themes [white, g10, g90, g100];即每个视觉回归 story 会依次在 white、g10、g90、g100 四种主题下跑一遍vrt标签用于标识视觉回归用例。六、调试 Playwright 测试文档推荐两种调试方式Playwright 的 VS Code 集成可直接在编辑器中单步执行、打断点--debug标志运行yarn playwright test --debug会打开 Playwright Inspector可逐步执行测试、查看当前页面状态并快速拾取可用的选择器便于定位用什么选择器命中测试目标。调试时也可配合--projectchromium --headed以真实可见的浏览器窗口观察测试过程。七、Chromatic 视觉回归测试与 g90 按需开启7.1 默认测试模式Chromatic 被用于 Storybook stories 的视觉回归测试。默认情况下stories 会在以下三种模式下被截图g10主题g100主题breakpoint-sm视口g90主题被有意排除在全局 Chromatic 覆盖之外以降低快照体积但当个别 story 需要如修复特定主题的 bug 或视觉回归时可以按需开启。7.2 为单个 story 开启 g90从 Storybook 的 modes 配置导入allModes并在 story 的chromatic.parameters.modes中显式声明import { allModes } from ../../.storybook/modes; export const MyStory { parameters: { chromatic: { modes: { g10: allModes[g10], g90: allModes[g90], // Opt into g90 coverage g100: allModes[g100], }, }, }, };注意原文档中的相对导入路径../../.storybook/modes是相对于 story 源码文件位于packages/react/src深层目录而言的其真实定义位于 packages/react/.storybook/modes.js。该文件从carbon/themes引入主题 token注册了g10/g90/g100三种背景模式以及breakpoint-sm/breakpoint-md/breakpoint-lg/breakpoint-xlg/breakpoint-max五种视口模式即allModes的完整来源。这种全局默认 局部 opt-in的策略既保证了大多数 story 有视觉回归基线又允许在必要时针对g90定向补充快照。八、FAQ浏览器可执行文件缺失问题为什么看到browserType.launch: Executable doesnt exist at ../path这是因为 Playwright 需要在 Chromium、Firefox 等真实浏览器内核中运行测试而这些浏览器可执行文件需要单独下载安装。在仓库根目录执行yarn playwright install即可完成安装。若网络受限或需要指定浏览器版本也可查看 Playwright CLI 的install --help了解可选参数如仅安装 chromiumyarn playwright install chromium。九、把测试纳入日常开发总结 Carbon 仓库测试实践的可复用要点分层明确包导出/公共 API 的稳定性用 Jest 快照yarn test:e2e组件观感、交互与无障碍用 Playwrightyarn playwright test命名即约定*-test.avt.e2e.js无障碍、*-test.vrt.e2e.js视觉回归由 playwright.config.js 的testMatch正则统一收集标签驱动筛选avt系列标签 --grep/--grep-invert实现按需执行Storybook 即测试台通过 e2e/test-utils/storybook.js 的visitStory把 story 参数化主题、args后作为被测页面CI 与本地仅 URL 形态不同有无.html后缀无障碍内建toHaveNoACViolations自定义匹配器将accessibility-checker的 IBM 规则集接入断言配合avt-keyboard-nav覆盖键盘可达性视觉回归分层Chromatic 默认g10g100breakpoint-smg90按 story 通过chromatic.modes显式 opt-in参考 packages/react/.storybook/modes.js。如需深入阅读可继续查看测试总览 docs/testing.md、根级测试脚本 package.json、Playwright 配置 playwright.config.js、Jest E2E 配置 jest.e2e.config.js以及大量真实用例目录 e2e/components 与 e2e/test-utils。【免费下载链接】carbonA design system built by IBM项目地址: https://gitcode.com/GitHub_Trending/carbo/carbon创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Carbon 设计系统测试指南：从 E2E 包验证到 Playwright 组件回归测试
Carbon 设计系统测试指南从 E2E 包验证到 Playwright 组件回归测试【免费下载链接】carbonA design system built by IBM项目地址: https://gitcode.com/GitHub_Trending/carbo/carbon本篇技术指南基于 CarbonIBM 开源设计系统仓库中的 docs/testing.md 编写系统梳理该仓库的端到端测试体系Jest 负责包级packaging测试Playwright 负责组件级视觉与行为回归测试。读完本文你将掌握 Carbon 全套测试命令的用法、avt无障碍测试标签的规范、基于 Storybook 编写 Playwright 测试的方法以及 Chromatic 视觉回归测试的默认模式与g90主题按需开启的配置方式并能在本地复现整套测试流程。一、测试命令速查表Carbon 仓库根目录的 package.json 中定义了测试相关的脚本。文档给出的常用任务与对应命令如下任务命令运行包级测试package testyarn test:e2e运行 Playwright 测试yarn playwright test运行指定的某个 Playwright 测试yarn playwright test path/to/test-e2e.js在指定浏览器中运行 Playwright 测试yarn playwright test --browserchromium在指定项目中运行 Playwright 测试yarn playwright test --projectchromium调试 Playwright 测试yarn playwright test --debug以可见浏览器窗口运行 Playwright 测试yarn playwright test --projectchromium --headed运行匹配指定标签的 Playwright 测试yarn playwright test --grep tag-name运行不匹配指定标签的 Playwright 测试yarn playwright test --grep-invert tag-name几点使用提示yarn test:e2e对应根目录 package.json 中的脚本cross-env BABEL_ENVtest jest -c jest.e2e.config.js其底层配置见 jest.e2e.config.jstestMatch为[rootDir/e2e/**/*-test.js]并复用jest-config-carbon预设。--browser与--project都能限定浏览器--browser是 Playwright 的内建参数直接指定 chromium / firefox / webkit--project则匹配 playwright.config.js 中定义的 project当前仅注册了chromium使用devices[Desktop Chrome]的设备描述。--grep/--grep-invert按测试标题中的文本如avt、vrt过滤用例在 CI 与本地按需挑选测试子集时非常实用。二、测试体系总览Jest 与 Playwright 的分工文档明确指出端到端测试用于验证库的打包产物packaging以及设计系统中组件的观感与行为。两套测试各司其职包级package端到端测试使用 Jest 运行测试目录位于e2e下文件匹配*-test.js。它们验证构建后的包对外暴露的公共 API 是否符合预期。组件级测试使用 Playwright 运行针对真实浏览器中的组件渲染结果覆盖视觉、交互与无障碍行为。以图标包测试为例e2e/icons/PublicAPI-test.js 通过readPackageExports(carbon/icons)读取构建产物的导出列表并与快照比对断言没有语义化版本变更就不应更新导出类似的 e2e/icons-react/PublicAPI-test.js、e2e/pictograms/PublicAPI-test.js 等对 React / Vue / pictogram 各包做相同校验。工具实现见 e2e/test-utils/icon-package.js它在独立 Node 进程中调用icon-package.mjs检查器e2e/test-utils/icon-package.mjs分别验证入口点导出与图标直接路径导入两类失败情况并返回 JSON 结果供快照比对。Playwright 同时被用于其他场景以防视觉回归例如 elements 站点elements包。这类测试同样放置在e2e目录中。三、Playwright 测试的组织方式与配置文件3.1 目录与命名约定文档规定Playwright 组件测试编写在e2e目录中文件匹配模式为*-test.e2e.js。仓库中实际命名更细致例如 e2e/components/Button/Button-test.avt.e2e.js、e2e/components/OverflowMenu/OverflowMenu-test.avt.e2e.js 等。根目录 playwright.config.js 通过正则收紧匹配范围testMatch: /.*-test(.avt|.vrt)?.e2e\.m?js$/,即只有带.avt或.vrt标记的-test.e2e.js文件才会被 Playwright 收集这也与文档中avt标签体系见下文呼应。3.2 关键配置项从 playwright.config.js 可以提炼出以下值得关注的配置testDir指向e2e目录testIgnore排除e2e/icons、e2e/icons-react、e2e/icons-vue、e2e/pictograms、e2e/pictograms-react等图标/ Pictogram 包目录这些由 Jest 快照测试覆盖避免重复timeout: 10000 * 30与expect: { timeout: 100000 }单个测试与断言的长超时设置以容纳 Storybook 页面加载与字体资源就绪forbidOnly: !!process.env.CI、retries: process.env.CI ? 2 : 0CI 环境下禁止test.only且失败自动重试 2 次use.baseURL: http://localhost:3000所有测试页面默认基于本地 Storybook 地址use.trace: on-first-retry首次重试时记录 trace便于排查 CI 偶发失败projects当前仅注册chromiumDesktop ChromereporterCI 使用简洁的dot、本地使用line同时始终输出blob与 JSON 报告含一份用于无障碍状态报告的INTERNAL_AVT_REPORT_DO_NOT_USE.json。3.3 内置的自定义匹配器配置文件还通过expect.extend注入了两个仓库级自定义匹配器测试中可直接使用toHaveNoACViolations(page, id)基于accessibility-checker的IBM_Accessibility规则集做无障碍合规扫描并内置一份denylist如html_lang_exists、page_title_exists、skip_main_exists等站点级规则生成自定义规则集后执行断言返回失败时附带stringifyResults的完整报告。toContainAStory(page, options)通过断言页面存在cds--layout类元素来判断 Storybook story 是否真实渲染而非错误页失败信息会输出 component / story / id / globals / args 便于排查。四、avt 无障碍测试标签体系文档规定Playwright 测试按标签分类avt标签用于填充 carbondesignsystem.com 组件页面上的无障碍测试状态。对于 avt 测试测试标题必须始终包含以下标签之一标签说明avt高层级/根标签应包裹所有 avt 测试通常放在describe块标题中avt-default-stateavt的子标签标记覆盖组件默认状态的单个测试avt-advanced-statesavt的子标签标记覆盖组件高级状态的单个测试打开/关闭、invalid、expanded 等avt-keyboard-navavt的子标签标记覆盖键盘导航流程的单个测试实际用例可参考 e2e/components/Button/Button-test.avt.e2e.jstest.describe(avt Button, () { test(avt-default-state, async ({ page }) { await visitStory(page, { component: Button, id: components-button--default, globals: { theme: white }, }); await expect(page).toHaveNoACViolations(Button); }); test(avt-keyboard-nav, async ({ page }) { await visitStory(page, { component: Button, id: components-button--default, globals: { theme: white }, }); await expect(page.getByRole(button).first()).toBeVisible(); await page.keyboard.press(Tab); await expect(page.getByRole(button).first()).toBeFocused(); }); });可以看到avt置于describe标题默认状态、键盘导航分别落在独立test的标题中无障碍断言统一走toHaveNoACViolations交互断言则借助 Playwright 的 role 选择器与keyboard.press(Tab)验证焦点流转。借助--grep avt即可只跑无障碍测试子集。五、本地开发启动 Storybook 并编写组件测试文档强调在本地使用 Playwright 时必须先启动被测服务。对于 React 组件需要在仓库根目录执行cd packages/react yarn storybookStorybook 加载完成后即可用 e2e/test-utils/storybook 中的工具编写并运行测试。该工具的入口是 e2e/test-utils/storybook.js其visitStory(page, options)承担了从参数到 URL 的全部构造逻辑支持component/story/id定位 story无id时自动拼接为components-${component}--${story}支持globals如主题theme: g10与args组件参数如disabled: true分别以globals...、args...追加到 URL页面地址在 CI 下使用/iframe?id...viewModestory静态 Storybook 会去掉.html后缀本地使用/iframe.html?id...viewModestory页面加载后先断言toContainAStory再等待document.fonts.ready确保 IBM Plex 字体资源完整加载保证视觉回归VRT截图稳定。文档给出的标准测试骨架如下// e2e/components/component/component-test.e2e.js use strict; const { test } require(playwright/test); const { themes } require(../../test-utils/env); const { visitStory } require(../../test-utils/storybook); test.describe(component-name vrt, () { themes.forEach((theme) { test(theme, async ({ page }) { await visitStory(page, { component: component, story: story-name, globals: { theme }, }); }); }); });其中themes来自 e2e/test-utils/env.jsconst themes [white, g10, g90, g100];即每个视觉回归 story 会依次在 white、g10、g90、g100 四种主题下跑一遍vrt标签用于标识视觉回归用例。六、调试 Playwright 测试文档推荐两种调试方式Playwright 的 VS Code 集成可直接在编辑器中单步执行、打断点--debug标志运行yarn playwright test --debug会打开 Playwright Inspector可逐步执行测试、查看当前页面状态并快速拾取可用的选择器便于定位用什么选择器命中测试目标。调试时也可配合--projectchromium --headed以真实可见的浏览器窗口观察测试过程。七、Chromatic 视觉回归测试与 g90 按需开启7.1 默认测试模式Chromatic 被用于 Storybook stories 的视觉回归测试。默认情况下stories 会在以下三种模式下被截图g10主题g100主题breakpoint-sm视口g90主题被有意排除在全局 Chromatic 覆盖之外以降低快照体积但当个别 story 需要如修复特定主题的 bug 或视觉回归时可以按需开启。7.2 为单个 story 开启 g90从 Storybook 的 modes 配置导入allModes并在 story 的chromatic.parameters.modes中显式声明import { allModes } from ../../.storybook/modes; export const MyStory { parameters: { chromatic: { modes: { g10: allModes[g10], g90: allModes[g90], // Opt into g90 coverage g100: allModes[g100], }, }, }, };注意原文档中的相对导入路径../../.storybook/modes是相对于 story 源码文件位于packages/react/src深层目录而言的其真实定义位于 packages/react/.storybook/modes.js。该文件从carbon/themes引入主题 token注册了g10/g90/g100三种背景模式以及breakpoint-sm/breakpoint-md/breakpoint-lg/breakpoint-xlg/breakpoint-max五种视口模式即allModes的完整来源。这种全局默认 局部 opt-in的策略既保证了大多数 story 有视觉回归基线又允许在必要时针对g90定向补充快照。八、FAQ浏览器可执行文件缺失问题为什么看到browserType.launch: Executable doesnt exist at ../path这是因为 Playwright 需要在 Chromium、Firefox 等真实浏览器内核中运行测试而这些浏览器可执行文件需要单独下载安装。在仓库根目录执行yarn playwright install即可完成安装。若网络受限或需要指定浏览器版本也可查看 Playwright CLI 的install --help了解可选参数如仅安装 chromiumyarn playwright install chromium。九、把测试纳入日常开发总结 Carbon 仓库测试实践的可复用要点分层明确包导出/公共 API 的稳定性用 Jest 快照yarn test:e2e组件观感、交互与无障碍用 Playwrightyarn playwright test命名即约定*-test.avt.e2e.js无障碍、*-test.vrt.e2e.js视觉回归由 playwright.config.js 的testMatch正则统一收集标签驱动筛选avt系列标签 --grep/--grep-invert实现按需执行Storybook 即测试台通过 e2e/test-utils/storybook.js 的visitStory把 story 参数化主题、args后作为被测页面CI 与本地仅 URL 形态不同有无.html后缀无障碍内建toHaveNoACViolations自定义匹配器将accessibility-checker的 IBM 规则集接入断言配合avt-keyboard-nav覆盖键盘可达性视觉回归分层Chromatic 默认g10g100breakpoint-smg90按 story 通过chromatic.modes显式 opt-in参考 packages/react/.storybook/modes.js。如需深入阅读可继续查看测试总览 docs/testing.md、根级测试脚本 package.json、Playwright 配置 playwright.config.js、Jest E2E 配置 jest.e2e.config.js以及大量真实用例目录 e2e/components 与 e2e/test-utils。【免费下载链接】carbonA design system built by IBM项目地址: https://gitcode.com/GitHub_Trending/carbo/carbon创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考