jest-rtl-testing

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Jest + React Testing Library Best Practices

Jest + React Testing Library 最佳实践

Overview

概述

Based on Testing Library's core principles and Kent C. Dodds' best practices guidance for writing user-centric tests.

Core Principle: Tests should interact with your application the same way users do, not test implementation details.

基于Testing Library的核心原则以及Kent C. Dodds提出的以用户为中心的测试最佳实践指导。

核心原则： 测试应与用户和应用的交互方式保持一致，而非测试实现细节。

🔴 MANDATORY PRE-CHECK

🔴 强制预检查

Before writing any test, you MUST:

✅ Check if project has
```
AGENTS.md
```
and read its Testing section
✅ Follow
```
AGENTS.md
```
rules with highest priority when they exist
✅ Use this skill's principles as baseline guidance and supplementary best practices

在编写任何测试前，你必须：

✅ 检查项目是否存在
```
AGENTS.md
```
并阅读其中的测试章节
✅ 若存在
```
AGENTS.md
```
规则，需优先遵循
✅ 将本技能的原则作为基础指导和补充最佳实践

When to Use

适用场景

Use this skill when:

Writing new tests, especially React component tests
Reviewing or refactoring existing tests
Debugging test failures to determine if API is misused
Optimizing test readability and maintainability

Don't use when:

Unit testing pure functions (no DOM or React)
E2E testing (use Playwright, Cypress, etc.)
Performance testing or visual regression testing

在以下场景使用本技能：

编写新测试，尤其是React组件测试
评审或重构现有测试
调试测试失败问题，判断是否存在API误用情况
优化测试的可读性和可维护性

不适用场景：

纯函数的单元测试（无DOM或React）
端到端测试（请使用Playwright、Cypress等工具）
性能测试或视觉回归测试

Quick Reference

快速参考

Query Priority (Context-Aware)

查询优先级（上下文感知）

⚠️ Performance Warning:

getByRole

can be slow on large views (ref). For complex UIs with many elements, prefer

getByLabelText

getByText

first.

Priority Order:

🥇 getByLabelText - Form fields, best performance
🥇 getByText - Non-interactive content
🥇 getByRole - Small components only, great for a11y validation
🥉 getByPlaceholderText / getByDisplayValue
🚫 getByTestId - Last resort (document why in AGENTS.md)

Query types:

```
getBy*
```
- element must exist (throws if not found)
```
queryBy*
```
- expect absence (returns null)
```
findBy*
```
- async wait (returns Promise)

Details: references/query-cheatsheet.md

⚠️ 性能警告：

getByRole

在大型视图中可能会较慢（参考）。对于包含大量元素的复杂UI，优先使用

getByLabelText

或

getByText

。

优先级顺序：

🥇 getByLabelText - 表单字段，性能最佳
🥇 getByText - 非交互式内容
🥇 getByRole - 仅适用于小型组件，可用于无障碍（a11y）验证
🥉 getByPlaceholderText / getByDisplayValue
🚫 getByTestId - 最后选择（需在AGENTS.md中说明原因）

查询类型：

```
getBy*
```
- 元素必须存在（未找到则抛出错误）
```
queryBy*
```
- 用于断言元素不存在（返回null）
```
findBy*
```
- 异步等待（返回Promise）

详情：references/query-cheatsheet.md

Core Principles (Short)

核心原则（精简版）

Project rules first - Read
```
AGENTS.md
```
and follow testing rules with highest priority.
User-centric behavior - Assert what users see and do, not internal state.
Async aware - Use
```
findBy*
```
for appearance,
```
waitForElementToBeRemoved
```
for disappearance.
Real interactions - Prefer
```
@testing-library/user-event
```
over
```
fireEvent
```
.
MSW first for HTTP - Use MSW to mock network requests; avoid manual fetch/axios mocks.

Examples and patterns: references/common-patterns.md

项目规则优先 - 阅读
```
AGENTS.md
```
并优先遵循其中的测试规则
以用户为中心的行为 - 断言用户所见和所做的操作，而非内部状态
异步感知 - 使用
```
findBy*
```
处理元素出现，使用
```
waitForElementToBeRemoved
```
处理元素消失
真实交互 - 优先使用
```
@testing-library/user-event
```
而非
```
fireEvent
```
HTTP请求优先用MSW - 使用MSW模拟网络请求；避免手动模拟fetch/axios。

示例和模式：references/common-patterns.md

Debugging (Short)

调试（精简版）

Use
```
screen.debug()
```
to inspect the DOM.
Check query choice (
```
getBy*
```
vs
```
queryBy*
```
vs
```
findBy*
```
).
Use
```
screen.logTestingPlaygroundURL()
```
to discover better queries.

使用
```
screen.debug()
```
检查DOM。
检查查询选择（
```
getBy*
```
vs
```
queryBy*
```
vs
```
findBy*
```
）。
使用
```
screen.logTestingPlaygroundURL()
```
找到更优的查询方式。

Resources

资源

Last Updated: 2026-02-10

最后更新： 2026-02-10