Agent-Skills.md

Agent Skills: Jest + React Testing Library Best Practices

Use when writing, reviewing, or debugging Jest + React Testing Library tests, before writing test code or when tests fail

UncategorizedID: lanamaysu/agent-skills/jest-rtl-testing

Repository

lanamaysu/agent-skills
lanamaysuLicense: MIT
1

Install this agent skill to your local

pnpm dlx add-skill https://github.com/lanamaysu/agent-skills/tree/HEAD/skills/jest-rtl-testing

Skill Files

Browse the full folder contents for jest-rtl-testing.

Download Skill

Loading file tree…

skills/jest-rtl-testing/SKILL.md

Skill Metadata

Name
jest-rtl-testing
Description
Use when writing, reviewing, or debugging Jest + React Testing Library tests, before writing test code or when tests fail

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

Last Updated: 2026-02-10