前端CMS【免费下载链接】wp-calypsoThe JavaScript and API powered WordPress.com项目地址https://gitcode.com/gh_mirrors/wp/wp-calypso点击查看免费下载Calypsowp-calypso是 WordPress.com 的 JavaScript 前端其新一代托管 Dashboard 位于client/dashboard/。本文基于仓库内 .claude/rules/dashboard-testing.md 这份测试编写规范结合client/dashboard下 188 个.test.tsx测试文件的真实实现系统讲解该模块的测试组织方式、断言原则、Mock 边界与测试数据策略。读完本文你将掌握一套可复制的行为驱动组件测试写法能够为 Dashboard 的屏幕Screen与组件写出稳定、易读、贴近用户视角的测试。适用范围与核心原则该规范通过 frontmatter 声明了明确的适用路径--- paths: - client/dashboard/**/test/** ---即所有位于client/dashboard/下test/子目录中的测试文件都必须遵守本文规范。整个 Dashboard 模块目前已有超过 180 个测试文件如client/dashboard/sites/test/index.test.tsx、client/dashboard/domains/dns/test/index.test.tsx、client/dashboard/me/billing-history/test/dataviews.test.tsx等覆盖站点列表、域名管理、账单、订阅、A4A 代理业务等所有屏幕。规范开篇立下一条最根本的原则Tests MUST verify user-visible behavior, not implementation details. Test what a user can see or do, not how the component is built internally.测试必须验证用户可见的行为而不是实现细节要测试用户能看到什么、能做什么而不是组件内部是如何构建的。这条原则贯穿了后面所有关于断言、Mock 与测试数据的规则是整个规范的思想内核测试是与用户视角的契约而不是与代码结构的耦合。规范同时点名了三个必须优先参考的权威示例分别覆盖三类典型的测试场景参考示例覆盖场景client/dashboard/sites/test/index.test.tsxDataViews 表格断言、空状态、筛选器client/dashboard/sites/overview/test/index.test.tsx屏幕中卡片/区块的复杂断言client/dashboard/sites/settings-php/test/index.test.tsx表单提交与交互Setup测试文件如何组织规范对测试文件的摆放位置、命名与用例书写方式给出了四条硬性约定。文件位置与命名Put the test file under thetest/subdirectory, with the same name as the component file but with the.test.tsxextension.测试文件必须放在组件同级的test/子目录下文件名与组件文件同名但扩展名换成.test.tsx。例如组件client/dashboard/sites/index.tsx对应的测试就是client/dashboard/sites/test/index.test.tsx组件client/dashboard/sites/settings-php/index.tsx对应client/dashboard/sites/settings-php/test/index.test.tsx。这种就近存放的约定让测试与源码天然相邻便于维护时同步更新。另外参考示例的测试文件第一行都带有/** jest-environment jsdom */注释见 client/dashboard/sites/overview/test/index.test.tsx 第 1-3 行显式声明使用 jsdom 环境确保组件在浏览器 DOM 语义下渲染。describe 与 test 的用法Use the component name (surrounded by) as the top-leveldescribe()block.Usetest()instead ofit()for test cases.顶层describe()块直接使用组件名并保留 JSX 的尖括号写法例如三个参考文件中分别使用describe( Sites )、describe( SiteOverview )和describe( PHPVersionSettings )。测试用例统一使用test()而非it()保持全仓库书写风格一致。使用自定义 render() 包裹全部 ProviderUse the customrender()function from client/dashboard/test-utils.tsx — it wraps components with all required providers (QueryClient, Router, Auth, Analytics).测试不得自行拼装 Provider 树而是使用 client/dashboard/test-utils.tsx 导出的自定义render()。该函数将组件一次性包裹进 Dashboard 运行所需的全部 Provider。从源码看其 Provider 嵌套结构为QueryClientProvider └─ AppProvider注入 AppConfig └─ AnalyticsProvider注入 recordTracksEvent / recordPageView 的 jest.fn() └─ AuthContext.Provider注入默认测试用户 └─ RouterProvidercreateTestRouter 创建的测试路由具体实现要点client/dashboard/test-utils.tsx 第 46-83 行默认用户defaultUser是一个ID: 1, username: testuser, email: testexample.com的最小用户对象可通过render(ui, { user })覆盖QueryClient默认创建一个queries: { retry: false }的客户端避免查询失败时无限重试拖慢测试也可以通过options.queryClient传入自定义实例测试路由createTestRouter用createRootRoute包一层Suspensefallback 是一个带data-testidloading的占位节点模拟路由级 Suspense 的加载态返回值render()除返回 Testing Library 的标准结果外还额外返回router、queryClient、recordTracksEvent、recordPageView方便测试断言埋点事件或直接操控查询客户端。处理 useSuspenseQuery 的异步If the component usesuseSuspenseQuery(), wait for a stable element (e.g., heading) before asserting.当组件使用 TanStack Query 的useSuspenseQuery()时页面会先进入 Suspense 加载态因此断言前必须先等待一个稳定元素出现例如页面标题 heading。典型写法是先await screen.findByRole( heading, { name: Test Site } )再继续后续断言——这在 client/dashboard/sites/overview/test/index.test.tsx 的每个用例开头都能看到。Assertions永远站在用户视角查询只用可访问性角色查询Query by accessible role using e.g.screen.findByRole(),screen.getByRole(),screen.queryByRole(), andwithin().所有查询一律基于可访问性角色accessible role优先使用findByRole异步等待、getByRole同步获取、queryByRole断言不存在以及within()限定查询范围。这是 Testing Library 官方推荐的最贴近用户的查询方式用户是通过按钮、链接、标题、表格这些语义角色来理解界面的测试也应如此。例如 client/dashboard/sites/test/index.test.tsx 第 88 行用screen.findByRole( button, { name: Add new site } )等待添加新站点按钮出现client/dashboard/sites/settings-php/test/index.test.tsx 第 65 行用findByRole( combobox, { name: PHP version } )定位版本下拉框并用toHaveDisplayValue( 8.2 )断言其当前显示值。禁止查询实现细节Never query by test ID, CSS class, or DOM structure.规范明确禁止通过data-testid、CSS class 或 DOM 结构如嵌套层级、兄弟节点关系来查询元素。data-testid在测试路由的 Suspense fallback 中虽然被用作加载占位标记client/dashboard/test-utils.tsx 第 26 行但那是基础设施内部的兜底手段业务测试断言一律不使用它。If an element isnt reachable by role, fix the components accessibility instead.更关键的是如果某个元素无法通过角色查询到正确的做法是修复组件的可访问性而不是绕道去查 class 或结构。这把可测试性和可访问性绑定在了一起——组件对测试友好就意味着它对屏幕阅读器等辅助技术友好。断言保持简单直接Prefer simple, readable assertions over complex logic.倾向于简单、可读的断言而不是复杂的判断逻辑。例如 client/dashboard/sites/test/index.test.tsx 第 116 行用一行expect( screen.queryByText( BOUNCING_NOTICE_TITLE ) ).not.toBeInTheDocument()验证不该出现的内容不出现第 88 行用toBeVisible()验证元素可见。每个用例只聚焦一个或一组紧密相关的用户可见行为。Mocking只在网络边界拦截这是整套规范中约束最严格的部分也是与只测用户可见行为原则配套的关键设计DO NOT mock React components, hooks, or modules.DO NOT mock TanStack queries.Only mock network requests at the boundary usingnockto intercept REST API calls tohttps://public-api.wordpress.com.不 mock React 组件、hooks 或模块组件树保持真实渲染hooks 走真实逻辑不 mock TanStack Query查询客户端、useSuspenseQuery、缓存、重试策略全部真实运行正因如此test-utils 里的 QueryClient 才显式设置retry: false让失败立即暴露唯一允许的 Mock 手段是 nock在https://public-api.wordpress.com这一网络边界拦截 REST API 调用返回模拟的响应体。这种隔离在边界的策略让测试真正覆盖了从发起查询 → 经过组件渲染逻辑 → 展示用户界面的完整链路而不是把组件内部逻辑替换成桩实现。nock 的实际用法从参考文件中可以看到 nock 的多种进阶用法基础拦截client/dashboard/sites/test/index.test.tsx 第 47-52 行function mockSitesEndpoint( sites: Site[] ) { nock( https://public-api.wordpress.com ) .get( /rest/v1.3/me/sites ) .query( true ) .reply( 200, { sites, total: sites.length } ); }按查询参数分流第 59-64 行用.query( ( query ) query.site_visibility deleted )只拦截带site_visibilitydeleted的请求从而分别模拟删除站点检查与普通站点列表两个接口function mockDeletedSitesCheckEndpoint( total: number ) { return nock( https://public-api.wordpress.com ) .get( /rest/v1.3/me/sites ) .query( ( query ) query.site_visibility deleted ) .reply( 200, { sites: [], total } ); }持久化拦截第 73-77 行用户偏好接口可能被多次请求用.persist()让同一拦截器反复生效nock( https://public-api.wordpress.com ) .persist() .get( /rest/v1.1/me/preferences ) .query( true ) .reply( 200, { calypso_preferences: {} } );延迟响应模拟加载态第 261-290 行用返回 Promise 的方式手动控制响应时机验证已删除站点检查进行中不应闪现空状态这类时序问题。POST 请求断言请求体client/dashboard/sites/settings-php/test/index.test.tsx 第 42-49 行在拦截器中直接对请求体做断言并用返回的scope.isDone()验证表单确实提交了正确数据function mockPHPVersionSaved( expectedVersion: string ) { return nock( https://public-api.wordpress.com ) .post( /wpcom/v2/sites/${ site.ID }/hosting/php-version, ( body ) { expect( body ).toEqual( { version: expectedVersion } ); return true; } ) .reply( 200 ); }测试末尾用await waitFor( () expect( scope.isDone() ).toBe( true ) )确认请求已发出且请求体符合预期从而端到端验证用户选择版本 → 点击保存 → 发出正确请求的完整交互。另外client/dashboard/sites/test/index.test.tsx 第 293 行的nock.cleanAll()展示了如何在单个用例内清理既有拦截器、重新注册以模拟不同的偏好数据如用户已持久化的 DataViews 视图配置。Test data最小化测试对象Keep test objects minimal — include only properties relevant to the test.Useas Typeto cast partial objects instead of filling unused fields.测试数据只保留与当前用例相关的字段用as Site/as User之类类型断言把部分对象提升为完整类型而不是把Site的所有几十个字段都填一遍。例如 client/dashboard/sites/test/index.test.tsx 第 24-45 行的mockSites只包含ID、name、slug、URL、is_coming_soon、is_private、site_migration、plan这几个字段const mockSites [ { ID: 1, name: My First Site, slug: my-first-site.wordpress.com, URL: https://my-first-site.wordpress.com, is_coming_soon: false, is_private: false, site_migration: {}, plan: { product_slug: business-bundle, product_name_short: Business }, } as Site, // ... ];测试依赖的具体字段如plan.product_name_short用于表格中 Plan 列的展示、is_coming_soon用于 Visibility 列的 Coming soon都在测试中可见、可查证其余无关字段一律省略。当需要覆盖更特殊的场景时则基于mockSites做展开覆盖例如第 320 行{ ...mockSites[ 1 ], ID: 3, name: My Deleted Site, is_deleted: true }在最小对象之上追加is_deleted字段来构造已删除站点。三个参考示例的实战拆解场景一DataViews 表格断言sitesclient/dashboard/sites/test/index.test.tsx 演示了如何对 DataViews 表格做用户视角断言。核心技巧是先用screen.findByRole( table )定位表格再用within( table )限定范围按行、按列头、按单元格断言第 408-437 行const table await screen.findByRole( table ); await waitFor( () expect( within( table ).getAllByRole( row ) ).toHaveLength( 3 ) ); const rows within( table ).getAllByRole( row ); const header within( rows[ 0 ] ).getAllByRole( columnheader ); expect( header[ 0 ] ).toHaveTextContent( Site ); expect( header[ 1 ] ).toHaveTextContent( Visibility ); expect( header[ 2 ] ).toHaveTextContent( Plan );该文件还覆盖了大量 DataViews 相关行为空状态queryByRole( table )断言表格不出现、删除站点感知的空状态、staging 筛选器、以及通过用户偏好接口返回持久化视图配置来驱动表格布局切换。第 408 行注释// more than 12 sites to force the table layout说明测试用site_count: 13的假用户数据强制触发表格布局模拟真实用户场景。场景二屏幕内卡片/区块的复杂断言overviewclient/dashboard/sites/overview/test/index.test.tsx 面对的是比单一表格复杂得多的站点总览屏——由可见性、备份、扫描、性能、计划、最新活动、域名等多张卡片组成并且很多卡片受套餐权益门控feature gate。文件为此提炼了两个辅助函数getCard( text )第 71-83 行在getAllByRole( article )中找到文本包含指定内容的卡片找不到就主动抛错以配合waitFor的重试语义waitForFeatureGatedCards( planName )第 89-91 行先等待套餐名称文本出现让HostingFeatureGate在套餐查询 resolve 后完成重挂载避免拿到被卸载的过期节点。beforeEach中一次性注册了十余个 nock 拦截器站点信息、偏好、agency 博客、域名、活动日志、扫描、launchpad、站点画像、存储、套餐、预览链接、主机指标、flex-usage 等把总览屏依赖的整个 API 面都铺好。用例则按免费套餐 / Atomic 付费套餐 / 待激活 / 未发布 / A4A 开发站点 / Jetpack 自托管 / Flex 套餐 / 不可访问站点等维度矩阵式覆盖每个用例断言一组用户能看到的卡片及其文案。值得注意的是第 14-24 行测试通过window.localStorage.setItem直接种入 ExPlat 实验的分组数据让useExperimenthook 走正常代码路径解析出指定实验变体——这是不 mock hooks、只从真实路径驱动原则的又一体现。场景三表单提交settings-phpclient/dashboard/sites/settings-php/test/index.test.tsx 是表单交互的范本用userEvent.setup()模拟真实用户操作第 53、68-76 行const user userEvent.setup(); // ... const versionSelect await screen.findByRole( combobox, { name: PHP version } ); expect( versionSelect ).toHaveDisplayValue( 8.2 ); await user.selectOptions( versionSelect, 8.3 ); const scope mockPHPVersionSaved( 8.3 ); const saveButton screen.getByRole( button, { name: Save } ); await user.click( saveButton ); await waitFor( () { expect( scope.isDone() ).toBe( true ); } );由于该页面的路由 loader 会在渲染前 await PHP 版本查询测试先创建自己的QueryClient并调用queryClient.ensureQueryData( sitePHPVersionQuery( site.ID ) )第 59-62 行预填充查询缓存再通过render( ..., { queryClient } )传入——这是对 test-utilsRenderOptions中queryClient选项的典型应用。此外该文件还覆盖了无权限套餐显示升级引导出现Upgrade plan按钮、不出现Save按钮和有套餐但未启用 Atomic 时显示激活引导出现Activate按钮两类门控状态用queryByRole( button, { name: Save } )的否定断言验证表单在门控状态下确实不可用。总结一套可复用的测试方法论Calypso Dashboard 的测试规范本质上是一套自洽的方法论闭环组织测试文件与组件就近存放于test/子目录用组件名作为顶层 describe用例统一test()渲染统一使用 client/dashboard/test-utils.tsx 的render()由测试基础设施负责 QueryClient、Router、Auth、Analytics 等全部 Provider断言只通过可访问性角色与用户可见文案查询不碰 test ID、class 与 DOM 结构发现不可查询就反推组件可访问性问题Mock所有 mock 收敛到nock对https://public-api.wordpress.com的网络拦截组件、hooks、TanStack Query 全部真实运行数据测试对象最小化as Type断言补齐类型字段只保留用例所需。这套规范让测试成为用户行为的忠实记录也让组件实现细节的变更只要不改变用户可见行为不会轻易打碎测试。为 Dashboard 屏幕或组件新增测试时直接对照 .claude/rules/dashboard-testing.md 以及三个参考文件sites、overview、settings-php按图索骥即可写出风格一致、稳定可靠的测试。赞分享前端CMS【免费下载链接】wp-calypsoThe JavaScript and API powered WordPress.com项目地址https://gitcode.com/gh_mirrors/wp/wp-calypso点击查看免费下载相关推荐Framework7组件单元测试使用Testing Library验证行为Framework7组件单元测试使用Testing Library验证行为 你是否遇到过这样的情况辛辛苦苦开发的移动应用组件在不同设备上表现迥异按钮点击前端UI组件移动开发cann/cann-competitionsForeachExpm1算子设计ForeachExpm1 算子设计方案 一、基本信息 1.1 需求来源 ForeachExpm1 算子是 PyTorch torch._foreach_expmCANN文档高性能计算nodejs.org组件测试React Testing Library实战nodejs.org组件测试React Testing Library实战 测试体系架构概览 Node.js官网项目采用多层测试策略构建了从单元测试到端到端前端文档创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考