Cherry Studio 前端测试规范渲染进程、packages/ui 与 E2E 的层级选择、Mock 边界与评审门禁【免费下载链接】cherry-studio Cherry Studio 是一款支持多个 LLM 提供商的桌面客户端项目地址: https://gitcode.com/CherryHQ/cherry-studio本文是 Cherry Studio 开源仓库中针对src/renderer/、packages/ui/与tests/e2e/的规范性测试指南原文见 docs/references/testing/frontend-testing.md。它面向人类开发者与 AI Agent 两类编写者回答三个核心问题一个测试什么时候值得写、应该写在哪个层级、断言什么内容。读完本文你将掌握 Cherry Studio 的测试价值门槛、最低充分层级选择、行为化断言原则、查询与 Mock 边界规则、评审拒绝清单以及一套可直接执行的 AI-Agent 测试工作流。0. 指南的定位与权威性本指南的目标不是最大化测试数量或覆盖率而是维护一组最小规模的测试集合使其能对用户可见行为与稳定的公共契约提供强信心。核心判断标准始终是保护用户可见行为、已文档化的公共契约或此前观察到的回归生产代码一旦出现真实回归测试必须失败同一行为没有在更合适的层级被重复保护测试能够在保持行为不变的前提下经受住内部重构。该文档是 Cherry Studio 前端测试质量与评审决策的唯一事实来源single source of truth。仓库入口文档应链接到它而不是复制其规则更具体的文档可以描述命令、fixture 或基础设施但不得重新定义测试何时有价值、应断言什么、如何评审。当旧示例与本指南冲突时以本指南为准——现有测试只代表当前实现历史不代表被自动认可的范式。1. 价值门槛The Value Gate写测试之前先说出回归在写任何测试之前先明确它要捕获的回归。一个测试只有在同时满足全部四个条件时才值得添加它保护用户可见行为、已文档化的公共契约或此前观察到的回归真实的生产代码回归会让它失败同样的行为尚未在更合适的层级被保护它能在一个保持行为不变的内部重构中存活。如果无法具体陈述回归就不要添加该测试。1.1 通常需要测试的变更新增或修改的业务规则、状态转换、校验与对账reconciliation逻辑触发持久化、IPC、导航、剪贴板访问或其他副作用side effect的用户交互对用户有实质影响的加载、空、错误、权限与恢复状态可访问性契约名称name、角色role、禁用状态、焦点移动与键盘行为跨进程、缓存、序列化、懒加载或 mock 对齐mock-parity边界Bug 修复添加在修复前必然失败的最小回归用例。1.2 通常不需要新测试的变更纯视觉重排无文档化的布局或可访问性契约无自身行为的透传包装pass-through wrapper或 re-export纯类型变更TypeScript 已强制除非类型契约本身就是产品 API已被生成器或契约检查覆盖的生成输出执行同一生产分支的 prop 排列组合针对不可能或不支持输入的防御性 不抛错does not throw用例。当不加测试的决策不明显时应在 PR 中解释原因而不是添加一个象征性token测试。2. 选择最低充分层级Choose the Lowest Sufficient Layer不同行为对应不同的首选测试层级Cherry Studio 的规范映射如下行为首选测试层级断言内容纯转换、解析器、reducer 或状态机单元测试输入、输出、转换与有意义的边界带状态或外部效果的 HookHook 测试或小型 harness 测试返回契约与外部可观察效果渲染进程组件行为组件测试用户能发现、操作与观察的内容通用cherrystudio/ui原语/复合组件packages/ui测试使用真实组件可访问性、交互与文档化视觉契约关键跨窗口或跨进程工作流E2E 测试完整的用户结果编译期公共类型契约类型测试被接受与被拒绝的用法无需重复运行时测试不要在每个层级重复同一行为组件测试不应重新测试已被测试的纯 helper 的每个分支E2E 测试不应枚举每个组件 prop。仓库在 vitest.config.ts 中以 Vitest projects 形式落地了这一分层rendererproject 使用jsdom环境并加载tests/renderer.setup.tsuiproject 把cherrystudio/ui别名指向packages/ui/src直接测试真实组件main/shared/preload/aiCore/provider-registry/scripts则分别对应主进程、共享层等其他边界。运行时可使用 package.json 中的命令pnpm test:renderer、pnpm test:pkg:ui、pnpm test:main、pnpm test:e2e等。2.1 测试时间确定性vitest.config.ts 在配置加载阶段强制process.env.TZ UTC并将监听器上限提高到 64。注释明确说明CI 运行器默认 UTC若不固定时区按本地日分桶 UTC 时间戳的测试例如话题列表的 Today/Yesterday会在 CI 通过、在非 UTC 时区的开发机失败。这一细节提醒我们层级选择之外测试环境的确定性同样是规范的一部分。3. 测试行为而非实现Test Behavior, Not Implementation优先断言文本、可访问名称、角色、焦点与禁用状态用户操作后的可见状态转换返回值与稳定的公共数据形状外部效果IPC 请求、导航、持久化、剪贴板写入清理cleanup——仅当不清理会造成可观察泄漏或重复效果时。避免断言内部 Hook 调用次数或注册顺序私有子组件的 props偶然的 DOM 嵌套结构非文档化契约的 CSS 类或内联样式被 mock 占位符的出现实现相关的重渲染次数。Mock 调用断言仅在 mock 本身就代表外部效果时合适例如剪贴板写入当被 mock 的函数是内部协作者时它不能替代可观察结果。CSS/class 断言只有在 class 本身即契约时才允许例如 Electron 拖拽区域标记drag-region marker、受维护的 UI 语义 token、或涉及布局机制的回归——此时应添加一行注释说明该契约。这正是 Cherry Studio 的data-ui语义契约存在的原因之一见第 4 节与 docs/references/components/ui-semantic-contract.md。4. 查询与交互优先级Query and Interaction Priority使用用户或辅助技术所用的同一表面来查询。4.1 Testing Library 查询优先级getByRole/findByRole 可访问名称accessible namegetByLabelText用户可见文本或其他语义查询文档化的受维护选择器maintained selectorgetByTestId——仅在不存在有意义的语义选择器时使用。使用queryBy*做不存在性检查findBy*等待异步出现。当存在语义查询时不要使用document.querySelector、DOM 父节点遍历或 CSS 类。交互方面常规用户输入点击、键入、Tab、选择使用userEvent.setup()fireEvent仅用于userEvent无法充分建模的底层浏览器事件如定向滚动、resize、拖拽或自定义事件。4.2 Playwright 定位器与>it(copies the message and announces success, async () { const user userEvent.setup() render(CopyButton textToCopyhello /) await user.click(screen.getByRole(button, { name: Copy })) expect(navigator.clipboard.writeText).toHaveBeenCalledWith(hello) expect(toast.success).toHaveBeenCalled() })剪贴板与 toast 是外部效果它们的调用即可观察契约。坏的示例实现与透传it(renders the icon and wrapper, () { const { container } render(CopyButton textToCopyhello /) expect(container.querySelector(div)).toBeInTheDocument() expect(container.querySelector(.copy-icon)).toBeInTheDocument() })该测试依赖偶然的 DOM 结构且不保护复制行为本身。仓库中的正面实践可对照 useCopyTool.test.tsx它断言工具列表暴露的copy动作在点击后调用了外部效果onCopySource被调用一次以及源复制失败时不显示成功反馈——关注用户可观察结果而非内部实现细节。负面实践如对container.querySelector的断言在本规范第 3、6 节中已被明确禁止。13. 相关文档Test Mocks测试 Mock 总览E2E Testing GuideElectron E2E 基础设施UI Semantic Contractdata-ui 语义契约Vitest 配置分层 projects 与确定性环境Playwright 配置E2E 运行参数前端测试脚本命令package.json【免费下载链接】cherry-studio Cherry Studio 是一款支持多个 LLM 提供商的桌面客户端项目地址: https://gitcode.com/CherryHQ/cherry-studio创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Cherry Studio 前端测试规范渲染进程、packages/ui 与 E2E 的层级选择、Mock 边界与评审门禁【免费下载链接】cherry-studio Cherry Studio 是一款支持多个 LLM 提供商的桌面客户端项目地址: https://gitcode.com/CherryHQ/cherry-studio本文是 Cherry Studio 开源仓库中针对src/renderer/、packages/ui/与tests/e2e/的规范性测试指南原文见 docs/references/testing/frontend-testing.md。它面向人类开发者与 AI Agent 两类编写者回答三个核心问题一个测试什么时候值得写、应该写在哪个层级、断言什么内容。读完本文你将掌握 Cherry Studio 的测试价值门槛、最低充分层级选择、行为化断言原则、查询与 Mock 边界规则、评审拒绝清单以及一套可直接执行的 AI-Agent 测试工作流。0. 指南的定位与权威性本指南的目标不是最大化测试数量或覆盖率而是维护一组最小规模的测试集合使其能对用户可见行为与稳定的公共契约提供强信心。核心判断标准始终是保护用户可见行为、已文档化的公共契约或此前观察到的回归生产代码一旦出现真实回归测试必须失败同一行为没有在更合适的层级被重复保护测试能够在保持行为不变的前提下经受住内部重构。该文档是 Cherry Studio 前端测试质量与评审决策的唯一事实来源single source of truth。仓库入口文档应链接到它而不是复制其规则更具体的文档可以描述命令、fixture 或基础设施但不得重新定义测试何时有价值、应断言什么、如何评审。当旧示例与本指南冲突时以本指南为准——现有测试只代表当前实现历史不代表被自动认可的范式。1. 价值门槛The Value Gate写测试之前先说出回归在写任何测试之前先明确它要捕获的回归。一个测试只有在同时满足全部四个条件时才值得添加它保护用户可见行为、已文档化的公共契约或此前观察到的回归真实的生产代码回归会让它失败同样的行为尚未在更合适的层级被保护它能在一个保持行为不变的内部重构中存活。如果无法具体陈述回归就不要添加该测试。1.1 通常需要测试的变更新增或修改的业务规则、状态转换、校验与对账reconciliation逻辑触发持久化、IPC、导航、剪贴板访问或其他副作用side effect的用户交互对用户有实质影响的加载、空、错误、权限与恢复状态可访问性契约名称name、角色role、禁用状态、焦点移动与键盘行为跨进程、缓存、序列化、懒加载或 mock 对齐mock-parity边界Bug 修复添加在修复前必然失败的最小回归用例。1.2 通常不需要新测试的变更纯视觉重排无文档化的布局或可访问性契约无自身行为的透传包装pass-through wrapper或 re-export纯类型变更TypeScript 已强制除非类型契约本身就是产品 API已被生成器或契约检查覆盖的生成输出执行同一生产分支的 prop 排列组合针对不可能或不支持输入的防御性 不抛错does not throw用例。当不加测试的决策不明显时应在 PR 中解释原因而不是添加一个象征性token测试。2. 选择最低充分层级Choose the Lowest Sufficient Layer不同行为对应不同的首选测试层级Cherry Studio 的规范映射如下行为首选测试层级断言内容纯转换、解析器、reducer 或状态机单元测试输入、输出、转换与有意义的边界带状态或外部效果的 HookHook 测试或小型 harness 测试返回契约与外部可观察效果渲染进程组件行为组件测试用户能发现、操作与观察的内容通用cherrystudio/ui原语/复合组件packages/ui测试使用真实组件可访问性、交互与文档化视觉契约关键跨窗口或跨进程工作流E2E 测试完整的用户结果编译期公共类型契约类型测试被接受与被拒绝的用法无需重复运行时测试不要在每个层级重复同一行为组件测试不应重新测试已被测试的纯 helper 的每个分支E2E 测试不应枚举每个组件 prop。仓库在 vitest.config.ts 中以 Vitest projects 形式落地了这一分层rendererproject 使用jsdom环境并加载tests/renderer.setup.tsuiproject 把cherrystudio/ui别名指向packages/ui/src直接测试真实组件main/shared/preload/aiCore/provider-registry/scripts则分别对应主进程、共享层等其他边界。运行时可使用 package.json 中的命令pnpm test:renderer、pnpm test:pkg:ui、pnpm test:main、pnpm test:e2e等。2.1 测试时间确定性vitest.config.ts 在配置加载阶段强制process.env.TZ UTC并将监听器上限提高到 64。注释明确说明CI 运行器默认 UTC若不固定时区按本地日分桶 UTC 时间戳的测试例如话题列表的 Today/Yesterday会在 CI 通过、在非 UTC 时区的开发机失败。这一细节提醒我们层级选择之外测试环境的确定性同样是规范的一部分。3. 测试行为而非实现Test Behavior, Not Implementation优先断言文本、可访问名称、角色、焦点与禁用状态用户操作后的可见状态转换返回值与稳定的公共数据形状外部效果IPC 请求、导航、持久化、剪贴板写入清理cleanup——仅当不清理会造成可观察泄漏或重复效果时。避免断言内部 Hook 调用次数或注册顺序私有子组件的 props偶然的 DOM 嵌套结构非文档化契约的 CSS 类或内联样式被 mock 占位符的出现实现相关的重渲染次数。Mock 调用断言仅在 mock 本身就代表外部效果时合适例如剪贴板写入当被 mock 的函数是内部协作者时它不能替代可观察结果。CSS/class 断言只有在 class 本身即契约时才允许例如 Electron 拖拽区域标记drag-region marker、受维护的 UI 语义 token、或涉及布局机制的回归——此时应添加一行注释说明该契约。这正是 Cherry Studio 的data-ui语义契约存在的原因之一见第 4 节与 docs/references/components/ui-semantic-contract.md。4. 查询与交互优先级Query and Interaction Priority使用用户或辅助技术所用的同一表面来查询。4.1 Testing Library 查询优先级getByRole/findByRole 可访问名称accessible namegetByLabelText用户可见文本或其他语义查询文档化的受维护选择器maintained selectorgetByTestId——仅在不存在有意义的语义选择器时使用。使用queryBy*做不存在性检查findBy*等待异步出现。当存在语义查询时不要使用document.querySelector、DOM 父节点遍历或 CSS 类。交互方面常规用户输入点击、键入、Tab、选择使用userEvent.setup()fireEvent仅用于userEvent无法充分建模的底层浏览器事件如定向滚动、resize、拖拽或自定义事件。4.2 Playwright 定位器与>it(copies the message and announces success, async () { const user userEvent.setup() render(CopyButton textToCopyhello /) await user.click(screen.getByRole(button, { name: Copy })) expect(navigator.clipboard.writeText).toHaveBeenCalledWith(hello) expect(toast.success).toHaveBeenCalled() })剪贴板与 toast 是外部效果它们的调用即可观察契约。坏的示例实现与透传it(renders the icon and wrapper, () { const { container } render(CopyButton textToCopyhello /) expect(container.querySelector(div)).toBeInTheDocument() expect(container.querySelector(.copy-icon)).toBeInTheDocument() })该测试依赖偶然的 DOM 结构且不保护复制行为本身。仓库中的正面实践可对照 useCopyTool.test.tsx它断言工具列表暴露的copy动作在点击后调用了外部效果onCopySource被调用一次以及源复制失败时不显示成功反馈——关注用户可观察结果而非内部实现细节。负面实践如对container.querySelector的断言在本规范第 3、6 节中已被明确禁止。13. 相关文档Test Mocks测试 Mock 总览E2E Testing GuideElectron E2E 基础设施UI Semantic Contractdata-ui 语义契约Vitest 配置分层 projects 与确定性环境Playwright 配置E2E 运行参数前端测试脚本命令package.json【免费下载链接】cherry-studio Cherry Studio 是一款支持多个 LLM 提供商的桌面客户端项目地址: https://gitcode.com/CherryHQ/cherry-studio创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
