Material UI 测试体系全指南从单元测试到端到端测试的全链路工程实践【免费下载链接】material-uiMaterial UI: Comprehensive React component library that implements Googles Material Design. Free forever.项目地址: https://gitcode.com/GitHub_Trending/ma/material-ui本指南基于 Material UI 官方仓库的 test/README.md系统讲解这个大型 monorepo 项目分层的测试策略与工程化细节既有基于 Vitest 的单元/集成测试也有覆盖真实浏览器环境的 vitest browser mode、视觉回归与端到端测试以及配套的 console 断言、多 React 版本矩阵和覆盖率报告手段。读完本文你将能像 MUI 维护者一样为任何 React 组件写出高质量、可被 CI 可靠执行的测试并能看懂并复用仓库中的整套测试基础设施。为什么 MUI 需要一套“分层的”测试体系Material UI 是一个由packages/mui-material、packages/mui-system、packages/mui-lab等子包构成的大型 monorepo当前仓库包版本见 package.json。组件的可靠性与可回归性直接决定库的质量因此测试策略的核心矛盾是完整性completenessvs 速度speed越接近真实浏览器环境的测试越能暴露问题但成本也越高。于是 test/README.md 把测试划分为三个层级层级测试对象运行环境主要工具React API level组件在 React 渲染层的 API 行为单元/集成测试Vitest jsdom testing-libraryDOM API level组件在真实 DOM中的行为vitest browser mode无头 Chrome / Firefox / WebkitBrowser API level渲染引擎层面的最终表现视觉回归、端到端Vite 截图比对、Playwright对应的仓库脚本集中在根 package.json工作区级联关系如下pnpm test # 等价于 pnpm test:node只跑 node 环境的单元/集成测试 pnpm test:unit # TZUTC vitest全量单元/集成测试node browser 两类工程 pnpm test:node # TEST_SCOPEnode仅 node 环境的测试工程 pnpm test:browser # TEST_SCOPEbrowser仅浏览器环境的测试工程 pnpm test:regressions:run # 视觉回归截图 pnpm test:e2e # 端到端测试其中TEST_SCOPE环境变量由根 vitest.config.mts 消费getProjects()依据它决定工作区装载{docs,packages…}/vitest.config.{browser,mts}中的哪一类工程。这正体现了官方 README 所说的“每种测试方式都有不同取舍主要在完整性与速度之间权衡”。快速上手5 分钟写出并跑通第一个测试README 给出了面向贡献者的最小工作流在packages/*/src/TheUnitInQuestion/下新增TheUnitInQuestion.test.js单元测试或放到packages/*/test/下集成测试运行pnpm t TheUnitInQuestion启动监听模式的测试实现被测行为直到测试通过通过后提交 PR。这里的pnpm t是 pnpm 对test脚本的简写参数会沿test → test:node → test:unit的命令链透传给 Vitest 作为文件名过滤模式因此实际效果等价于“只跑名字含该组件的测试文件”非常契合 TDD 的快速反馈循环。环境前提仓库通过packageManager: pnpm11.22.0与 Node22.23.2见 package.json约束开发环境根目录执行pnpm install后即可运行上述命令。测试技术栈与职责划分README 明确列出了本仓库使用的测试工具结合根 package.json 的依赖可以清楚看到各自承担的职责Vitest^4.1.0——测试运行器负责调度、断言、mock、覆盖率与浏览器模式替代早期的 mocha/AVAJtesting-library/react——以“用户视角”渲染组件并查询 DOM强调可访问性优先的查询方式Chai chai-dom——提供 BDD 风格断言与 DOM 语义化匹配器如expect(button).to.have.class(...)Sinon——spy / stub / fake timer 等测试替身jsdom30.0.1——node 环境下模拟 DOM 的宿主Playwright1.62.1——驱动浏览器模式与端到端测试vitest-fail-on-console0.10.1——把意外 console 输出直接变成测试失败见下文 console 策略。在真实组件测试里你可以同时看到这些工具的协作例如 Dialog.test.js 用sinon的spy观测事件、用mui/internal-test-utils的act/createRenderer/fireEvent/screen驱动交互。编写测试的两个硬性规范统一走createRenderer渲染所有单元测试都应使用mui/internal-test-utils/createRenderer的返回值。它内部完成测试套件的初始化清理副作用、接入 chai 匹配器、接管 console 等并返回一个与testing-library/react的render同接口的函数因此无需额外引入renderdescribe(test suite, () { const { render } createRenderer(); test(first, () { render(input /); }); });源码实践中 createRenderer 还暴露了更多实用能力例如 Button.test.js 解构出renderToString用于 SSR 场景Dialog.test.js 传入{ clock: fake }选项以配合 Sinon 假时钟处理动画与延迟逻辑。你可以根据被测组件需要任意挑选组合。使用 BDD 风格的expect与最贴切的匹配器新测试统一使用 BDD 断言写法并优先选择语义最清晰的匹配器——这不仅让用例可读更重要的是让失败信息可读。在 chai 核心匹配器之外仓库额外引入chai-dom提供的 DOM 匹配器如to.have.class、to.have.tagName见 Button.test.jsit(should render with the root, text, and colorPrimary classes but no others, () { render(ButtonHello World/Button); const button screen.getByRole(button); expect(button).to.have.class(classes.root); expect(button).to.have.class(classes.text); expect(button).not.to.have.class(classes.outlined); });用例到底该放哪里把测试放到正确的位置与命名同样困难README 给出了可执行的分流决策拿不准时直接放进该组件的单元测试文件如packages/mui-material/src/Button/Button.test.js需要多个库组件协作Select、Menu这类复合组件时新建集成测试放入packages/*/test/不需要交互、但依赖大量data-testid或涉及较多样式断言时把组件做成 fixture 加入test/regressions/tests/例如List/ListWithSomeStyleProp让视觉回归兜底需要派发、组合大量不同 DOM 事件时优先使用端到端测试详见 test/e2e/README.md。处理console.error/console.warn的两套规范默认策略未预期的 console 调用直接失败默认情况下只要某个测试出现了未被预期的console.error或console.warn调用整个测试套件就会失败。配套基础设施有根 vitest.shared.mts 设置disableConsoleIntercept: true说明 console 拦截由测试环境自身接管而非 Vitest 默认拦截器全局 setup 文件 test/setupVitest.ts 引入mui/internal-test-utils/setupVitestemotion: true并注册beforeAll/afterAll根 devDependencies 中的vitest-fail-on-console提供“console 即失败”的兜底机制。失败消息会包含完整测试名suite test便于在海量错误刷屏时定位、被打印的消息本身以及该消息的堆栈。这在 watch 模式下尤其重要——当你不小心在组件里留下一条开发期警告时它能立刻把问题暴露在“引入它的那次改动”上。主动断言为新增警告编写toWarnDev/toErrorDev当你新增一条console.error/console.warn警告时应该同步补上“期望该消息出现”的测试。仓库提供自定义匹配器toWarnDev与toErrorDev约定如下期望消息必须是实际消息的子集大小写必须一致多条消息的顺序也必须一致。先看一个“故意触发两条警告”的测试数组语义表达“这两条都应在本次渲染中按顺序出现”function SomeComponent({ variant }) { if (process.env.NODE_ENV ! production) { if (variant unexpected) { console.error(That variant doesnt make sense.); } if (variant ! undefined) { console.error(variant is deprecated.); } } return div /; } expect(() { render(SomeComponent variantunexpected /); }).toErrorDev([That variant doesnt make sense., variant is deprecated.]);再看回归测试场景——组件在合法输入下不应产生任何警告expect(() { render(SomeComponent /); }).not.toErrorDev();把.not.toErrorDev()显式写出来有两个好处用例意图更清楚在 watch 模式下若组件意外引入 console 调用该用例会立即变红而不是等整个套件跑完才被“全局 console 拦截”炸出来。React API level单元测试与集成测试的运行细节过滤与 grep全量跑单元/集成测试pnpm test:unit缩小到特定文件只需追加文件名模式pnpm test:unit file name pattern按用例名搜索Vitest 的-t等价于 greppnpm test:unit -t STRING_TO_GREP开启 watch 模式pnpm t testFilePattern单元测试套件基于 Vitest testing-library/react的精简封装仓库中的真实示例可参考 Dialog.test.js 里对渲染、ref 类型、slot/class 覆盖的完整约定测试describeConformance。集成测试则多用于Select、Menu这类“多子组件协同”的复合组件。调试测试需要逐步调试时使用--debug标志pnpm t testFilePattern --debug随后在 Chrome 的chrome://inspect中连接调试器——注意测试不会立刻执行直到你在调试器里点击“继续/执行”后才会真正运行。如果你使用 VS Code仓库还预置了调试任务打开目标测试文件直接按F5启动 “Test Current File”即可用集成调试器运行当前文件断点体验与普通应用调试完全一致。生成 HTML 覆盖率报告pnpm test:node --coverage在浏览器/node/全量三种范围上分别生成 HTML 覆盖率# browser tests pnpm test:browser run --coverage --coverage.reporter html # node tests pnpm test:node run --coverage --coverage.reporter html # all tests pnpm test:unit run --coverage --coverage.reporter html执行后可在coverage/index.html查看完整的行/分支/函数覆盖率。README 原注提到报告由 Istanbul 的 HTML reporter 生成需要说明的是当前仓库根 vitest.config.mts 已将 coverage provider 配置为 v8vitest/coverage-v8reportsDirectory指向根目录coverageCI 下 reporter 自动切换为lcovonly本地默认text——因此这里追加--coverage.reporter html命令得到的同样是coverage/index.html这一份输出。DOM API level用真实浏览器兜住“真 DOM 行为”只在 React 层面测试远远不够——组件最终要在真实 DOM里工作focus 管理、事件冒泡、scroll、布局副作用都依赖真实环境。为此仓库启用了Vitest 的 browser modePlaywright providerpnpm test:browser关键实现见 vitest.shared.mts浏览器模式默认headless: true、视口1024x896并通过VITEST_BROWSERS环境变量决定运行在哪些浏览器实例上VITEST_BROWSERSfirefox,webkit pnpm test:browser默认值即chromium。README 说明默认覆盖三种内核无头 Chrome、无头 Firefox、Webkit。测试文件命名约定也从配置中可推断文件名含.browser.的用例会以浏览器环境运行见 vitest.shared.mts这也是跨包vitest.config.browser.mts与vitest.config.mts并存的原因。Browser API level视觉回归与端到端测试最终组件必然要交给用户的真实渲染引擎DOM 只是该环境的一个维度因此还需要覆盖渲染层级的测试。视觉回归测试视觉回归的详细说明见 test/regressions/README.md根脚本package.json提供了三件套pnpm test:regressions:dev # 后台常驻持续构建用于回归的视图Vite端口 5001 pnpm test:regressions:run # 真正执行截图比对参数与 vitest 一致 pnpm test:regressions:server # 预览已构建的回归视图端口 5001调试时的推荐做法先让pnpm test:regressions:dev在后台跑起来然后执行截图。它支持与vitest相同的过滤参数例如只对docs/src/pages/system/basic下的每个 demo 重新截图pnpm test:regressions:run -t docs-system-basic截图产物位于test/regressions/screenshots/chrome。如果想单独逐个查看某个视图可在 dev 进程运行期间访问http://localhost:5001。端到端测试端到端测试用于“派发并组合大量真实 DOM 事件”的场景专项说明见 test/e2e/README.md。仓库里另一处与此相关的是test/e2e-website/它包含多个 Playwright spec如material-docs.spec.ts、material-icons.spec.ts等通过根脚本运行pnpm test:e2e-website # 使用 test/e2e-website/playwright.config.ts pnpm test:e2e-website:dev # 附带 PLAYWRIGHT_TEST_BASE_URLhttp://localhost:3000实战提醒可访问性a11y树的包含/排除README 特别指出一个最容易踩的坑测试查询应显式记录被查询元素在 a11y 树中的成员资格。默认查询如getByRole(button, { hidden: false })在判断“a11y 树排除”时行为会不同例如hidden: false显式要求包含 a11y 树中被隐藏但仍被排除的元素。由于该检查开销较大本地默认关闭只有在 CI 环境或设置环境变量CItrue才会开启CItrue pnpm test:unit忽略这一差异是两种典型报错的最常见诱因Unable to find an accessible element with the role与Found multiple elements with the role——前者常因元素被 a11y 树排除而查不到后者常因未排除掉隐藏元素而查到多个。性能监控与多版本 React 矩阵手动触发的性能 profile仓库有一条专门的 CI 任务对核心测试套件做性能剖析profiling。由于成本高且与日常开发无关该任务默认不跑需要手动触发 pipeline在环境变量$CIRCLE_TOKEN中放入个人访问令牌用下面的请求为 PR #24289 触发名为profile的 workflowcurl --request POST \ --url https://circleci.com/api/v2/project/gh/mui/material-ui/pipeline \ --header content-type: application/json \ --header Circle-Token: $CIRCLE_TOKEN \ --data-raw {branch:pull/24289/head,parameters:{workflow:profile}}分析页面由 pipeline 里test_profilejob 的 job number 定位先从刚才 API 响应中的 pipeline id 出发在 CircleCI 界面中找到该 pipeline 下test_profilejob 的编号即 job URL 末尾的数字如jobs/211258再用:job-number打开对应的 profile 页面进行分析。在多个 React 版本下测试组件需要保证对不同 React 版本不同的 release channel甚至 React 的 PR都兼容一条命令即可切换依赖矩阵pnpm use-react-version version对应实现是 scripts/useReactVersion.mjs根 package.json 已注册该脚本。version的合法取值包括取值含义示例defaultstable即当前支持的最低 React 版本pnpm use-react-version stablenpm 上的 tag体验预发布通道next、experimental、latest具体历史版本验证旧版本兼容^17.0.0在 CI 侧任何 PR 都可在 CircleCI 界面手动追加字符串参数触发两条工作流参数类型名称值stringworkflowreact-next或react-17步骤为进入…/pipelines/github/mui/material-ui?branchpull/PR_NUMBER/head把PR_NUMBER换成你的 PR 号→ 点击Trigger Pipeline→ 展开Add parameters (optional)添加上表参数 → 再次点击触发。若走 API则是向 pipeline 接口提交react-version参数例如触发 PR #24289 在reactnext下运行默认 workflowcurl --request POST \ --url https://circleci.com/api/v2/project/gh/mui/material-ui/pipeline \ --header content-type: application/json \ --header Circle-Token: $CIRCLE_TOKEN \ --data-raw {branch:pull/24289/head,parameters:{react-version:next}}仓库配套资源速查想继续深入这套测试体系可以按下面的路径在仓库中阅读一手资料测试总览test/README.md即本文的源头文档视觉回归专项test/regressions/README.md端到端专项test/e2e/README.mdVitest 工作区/浏览器与覆盖率配置vitest.config.mts 与 vitest.shared.mts后者集中体现了 browser mode 实例、VITEST_BROWSERS、setup 文件与 node/browser 环境判定逻辑全局测试 setuptest/setupVitest.ts注册 Emotion 环境并处理 Firefox 下focus()的兼容差异测试范例单元测试 Button.test.js、Dialog.test.js其中包含createRenderer多种用法、describeConformance组件约定检查与 chai-dom 断言e2e 网站测试配置test/e2e-website/playwright.config.ts。整体而言这套体系的价值在于“每一层测试只解决它最擅长的问题”jsdom 之上的单测追求速度与精确断言真实浏览器的 DOM 测试兜住 jsdom 的偏差视觉回归与端到端测试则最终保证用户看到的渲染结果不出差错。理解并复用这些约定是向任何大型组件库贡献高质量测试的第一步。【免费下载链接】material-uiMaterial UI: Comprehensive React component library that implements Googles Material Design. Free forever.项目地址: https://gitcode.com/GitHub_Trending/ma/material-ui创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Material UI 测试体系全指南：从单元测试到端到端测试的全链路工程实践
Material UI 测试体系全指南从单元测试到端到端测试的全链路工程实践【免费下载链接】material-uiMaterial UI: Comprehensive React component library that implements Googles Material Design. Free forever.项目地址: https://gitcode.com/GitHub_Trending/ma/material-ui本指南基于 Material UI 官方仓库的 test/README.md系统讲解这个大型 monorepo 项目分层的测试策略与工程化细节既有基于 Vitest 的单元/集成测试也有覆盖真实浏览器环境的 vitest browser mode、视觉回归与端到端测试以及配套的 console 断言、多 React 版本矩阵和覆盖率报告手段。读完本文你将能像 MUI 维护者一样为任何 React 组件写出高质量、可被 CI 可靠执行的测试并能看懂并复用仓库中的整套测试基础设施。为什么 MUI 需要一套“分层的”测试体系Material UI 是一个由packages/mui-material、packages/mui-system、packages/mui-lab等子包构成的大型 monorepo当前仓库包版本见 package.json。组件的可靠性与可回归性直接决定库的质量因此测试策略的核心矛盾是完整性completenessvs 速度speed越接近真实浏览器环境的测试越能暴露问题但成本也越高。于是 test/README.md 把测试划分为三个层级层级测试对象运行环境主要工具React API level组件在 React 渲染层的 API 行为单元/集成测试Vitest jsdom testing-libraryDOM API level组件在真实 DOM中的行为vitest browser mode无头 Chrome / Firefox / WebkitBrowser API level渲染引擎层面的最终表现视觉回归、端到端Vite 截图比对、Playwright对应的仓库脚本集中在根 package.json工作区级联关系如下pnpm test # 等价于 pnpm test:node只跑 node 环境的单元/集成测试 pnpm test:unit # TZUTC vitest全量单元/集成测试node browser 两类工程 pnpm test:node # TEST_SCOPEnode仅 node 环境的测试工程 pnpm test:browser # TEST_SCOPEbrowser仅浏览器环境的测试工程 pnpm test:regressions:run # 视觉回归截图 pnpm test:e2e # 端到端测试其中TEST_SCOPE环境变量由根 vitest.config.mts 消费getProjects()依据它决定工作区装载{docs,packages…}/vitest.config.{browser,mts}中的哪一类工程。这正体现了官方 README 所说的“每种测试方式都有不同取舍主要在完整性与速度之间权衡”。快速上手5 分钟写出并跑通第一个测试README 给出了面向贡献者的最小工作流在packages/*/src/TheUnitInQuestion/下新增TheUnitInQuestion.test.js单元测试或放到packages/*/test/下集成测试运行pnpm t TheUnitInQuestion启动监听模式的测试实现被测行为直到测试通过通过后提交 PR。这里的pnpm t是 pnpm 对test脚本的简写参数会沿test → test:node → test:unit的命令链透传给 Vitest 作为文件名过滤模式因此实际效果等价于“只跑名字含该组件的测试文件”非常契合 TDD 的快速反馈循环。环境前提仓库通过packageManager: pnpm11.22.0与 Node22.23.2见 package.json约束开发环境根目录执行pnpm install后即可运行上述命令。测试技术栈与职责划分README 明确列出了本仓库使用的测试工具结合根 package.json 的依赖可以清楚看到各自承担的职责Vitest^4.1.0——测试运行器负责调度、断言、mock、覆盖率与浏览器模式替代早期的 mocha/AVAJtesting-library/react——以“用户视角”渲染组件并查询 DOM强调可访问性优先的查询方式Chai chai-dom——提供 BDD 风格断言与 DOM 语义化匹配器如expect(button).to.have.class(...)Sinon——spy / stub / fake timer 等测试替身jsdom30.0.1——node 环境下模拟 DOM 的宿主Playwright1.62.1——驱动浏览器模式与端到端测试vitest-fail-on-console0.10.1——把意外 console 输出直接变成测试失败见下文 console 策略。在真实组件测试里你可以同时看到这些工具的协作例如 Dialog.test.js 用sinon的spy观测事件、用mui/internal-test-utils的act/createRenderer/fireEvent/screen驱动交互。编写测试的两个硬性规范统一走createRenderer渲染所有单元测试都应使用mui/internal-test-utils/createRenderer的返回值。它内部完成测试套件的初始化清理副作用、接入 chai 匹配器、接管 console 等并返回一个与testing-library/react的render同接口的函数因此无需额外引入renderdescribe(test suite, () { const { render } createRenderer(); test(first, () { render(input /); }); });源码实践中 createRenderer 还暴露了更多实用能力例如 Button.test.js 解构出renderToString用于 SSR 场景Dialog.test.js 传入{ clock: fake }选项以配合 Sinon 假时钟处理动画与延迟逻辑。你可以根据被测组件需要任意挑选组合。使用 BDD 风格的expect与最贴切的匹配器新测试统一使用 BDD 断言写法并优先选择语义最清晰的匹配器——这不仅让用例可读更重要的是让失败信息可读。在 chai 核心匹配器之外仓库额外引入chai-dom提供的 DOM 匹配器如to.have.class、to.have.tagName见 Button.test.jsit(should render with the root, text, and colorPrimary classes but no others, () { render(ButtonHello World/Button); const button screen.getByRole(button); expect(button).to.have.class(classes.root); expect(button).to.have.class(classes.text); expect(button).not.to.have.class(classes.outlined); });用例到底该放哪里把测试放到正确的位置与命名同样困难README 给出了可执行的分流决策拿不准时直接放进该组件的单元测试文件如packages/mui-material/src/Button/Button.test.js需要多个库组件协作Select、Menu这类复合组件时新建集成测试放入packages/*/test/不需要交互、但依赖大量data-testid或涉及较多样式断言时把组件做成 fixture 加入test/regressions/tests/例如List/ListWithSomeStyleProp让视觉回归兜底需要派发、组合大量不同 DOM 事件时优先使用端到端测试详见 test/e2e/README.md。处理console.error/console.warn的两套规范默认策略未预期的 console 调用直接失败默认情况下只要某个测试出现了未被预期的console.error或console.warn调用整个测试套件就会失败。配套基础设施有根 vitest.shared.mts 设置disableConsoleIntercept: true说明 console 拦截由测试环境自身接管而非 Vitest 默认拦截器全局 setup 文件 test/setupVitest.ts 引入mui/internal-test-utils/setupVitestemotion: true并注册beforeAll/afterAll根 devDependencies 中的vitest-fail-on-console提供“console 即失败”的兜底机制。失败消息会包含完整测试名suite test便于在海量错误刷屏时定位、被打印的消息本身以及该消息的堆栈。这在 watch 模式下尤其重要——当你不小心在组件里留下一条开发期警告时它能立刻把问题暴露在“引入它的那次改动”上。主动断言为新增警告编写toWarnDev/toErrorDev当你新增一条console.error/console.warn警告时应该同步补上“期望该消息出现”的测试。仓库提供自定义匹配器toWarnDev与toErrorDev约定如下期望消息必须是实际消息的子集大小写必须一致多条消息的顺序也必须一致。先看一个“故意触发两条警告”的测试数组语义表达“这两条都应在本次渲染中按顺序出现”function SomeComponent({ variant }) { if (process.env.NODE_ENV ! production) { if (variant unexpected) { console.error(That variant doesnt make sense.); } if (variant ! undefined) { console.error(variant is deprecated.); } } return div /; } expect(() { render(SomeComponent variantunexpected /); }).toErrorDev([That variant doesnt make sense., variant is deprecated.]);再看回归测试场景——组件在合法输入下不应产生任何警告expect(() { render(SomeComponent /); }).not.toErrorDev();把.not.toErrorDev()显式写出来有两个好处用例意图更清楚在 watch 模式下若组件意外引入 console 调用该用例会立即变红而不是等整个套件跑完才被“全局 console 拦截”炸出来。React API level单元测试与集成测试的运行细节过滤与 grep全量跑单元/集成测试pnpm test:unit缩小到特定文件只需追加文件名模式pnpm test:unit file name pattern按用例名搜索Vitest 的-t等价于 greppnpm test:unit -t STRING_TO_GREP开启 watch 模式pnpm t testFilePattern单元测试套件基于 Vitest testing-library/react的精简封装仓库中的真实示例可参考 Dialog.test.js 里对渲染、ref 类型、slot/class 覆盖的完整约定测试describeConformance。集成测试则多用于Select、Menu这类“多子组件协同”的复合组件。调试测试需要逐步调试时使用--debug标志pnpm t testFilePattern --debug随后在 Chrome 的chrome://inspect中连接调试器——注意测试不会立刻执行直到你在调试器里点击“继续/执行”后才会真正运行。如果你使用 VS Code仓库还预置了调试任务打开目标测试文件直接按F5启动 “Test Current File”即可用集成调试器运行当前文件断点体验与普通应用调试完全一致。生成 HTML 覆盖率报告pnpm test:node --coverage在浏览器/node/全量三种范围上分别生成 HTML 覆盖率# browser tests pnpm test:browser run --coverage --coverage.reporter html # node tests pnpm test:node run --coverage --coverage.reporter html # all tests pnpm test:unit run --coverage --coverage.reporter html执行后可在coverage/index.html查看完整的行/分支/函数覆盖率。README 原注提到报告由 Istanbul 的 HTML reporter 生成需要说明的是当前仓库根 vitest.config.mts 已将 coverage provider 配置为 v8vitest/coverage-v8reportsDirectory指向根目录coverageCI 下 reporter 自动切换为lcovonly本地默认text——因此这里追加--coverage.reporter html命令得到的同样是coverage/index.html这一份输出。DOM API level用真实浏览器兜住“真 DOM 行为”只在 React 层面测试远远不够——组件最终要在真实 DOM里工作focus 管理、事件冒泡、scroll、布局副作用都依赖真实环境。为此仓库启用了Vitest 的 browser modePlaywright providerpnpm test:browser关键实现见 vitest.shared.mts浏览器模式默认headless: true、视口1024x896并通过VITEST_BROWSERS环境变量决定运行在哪些浏览器实例上VITEST_BROWSERSfirefox,webkit pnpm test:browser默认值即chromium。README 说明默认覆盖三种内核无头 Chrome、无头 Firefox、Webkit。测试文件命名约定也从配置中可推断文件名含.browser.的用例会以浏览器环境运行见 vitest.shared.mts这也是跨包vitest.config.browser.mts与vitest.config.mts并存的原因。Browser API level视觉回归与端到端测试最终组件必然要交给用户的真实渲染引擎DOM 只是该环境的一个维度因此还需要覆盖渲染层级的测试。视觉回归测试视觉回归的详细说明见 test/regressions/README.md根脚本package.json提供了三件套pnpm test:regressions:dev # 后台常驻持续构建用于回归的视图Vite端口 5001 pnpm test:regressions:run # 真正执行截图比对参数与 vitest 一致 pnpm test:regressions:server # 预览已构建的回归视图端口 5001调试时的推荐做法先让pnpm test:regressions:dev在后台跑起来然后执行截图。它支持与vitest相同的过滤参数例如只对docs/src/pages/system/basic下的每个 demo 重新截图pnpm test:regressions:run -t docs-system-basic截图产物位于test/regressions/screenshots/chrome。如果想单独逐个查看某个视图可在 dev 进程运行期间访问http://localhost:5001。端到端测试端到端测试用于“派发并组合大量真实 DOM 事件”的场景专项说明见 test/e2e/README.md。仓库里另一处与此相关的是test/e2e-website/它包含多个 Playwright spec如material-docs.spec.ts、material-icons.spec.ts等通过根脚本运行pnpm test:e2e-website # 使用 test/e2e-website/playwright.config.ts pnpm test:e2e-website:dev # 附带 PLAYWRIGHT_TEST_BASE_URLhttp://localhost:3000实战提醒可访问性a11y树的包含/排除README 特别指出一个最容易踩的坑测试查询应显式记录被查询元素在 a11y 树中的成员资格。默认查询如getByRole(button, { hidden: false })在判断“a11y 树排除”时行为会不同例如hidden: false显式要求包含 a11y 树中被隐藏但仍被排除的元素。由于该检查开销较大本地默认关闭只有在 CI 环境或设置环境变量CItrue才会开启CItrue pnpm test:unit忽略这一差异是两种典型报错的最常见诱因Unable to find an accessible element with the role与Found multiple elements with the role——前者常因元素被 a11y 树排除而查不到后者常因未排除掉隐藏元素而查到多个。性能监控与多版本 React 矩阵手动触发的性能 profile仓库有一条专门的 CI 任务对核心测试套件做性能剖析profiling。由于成本高且与日常开发无关该任务默认不跑需要手动触发 pipeline在环境变量$CIRCLE_TOKEN中放入个人访问令牌用下面的请求为 PR #24289 触发名为profile的 workflowcurl --request POST \ --url https://circleci.com/api/v2/project/gh/mui/material-ui/pipeline \ --header content-type: application/json \ --header Circle-Token: $CIRCLE_TOKEN \ --data-raw {branch:pull/24289/head,parameters:{workflow:profile}}分析页面由 pipeline 里test_profilejob 的 job number 定位先从刚才 API 响应中的 pipeline id 出发在 CircleCI 界面中找到该 pipeline 下test_profilejob 的编号即 job URL 末尾的数字如jobs/211258再用:job-number打开对应的 profile 页面进行分析。在多个 React 版本下测试组件需要保证对不同 React 版本不同的 release channel甚至 React 的 PR都兼容一条命令即可切换依赖矩阵pnpm use-react-version version对应实现是 scripts/useReactVersion.mjs根 package.json 已注册该脚本。version的合法取值包括取值含义示例defaultstable即当前支持的最低 React 版本pnpm use-react-version stablenpm 上的 tag体验预发布通道next、experimental、latest具体历史版本验证旧版本兼容^17.0.0在 CI 侧任何 PR 都可在 CircleCI 界面手动追加字符串参数触发两条工作流参数类型名称值stringworkflowreact-next或react-17步骤为进入…/pipelines/github/mui/material-ui?branchpull/PR_NUMBER/head把PR_NUMBER换成你的 PR 号→ 点击Trigger Pipeline→ 展开Add parameters (optional)添加上表参数 → 再次点击触发。若走 API则是向 pipeline 接口提交react-version参数例如触发 PR #24289 在reactnext下运行默认 workflowcurl --request POST \ --url https://circleci.com/api/v2/project/gh/mui/material-ui/pipeline \ --header content-type: application/json \ --header Circle-Token: $CIRCLE_TOKEN \ --data-raw {branch:pull/24289/head,parameters:{react-version:next}}仓库配套资源速查想继续深入这套测试体系可以按下面的路径在仓库中阅读一手资料测试总览test/README.md即本文的源头文档视觉回归专项test/regressions/README.md端到端专项test/e2e/README.mdVitest 工作区/浏览器与覆盖率配置vitest.config.mts 与 vitest.shared.mts后者集中体现了 browser mode 实例、VITEST_BROWSERS、setup 文件与 node/browser 环境判定逻辑全局测试 setuptest/setupVitest.ts注册 Emotion 环境并处理 Firefox 下focus()的兼容差异测试范例单元测试 Button.test.js、Dialog.test.js其中包含createRenderer多种用法、describeConformance组件约定检查与 chai-dom 断言e2e 网站测试配置test/e2e-website/playwright.config.ts。整体而言这套体系的价值在于“每一层测试只解决它最擅长的问题”jsdom 之上的单测追求速度与精确断言真实浏览器的 DOM 测试兜住 jsdom 的偏差视觉回归与端到端测试则最终保证用户看到的渲染结果不出差错。理解并复用这些约定是向任何大型组件库贡献高质量测试的第一步。【免费下载链接】material-uiMaterial UI: Comprehensive React component library that implements Googles Material Design. Free forever.项目地址: https://gitcode.com/GitHub_Trending/ma/material-ui创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
 的用法、配置与底层原理)
