Jest + React Testing Library Best Practices

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.

🔴 MANDATORY PRE-CHECK

Before writing any test, you MUST:

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

---

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

---

Quick Reference

Query Priority (Context-Aware)

⚠️ Performance Warning: getByRole can be slow on large views (ref). For complex UIs with many elements, prefer getByLabelText or getByText first.

Priority Order:

1. 🥇 getByLabelText - Form fields, best performance
2. 🥇 getByText - Non-interactive content
3. 🥇 getByRole - Small components only, great for a11y validation
4. 🥉 getByPlaceholderText / getByDisplayValue
5. 🚫 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

---

Core Principles (Short)

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

Examples and patterns: 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.

---

Resources

• Testing Library - Guiding Principles
• Testing Library - Queries
• Testing Library - Async
• MSW Documentation
• Common mistakes with React Testing Library (Kent C. Dodds)
• getByRole Performance Issue

---

Last Updated: 2026-02-10