studio-testing

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Studio Testing Strategy

Studio 测试策略

How to write and structure tests for

apps/studio/

. The core principle: push logic out of React components into pure utility functions, then test those functions exhaustively. Only use component tests for complex UI interactions. Use E2E tests for features shared between self-hosted and platform.

如何为

apps/studio/

编写和组织测试。核心原则：将逻辑从React组件中剥离到纯工具函数中，然后对这些函数进行全面测试。仅针对复杂UI交互使用组件测试。针对自托管版与平台版共用的功能使用E2E测试。

When to Apply

适用场景

Reference these guidelines when:

Writing new tests for Studio code
Deciding which type of test to write (unit, component, E2E)
Extracting logic from a component to make it testable
Reviewing whether test coverage is sufficient
Adding a new feature that needs tests

在以下场景中参考这些指南：

为Studio代码编写新测试时
决定编写哪种类型的测试（单元测试、组件测试、E2E测试）时
从组件中提取逻辑以使其可测试时
审查测试覆盖率是否足够时
添加需要测试的新功能时

Rule Categories by Priority

按优先级划分的规则类别

Priority	Category	Impact	Prefix
1	Logic Extraction	CRITICAL	`testing-`
2	Test Coverage	CRITICAL	`testing-`
3	Component Tests	HIGH	`testing-`
4	E2E Tests	HIGH	`testing-`

优先级	类别	影响程度	前缀
1	逻辑提取	关键	`testing-`
2	测试覆盖率	关键	`testing-`
3	组件测试	高	`testing-`
4	E2E测试	高	`testing-`

Quick Reference

快速参考

1. Logic Extraction (CRITICAL)

1. 逻辑提取（关键）

```
testing-extract-logic
```
- Remove logic from components into
```
.utils.ts
```
files as pure functions: args in, return out

```
testing-extract-logic
```
- 将组件中的逻辑移至
```
.utils.ts
```
文件，作为纯函数：传入参数，返回结果

2. Test Coverage (CRITICAL)

2. 测试覆盖率（关键）

```
testing-exhaustive-permutations
```
- Test every permutation of utility functions: happy path, malformed input, empty values, edge cases

```
testing-exhaustive-permutations
```
- 测试工具函数的所有排列组合：正常路径、格式错误的输入、空值、边缘情况

3. Component Tests (HIGH)

3. 组件测试（高）

```
testing-component-tests-ui-only
```
- Only write component tests for complex UI interaction logic, not business logic

```
testing-component-tests-ui-only
```
- 仅针对复杂UI交互逻辑编写组件测试，而非业务逻辑

4. E2E Tests (HIGH)

4. E2E测试（高）

```
testing-e2e-shared-features
```
- Write E2E tests for features used in both self-hosted and platform; cover clicks AND keyboard shortcuts

```
testing-e2e-shared-features
```
- 为自托管版与平台版共用的功能编写E2E测试；覆盖点击操作和键盘快捷键

Decision Tree: Which Test Type?

决策树：选择哪种测试类型？

Is the logic a pure transformation (parse, format, validate, compute)?
  YES -> Extract to .utils.ts, write unit test with vitest
  NO  -> Does the feature involve complex UI interactions?
           YES -> Is it used in both self-hosted and platform?
                    YES -> Write E2E test in e2e/studio/features/
                    NO  -> Write component test with customRender
           NO  -> Can you extract the logic to make it pure?
                    YES -> Do that, then unit test it
                    NO  -> Write a component test

该逻辑是否为纯转换逻辑（解析、格式化、验证、计算）？
  是 -> 提取至.utils.ts文件，使用vitest编写单元测试
  否 -> 该功能是否涉及复杂UI交互？
           是 -> 是否同时用于自托管版和平台版？
                    是 -> 在e2e/studio/features/中编写E2E测试
                    否 -> 使用customRender编写组件测试
           否 -> 是否可以提取逻辑使其成为纯函数？
                    是 -> 执行提取，然后编写单元测试
                    否 -> 编写组件测试

How to Use

使用方法

Read individual rule files for detailed explanations and code examples:

rules/testing-extract-logic.md
rules/testing-exhaustive-permutations.md

Each rule file contains:

Brief explanation of why it matters
Incorrect code example with explanation
Correct code example with explanation
Real codebase references

阅读单个规则文件以获取详细说明和代码示例：

rules/testing-extract-logic.md
rules/testing-exhaustive-permutations.md

每个规则文件包含：

简要说明其重要性
错误代码示例及解释
正确代码示例及解释
代码库中的实际参考

Full Compiled Document

完整编译文档

For the complete guide with all rules expanded:

AGENTS.md

如需包含所有扩展规则的完整指南，请查看

AGENTS.md

Codebase References

代码库参考

What	Where
Util test examples	`tests/components/Grid/Grid.utils.test.ts` , `tests/components/Billing/TaxID.utils.test.ts` , `tests/components/Editor/SpreadsheetImport.utils.test.ts`
Component test examples	`tests/features/logs/LogsFilterPopover.test.tsx` , `tests/components/CopyButton.test.tsx`
E2E test example	`e2e/studio/features/filter-bar.spec.ts`
E2E helpers pattern	`e2e/studio/utils/filter-bar-helpers.ts`
Custom render	`tests/lib/custom-render.tsx`
MSW mock setup	`tests/lib/msw.ts` ( `addAPIMock` )
Test README	`tests/README.md`
Vitest config	`vitest.config.ts`
Related skills	`e2e-studio-tests` (running E2E), `vitest` (API reference), `vercel-composition-patterns` (component architecture)

内容	位置
工具函数测试示例	`tests/components/Grid/Grid.utils.test.ts` , `tests/components/Billing/TaxID.utils.test.ts` , `tests/components/Editor/SpreadsheetImport.utils.test.ts`
组件测试示例	`tests/features/logs/LogsFilterPopover.test.tsx` , `tests/components/CopyButton.test.tsx`
E2E测试示例	`e2e/studio/features/filter-bar.spec.ts`
E2E助手模式	`e2e/studio/utils/filter-bar-helpers.ts`
自定义渲染	`tests/lib/custom-render.tsx`
MSW 模拟设置	`tests/lib/msw.ts` ( `addAPIMock` )
测试说明文档	`tests/README.md`
Vitest 配置	`vitest.config.ts`
相关技能	`e2e-studio-tests` （运行E2E测试）, `vitest` （API参考）, `vercel-composition-patterns` （组件架构）