Test Conventions

Deterministic Tests

• Mock network calls, timers, and randomness — tests must not depend on external state.
• Avoid unnecessary snapshots unless the repo already relies on them.
• Test file location: *.test.*, *.spec.*, or __tests__/ directories.

Stack Detection

Identify the test stack before writing anything:

• Check package.json devDependencies for jest, vitest, @testing-library/*, detox, etc.
• Look at existing test files for import patterns and conventions already in use.
• Match the existing stack — don't introduce a new test runner or library.

Selector Best Practices

Hierarchy of preference (most to least stable):

1. testID props — always prefer these for element selection
2. Accessibility role / label — stable and meaningful
3. Semantic query (e.g., getByRole, getByLabelText)
4. Last resort: structure-based selectors

Never do:

• Query by display text or copy — breaks when copy changes
• Query by element count or string count — strings repeat across components
• Tie selectors to internal component structure, nesting depth, or class names

DRY Testing

• Extract shared setup into beforeEach or helper functions.
• Use test factories/builders for common test data instead of duplicating object literals.
• Share common assertions via custom matchers or helper functions.
• Parameterize similar tests with test.each / it.each instead of copy-pasting test cases.
• Extract common render + setup patterns into helper functions (e.g., renderWithProviders).

Coverage Gap Analysis

When asked "what needs testing?" or to find test gaps:

1. Scan for untested modules — find source files with no corresponding test file.
2. Prioritize by risk:
   • Critical user paths (auth, payments, core flows) > recently changed code > complex branching logic
3. Flag zero-coverage modules — components or utilities with no test file at all.
4. Check edge cases — look for error handling, boundary conditions, and fallback logic that existing tests skip.