| name | testing-standards |
| description | This skill enforces robust, scalable testing methodologies for both the frontend and backend. Use it when writing unit or integration tests, setting up testing frameworks like Vitest, or verifying that features conform to the "Gold Standard". |
Testing Standards Skill
๐ฏ Purpose
This skill ensures that code is verified through rigorous, maintainable tests. It enforces the use of modern testing
tools and methodologies to prevent regressions and validate behavior without writing fragile, implementation-coupled
tests.
๐๏ธ Core Responsibilities
- Frontend Testing: Focus on user interactions and accessibility roles, not implementation details or fragile HTML
selectors.
- Backend Testing: Focus on API contracts, middleware validation, and database abstraction.
- Dual Coverage Mandate: Every feature MUST have at least one Unit Test (mocked) and one Integration Test (real database).
- Test Isolation: Ensure tests run independently and reliably without side-effects or database pollution.
๐ Key References
๐ ๏ธ Testing Rules
Frontend Testing (React / Vite)
- Frameworks: ALWAYS use Vitest for the test runner and React Testing Library (
@testing-library/react) for
component testing.
- Location: Store all tests in
client/tests/[feature]/[unit|integration] (outside src/).
- Organization: ALWAYS group tests by feature. Within the feature folder, separate
unit tests (individual
components/logic) from integration tests (complex interactions).
- Configuration: Use vitest.config.ts and setup.ts.
- Queries: ALWAYS prioritize Accessibility Queries (
getByRole, getByLabelText). Do NOT use fragile selectors
like querySelector('.my-class') or getByTestId unless absolutely necessary as a last resort.
- User Events: Synthesize interactions using
@testing-library/user-event rather than fireEvent to accurately
simulate real user behavior.
- Mocks: When testing components, properly mock external dependencies like
TanStack Router (navigation) or
TanStack Query (data fetching wrappers) so tests remain fast and isolated.
Backend Testing (Node / Express)
- Frameworks: Use Vitest alongside Supertest to execute HTTP requests against the Express app without
starting the actual server.
- Location: Store all tests in
server/tests/[feature]/[unit|integration] (outside src/).
- Configuration: Use vitest.config.ts.
- Controller/Route Testing: Validate that the REST API responds with the correct HTTP status codes and the strict
ApiResponse JSON structure. Check that Zod validation middleware intercepts bad requests (400 Bad Request).
- Database (Prisma) Strategy: Never hit a production or shared development database.
- Option A (Preferred for Unit Tests): Mock Prisma using
vitest-mock-extended to test Service logic without IO.
- Option B (Preferred for Integration/API Tests): Use an isolated test database (e.g., via Docker) and ensure each
test is wrapped in a transaction or cleaned up after.
End-to-End Testing (Playwright)
- Framework: Use Playwright for full application flows.
- Location: Store E2E tests in
e2e/tests/ at the root.
- Execution: Run via
npm run test:e2e from the root.
General Philosophy
- Explicit Imports: ALWAYS explicitly import
describe, it, expect, beforeEach, afterEach, and other
testing functions from vitest. Global variables are DISABLED to ensure better IDE support and avoid naming
collisions.
- Test-Driven Design (TDD): Write tests for edge cases and core logic paths (e.g., authentication, role-based access
control, billing) before finalizing the implementation.
- AAA Pattern: Structure every test clearly using Arrange (setup), Act (execution), and Assert
(verification).