React Testing

React Testing

Priority: P1 (HIGH)

Core Philosophy

• Test User Behavior, Not Implementation Mechanics: Tests should verify that the application works for end users, rather than checking how components are implemented internally.
• Resistance to Refactoring: Refactoring component internal state, props, or hooks must never break passing tests as long as the user-visible behavior remains unchanged.

Core Rule Anchors (Four Pillars Enforcement)

• [WEB-TEST-01] Tripartite Naming & AAA Cadence: Test names must follow Method_Scenario_ExpectedBehavior and adhere strictly to Arrange-Act-Assert. Example: SubmitOrder_WhenCreditLimitExceeded_DisplaysBlockedBanner.
• [WEB-TEST-02] Accessible Roles & UserEvent: Always use userEvent.setup() for user interactions (await user.click(...)) and query elements via accessible roles (getByRole, findByLabelText). Avoid fireEvent and ban arbitrary CSS / DOM hierarchy selectors.
• [WEB-TEST-03] Ban on Component State & Prop Inspection: Never inspect internal component state or props directly. Never write trivial echo assertions (expect(true).toBe(true)). Assert on visible user outcomes and DOM state changes.
• [WEB-TEST-04] Mock Service Worker (MSW) Network Mocking: Intercept network requests at the HTTP boundary via MSW rather than mocking internal Apollo Client hooks (useQuery) or Redux dispatchers. Tests must verify true end-to-end component data flow.
• [WEB-TEST-05] Bug-First Regression Lock: Every PR resolving a bug ticket or with title fix(...) must introduce a test reproducing the defect prior to the fix.

Implementation Guidelines

• Standards: Use React Testing Library (RTL) with Vitest or Jest. Follow Arrange-Act-Assert (AAA) pattern ([WEB-TEST-01]).
• User-Centric Selection: Prioritize accessible queries: getByRole, findByLabelText, getByText. Treat data-testid only as an explicit fallback for complex UI elements, and strictly ban CSS class or DOM hierarchy selectors ([WEB-TEST-02]).
• Behavioral Assertions: Test user workflows using userEvent.setup() (e.g., const user = userEvent.setup(); await user.click(...)) rather than firing raw synthetic DOM events with fireEvent ([WEB-TEST-02]).
• Network Boundary Mocking (MSW): Mock API network requests at the HTTP layer using Mock Service Worker (MSW) instead of mocking Apollo Client hooks (useQuery, useMutation) or Redux dispatchers. This validates end-to-end component data flow without leaking mock internals. Never call real APIs in unit/integration tests ([WEB-TEST-04]).
• Asynchrony: Use await screen.findBy* for elements rendered after asynchronous actions. Use waitFor(() => ...) only for complex non-element updates or assertion retries.
• Architecture: Test behavior, not implementation. Never inspect component internal state or props ([WEB-TEST-03]).
• Mocks: Mock expensive third-party libraries (e.g., framer-motion, react-router) or heavy assets at the boundary to speed up tests.
• Visuals: Use Snapshot testing sparingly for stable, small UI components. Banish large snapshot tests of dynamic pages. Manual a11y checks with jest-axe.