Calypso Dashboard 组件测试实战指南：以用户可见行为为中心的 Testing Library 规范-平芜编程栈

前端
CMS

【免费下载链接】wp-calypso

The JavaScript and API powered WordPress.com

项目地址：https://gitcode.com/gh_mirrors/wp/wp-calypso

Calypso（wp-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.tsx	DataViews 表格断言、空状态、筛选器
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() 包裹全部 Provider

Use 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（注入默认测试用户） └─ RouterProvider（createTestRouter 创建的测试路由）

具体实现要点（client/dashboard/test-utils.tsx 第 46-83 行）：

默认用户：defaultUser是一个ID: 1, username: 'testuser', email: 'test@example.com'的最小用户对象，可通过render(ui, { user })覆盖；
QueryClient：默认创建一个queries: { retry: false }的客户端，避免查询失败时无限重试拖慢测试；也可以通过options.queryClient传入自定义实例；
测试路由：createTestRouter用createRootRoute包一层Suspense，fallback 是一个带data-testid="loading"的占位节点，模拟路由级 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 isn't reachable by role, fix the component's 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_visibility=deleted的请求，从而分别模拟"删除站点检查"与"普通站点列表"两个接口：

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 表格断言（sites）

client/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的假用户数据强制触发表格布局，模拟真实用户场景。

场景二：屏幕内卡片/区块的复杂断言（overview）

client/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-php）

client/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）按图索骥即可写出风格一致、稳定可靠的测试。