accelint-react-testing
Use when writing, reviewing, or refactoring React component tests with Testing Library. Load when you see render(), screen, fireEvent, userEvent, waitFor, or *.test.tsx files. Covers query priority (getByRole > getByLabelText > getByText), user-centric testing patterns, async utilities, custom renders with providers, and accessibility-first assertions. Keywords include RTL, Testing Library, screen, getByRole, findBy, queryBy, userEvent, waitFor, toBeInTheDocument, testing-library/react, testing-library/user-event, jest-dom.
- License 许可
- Apache-2.0
- 最近更新
- 2026-09-09
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- accelint-react-testing
- license
- Apache-2.0
- metadata
- { "author": "accelint", "version": "1.0.0" }
- description
- Use when writing, reviewing, or refactoring React component tests with Testing Library. Load when you see render(), screen, fireEvent, userEvent, waitFor, or *.test.tsx files. Covers query priority (getByRole > getByLabelText > getByText), user-centric testing patterns, async utilities, custom renders with providers, and accessibility-first assertions. Keywords include RTL, Testing Library, screen, getByRole, findBy, queryBy, userEvent, waitFor, toBeInTheDocument, testing-library/react, testing-library/user-event, jest-dom.
- compatibility
- Requires @testing-library/react, works with vitest or jest
02 资源文件 14
- 参考文档AGENTS.md3.2 KB
- 资产文件assets/custom-render-template.tsx4.0 KB
- 资产文件assets/output-report-template.md10.0 KB
- 参考文档README.md3.4 KB
- 参考文档references/accessibility-queries.md8.5 KB
- 参考文档references/anti-patterns.md11.8 KB
- 参考文档references/async-testing.md7.8 KB
- 参考文档references/custom-render.md9.2 KB
- 参考文档references/query-priority.md7.0 KB
- 参考文档references/query-variants.md10.2 KB
- 参考文档references/user-events.md10.2 KB
- 脚本scripts/check-query-priority.sh2.4 KB
- 脚本scripts/detect-wrapper-queries.sh2.9 KB
- 脚本scripts/find-fire-event.sh2.6 KB
03 SKILL.md 正文
React Testing Best Practices
Expert guidance for writing maintainable, user-centric React component tests with Testing Library. Focused on query selection, accessibility-first testing, and avoiding implementation details.
NEVER Do When Writing React Tests
- NEVER query by test IDs before trying accessible queries - Test IDs bypass accessibility verification: a button with
data-testid="submit"but no accessible name works in tests but fails for screen reader users. When tests pass with test IDs, you ship inaccessible UIs. Query hierarchy:getByRole>getByLabelText>getByText>getByTestId. Each step down this list means less confidence your UI is usable. - NEVER use
fireEventfor user interactions whenuserEventis available -fireEventdispatches single DOM events, missing the event sequence real users trigger:fireEvent.click()fires one click event, but real users trigger focus → mousedown → mouseup → click. Components that work with fireEvent break in production when users interact normally.userEvent.click()simulates the full interaction sequence, catching bugs fireEvent misses. - NEVER test implementation details instead of user behavior - Tests that verify "state variable X equals Y" or "function Z was called" create false failures: you refactor from useState to useReducer, all tests fail, yet the UI works identically. Testing implementation details punishes refactoring and provides zero confidence the user experience works. Test what users see and do (rendered output, interaction results), not how your component achieves it internally.
- NEVER query from
containeror use destructured queries after initial render -const { getByText } = render(<Component />)creates stale queries that miss updates: after state changes, destructured queries search the initial DOM snapshot, missing newly rendered elements. This causes "element not found" errors for elements that are actually present. Always usescreen.getByText()which automatically queries the current DOM state. Using screen consistently also makes tests more maintainable - adding a new query doesn't require updating the destructuring. - NEVER add aria-label or role attributes solely for tests - If you're adding
aria-label="submit-button"orrole="button"just so tests can find elements, you're working backwards. Tests should verify the component is already accessible, not make it accessible for tests. Adding test-only ARIA pollutes production code and masks real accessibility problems. Fix the component's semantic HTML and existing ARIA first. - NEVER snapshot entire component trees without specific assertions - Massive snapshots with 500+ lines break on any change (updated classname, new prop, reordered elements), forcing reviewers to approve diffs they can't meaningfully evaluate. When test failures require "just update the snapshot" without understanding why, the test has zero value. Snapshot specific critical structures (error messages, data tables) with targeted assertions for everything else.
- NEVER use
waitForfor actions that return promises -waitFor(() => expect(element).toBeInTheDocument())polls repeatedly until timeout when a promise-basedfindByquery solves it in one shot:await screen.findByText('loaded')waits for the element to appear without polling. Reserve waitFor for assertions that can't use findBy (checking element disappears, waiting for attribute changes). - NEVER perform side effects inside waitFor callback -
waitFor(() => { fireEvent.click(button); expect(text).toBeInTheDocument(); })runs the click multiple times as waitFor retries, causing unpredictable behavior. waitFor is for waiting on assertions, not triggering actions. Perform all actions outside waitFor, then use waitFor only for the assertion:fireEvent.click(button); await waitFor(() => expect(text).toBeInTheDocument());or better yet,await userEvent.click(button); expect(await screen.findByText(text)).toBeInTheDocument();. - NEVER create custom renders without documenting provider requirements - A custom
renderWithReduxfunction with undocumented required store shape breaks for every developer: they callrender(<Component />)instead ofrenderWithRedux(), tests fail with cryptic "Cannot read property of undefined", wasting 15 minutes debugging. Centralize provider setup in test utils with TypeScript types that enforce correct usage, or document required wrappers prominently. - NEVER mix queries from different Testing Library imports - Importing both
@testing-library/reactrender and@testing-library/domqueries creates confusion:screenfrom react package doesn't work withgetByRolefrom dom package, causing "screen.getByRole is not a function" errors. Import all queries from@testing-library/reactfor React components - it re-exports everything from dom with React-specific enhancements.
Before Writing Tests, Ask
Apply these thinking patterns before implementing React component tests:
Query Selection Strategy
- Which query matches how users find this element? Real users don't look for test IDs or CSS classes - they look for labels, buttons, headings. If you can't query by role or label, your UI lacks accessibility. Query difficulty reveals UX problems before they reach production.
- Does this element need to be found at all? Not every element needs a query assertion. Users don't verify "loading spinner exists" - they verify "data appears after loading". Test outcomes, not intermediate states.
- Should I use getBy, queryBy, or findBy? Start with getBy for immediate presence - it gives the best error messages. Use queryBy only when asserting absence (.not.toBeInTheDocument()). Use findBy for async appearance. Never use queryBy + expect(...).toBeInTheDocument() - use getBy instead for better error messages when the element is missing.
User vs Implementation Testing
- What would a user do to verify this works? Users click buttons and read text - they don't check state variables or mock function calls. If your test uses
rerender()or accesses component internals, you're testing implementation. Refactor to test through user actions. - Will this test survive a refactoring that doesn't change behavior? If renaming a function or switching from useState to useReducer breaks the test, you're testing implementation details. These tests waste time blocking safe changes while providing no confidence the UI actually works.
Async and Timing
- Is this query for something that loads asynchronously? Use
findBy*for anything loaded via useEffect, API calls, or setTimeout.getBy*throws immediately if element is missing;findBy*waits for it to appear. Using getBy for async content creates race conditions that only fail in CI. - Am I waiting for an element to appear or disappear? Appearance =
findBy*query. Disappearance =waitForElementToBeRemoved. State changes =waitForwith assertion. Each has different semantics; using the wrong one causes flaky tests or longer timeouts.
Test Isolation and Setup
- Does this component need context providers to render? Components using useContext, Redux hooks, or React Router throw without providers. Create custom render utilities that wrap components in required providers automatically. Repeating provider setup in every test file is a maintenance disaster.
- What's the minimal setup needed for this test case? Tests with excessive setup (mocking 10 functions for a button test) are fragile and slow. Mock only external dependencies (APIs, localStorage), never your own functions. If setup is complex, the component design might be the problem.
How to Use
This skill uses progressive disclosure to minimize context usage:
1. Start with the Overview (AGENTS.md)
Read AGENTS.md for a concise overview of all rules with one-line summaries.
2. Load Specific Rules as Needed
Use these explicit triggers to know when to load each reference file:
MANDATORY Loading (load entire file):
- Writing any query (getBy, findBy, queryBy*)** → query-priority.md
- Simulating user interactions (clicks, typing, etc.) → user-events.md
Load When You See These Patterns:
- Confusion about getBy vs findBy vs queryBy → query-variants.md
- waitFor, async queries, or "act" warnings → async-testing.md
- Components using Context, Redux, Router → custom-render.md
- Testing accessibility or ARIA attributes → accessibility-queries.md
- Using container, wrapper, or rerender extensively → anti-patterns.md
- Queries failing or can't find right selector → query-variants.md for screen.debug() usage
Do NOT Load Unless Specifically Needed:
- Do NOT load custom-render.md for simple components without providers
- Do NOT load async-testing.md for synchronous tests
- Do NOT load accessibility-queries.md unless testing ARIA or a11y concerns
3. Apply the Pattern
Each reference file contains:
- ❌ Incorrect examples showing the anti-pattern
- ✅ Correct examples showing the optimal implementation
- Explanations of why the pattern matters
4. Audit Existing Tests (Optional)
Use the provided scripts to audit existing test suites:
# Check query priority (testId usage, container.querySelector)
./scripts/check-query-priority.sh
# Find fireEvent that should be userEvent
./scripts/find-fire-event.sh
# Detect deprecated wrapper/container patterns
./scripts/detect-wrapper-queries.sh
5. Use the Report Template
When this skill is invoked for test code review, use the standardized report format:
Template: assets/output-report-template.md
The report format provides:
- Executive Summary with accessibility confidence and user-centric coverage assessment
- Severity levels (Critical, High, Medium, Low) for prioritization
- Impact analysis (accessibility confidence, user-centric confidence, test reliability, refactor safety)
- Categorization (Query Priority, Query Variants, User Events, Async Testing, Custom Render, Accessibility, Anti-patterns)
- Pattern references linking to detailed guidance in references/
- Summary table for tracking all issues
When to use the report template:
- Skill invoked directly via
/accelint-react-testing <path> - User asks to "review test code" or "audit tests" across file(s), invoking skill implicitly
When NOT to use the report template:
- User asks to "write a test for this function" (direct implementation)
- User asks "what's wrong with this test?" (answer the question)
- User requests specific test fixes (apply fixes directly without formal report)
What This Skill Covers
Expert guidance on React Testing Library patterns:
- Query Priority - Accessible query hierarchy from getByRole to getByTestId
- Query Variants - When to use getBy, findBy, queryBy for different scenarios
- User Events - userEvent vs fireEvent for realistic interaction testing
- Async Testing - Handling promises, waitFor, findBy queries, avoiding act warnings
- Custom Render - Setting up providers (Context, Redux, Router) for complex components
- Accessibility Queries - Testing with roles, labels, and ARIA attributes
- Anti-patterns - Avoiding implementation details, container usage, excessive snapshots
- Audit Scripts - Automated detection of suboptimal patterns in existing tests
Query Selection Decision Tree
Use this hierarchy when selecting queries - try options from top to bottom:
1. getByRole ← Preferred: Accessible, reflects how users & ATs interact
↓ Can't find role?
2. getByLabelText ← For form fields: matches how users read forms
↓ No label?
3. getByPlaceholderText ← For inputs: less accessible than labels
↓ No placeholder?
4. getByText ← For non-interactive content: headings, paragraphs
↓ Text not unique?
5. getByDisplayValue ← For form inputs: current value
↓ No display value?
6. getByAltText ← For images: alt attribute
↓ No alt text?
7. getByTitle ← For title attribute: less accessible
↓ No title?
8. getByTestId ← Last resort: no accessibility verification
Key principles:
- Higher queries = more confidence in accessibility
- If you can't query by role/label, fix the component's accessibility first
- getByTestId means "I've verified accessibility is impossible here"
Important Notes
- The
screenexport is not magic - It's justgetQueriesForElement(document.body). Usingscreen.getByRole()is identical to destructuredgetByRole()from render, but screen never goes stale after re-renders. - Testing Library encourages accessibility by making accessible elements easiest to query - If queries are hard, your UI is hard to use. Query difficulty is a UX code smell.
- Use screen.debug() or screen.logTestingPlaygroundURL() when queries fail - When getByRole fails, run
screen.debug()to see the current DOM orscreen.logTestingPlaygroundURL()to get an interactive tool showing what queries work. Don't guess at selectors - let Testing Library show you what's available. - queryBy returns null silently - use getBy for better errors - When an element should exist,
getBy*throws with helpful suggestions about similar elements and available roles.queryBy*returns null, requiring you to add your own assertion with less helpful error output. Use queryBy only when asserting absence with .not.toBeInTheDocument(). - Act warnings mean React state updates happened outside Testing Library's awareness - Usually caused by promises resolving after test completion or missing
awaiton async queries. Not caused by correct use of findBy or waitFor. - userEvent methods are async (return promises), fireEvent methods are sync - Forgetting
await userEvent.click()causes "act" warnings and flaky tests as state updates happen after assertions run.
04 同仓库更多 Skills
zustand-state-management
Production-tested setup for Zustand state management in React applications with TypeScript. This skill provides comprehensive patterns for building scalable, type-safe global state. Use when: setting up global state in React, migrating from Redux or Context API, implementing state persistence with localStorage, configuring TypeScript with Zustand, using slices pattern for modular stores, adding devtools middleware for debugging, handling Next.js SSR hydration, or encountering hydration errors, TypeScript inference issues, or persist middleware problems. Prevents 5 documented issues: Next.js hydration mismatches, TypeScript double parentheses syntax errors, persist middleware export errors, infinite render loops, and slices pattern type inference failures. Keywords: zustand, state management, React state, TypeScript state, persist middleware, devtools, slices pattern, global state, React hooks, create store, useBoundStore, StateCreator, hydration error, text content mismatch, infinite render, localStorage, sessionStorage, immer middleware, shallow equality, selector pattern, zustand v5
zetic-mlange
Help users integrate the ZETIC Melange (MLange) on-device AI SDK into Android (Kotlin/Java) and iOS (Swift) mobile apps. Use this skill whenever the user mentions Zetic, MLange, Melange, ZeticMLangeModel, ZeticMLangeLLMModel, ZeticMLangeHFModel, on-device NPU inference for mobile, or deploying ML models to Android/iOS with NPU acceleration. Also trigger when users ask about running LLMs on-device with GGUF quantization, mobile NPU model deployment, or converting PyTorch/ONNX models for mobile inference. Covers general model inference, LLM inference (streaming token generation), and HuggingFace model loading.
youtube-downloader
Download videos, audio, playlists, and channels from YouTube and 1000+ websites using yt-dlp. Supports quality selection, format conversion, subtitle download, playlist filtering, metadata extraction, thumbnail download, and batch operations. Use when downloading YouTube videos in any quality (4K, 8K, HDR), extracting audio as MP3/M4A/FLAC, downloading entire playlists/channels, getting subtitles in multiple languages, converting to specific formats, downloading live streams, archiving content, or batch processing multiple URLs. Optimized for reliability with automatic retries, rate limiting, and error handling.
wordpress-plugin-core
This skill provides comprehensive knowledge for WordPress plugin development, covering core patterns, security best practices, database interactions, hooks/filters, Settings API, custom post types, REST API, and AJAX. This skill should be used when creating WordPress plugins, troubleshooting security issues, implementing custom post types/taxonomies, building admin interfaces, or working with the WordPress database. Use when: Creating new WordPress plugins, implementing nonces/sanitization/escaping, working with $wpdb and prepared statements, building Settings API pages, registering custom post types or taxonomies, implementing REST API endpoints, handling AJAX requests, debugging plugin activation/deactivation issues, preventing SQL injection/XSS/CSRF vulnerabilities. Keywords: wordpress plugin development, wordpress security, wordpress hooks, wordpress filters, wordpress database, wpdb prepare, sanitize_text_field, esc_html, wp_nonce, custom post type, register_post_type, settings api, rest api, admin-ajax, wordpress sql injection, wordpress xss, wordpress csrf, plugin header, activation hook, deactivation hook, wordpress coding standards, wordpress plugin architecture
webapp-testing
Test local web applications with Playwright. Use when asked to verify frontend functionality, debug UI behavior, capture browser screenshots, or inspect browser logs.
web-performance-audit
Audit web performance using Chrome DevTools MCP. Use when asked to audit, profile, debug, or optimize page load performance, Lighthouse scores, or site speed.