.cursorrules (deprecated)

1# Testing & TDD — Cursor Rules
2# Comprehensive rules for test-driven development across languages and frameworks
3 
4## Project Context
5You are working on a project that prioritizes test-driven development (TDD). Tests are
6written before implementation, code is designed for testability, and the test suite serves
7as living documentation. The goal is high confidence in code correctness through
8well-structured, maintainable tests.
9 
10## Tech Stack (Multi-Framework)
11- JavaScript/TypeScript: Jest, Vitest, React Testing Library, Playwright
12- Python: pytest, unittest, pytest-cov, factory_boy
13- General: MSW (Mock Service Worker), Faker for test data
14- CI integration for automated test runs
15 
16## TDD Workflow
17 
18### The Red-Green-Refactor Cycle
191. **Red**: Write a failing test that describes the desired behavior
202. **Green**: Write the minimum code to make the test pass
213. **Refactor**: Clean up the code while keeping tests green
224. Repeat
23 
24### Rules
25- Never write production code without a failing test first
26- Each test should test ONE behavior or requirement
27- Run the full test suite before committing
28- Treat test code with the same quality standards as production code
29- Tests should be fast — mock expensive I/O operations
30 
31## Naming Conventions
32 
33### Test Files
34- JavaScript: `*.test.ts`, `*.spec.ts` (co-located with source)
35- Python: `test_*.py` or `*_test.py` in `tests/` directory
36- Test fixtures/factories: `factories.ts`, `conftest.py`
37 
38### Test Names — Describe Behavior, Not Implementation
39```ts
40// GOOD — describes what should happen
41it('returns 404 when the user does not exist')
42it('sends a confirmation email after successful registration')
43it('prevents duplicate orders within 5 minutes')
44it('shows an error message when the form submission fails')
45 
46// BAD — describes implementation details
47it('calls findById with correct id')
48it('sets isLoading to true')
49it('dispatches SET_USER action')
50```
51 
52### Test Structure — AAA Pattern
53```ts
54it('calculates the total with tax for items in the cart', () => {
55  // Arrange — set up test data and dependencies
56  const cart = new Cart();
57  cart.addItem({ name: 'Widget', price: 10.00, quantity: 2 });
58  cart.addItem({ name: 'Gadget', price: 25.00, quantity: 1 });
59 
60  // Act — perform the action being tested
61  const total = cart.calculateTotal({ taxRate: 0.08 });
62 
63  // Assert — verify the expected outcome
64  expect(total).toBe(48.60);
65});
66```
67 
68## Test Categories
69 
70### Unit Tests
71- Test individual functions, classes, or modules in isolation
72- Mock all external dependencies (database, APIs, file system)
73- Should run in milliseconds
74- Aim for high coverage of business logic and utility functions
75 
76### Integration Tests
77- Test how modules work together
78- May use a real database (test instance) or API
79- Test the full request/response cycle for API endpoints
80- Slower than unit tests but provide higher confidence
81 
82### End-to-End (E2E) Tests
83- Test complete user workflows through the UI
84- Use Playwright or Cypress
85- Test critical paths: sign up, purchase flow, key features
86- Keep the E2E suite small — focus on high-value user journeys
87 
88### The Testing Pyramid
89```
90    /  E2E  \        Few — slow, expensive, high confidence
91   / Integr. \      Some — medium speed, good confidence
92  /   Unit    \     Many — fast, cheap, focused
93```
94 
95## Mocking Strategy
96 
97### What to Mock
98- External APIs and services
99- Database calls (in unit tests)
100- File system operations
101- Time/dates (use fake timers)
102- Random number generation
103- Email/notification services
104 
105### What NOT to Mock
106- The code under test itself
107- Simple utility functions
108- Data structures and models
109- Things that are fast and deterministic
110 
111### Mock Patterns
112```ts
113// Prefer dependency injection over module mocking
114class OrderService {
115  constructor(
116    private db: Database,        // Inject — easy to mock
117    private emailService: EmailService,
118  ) {}
119}
120 
121// In tests:
122const mockDb = { findById: vi.fn(), save: vi.fn() };
123const mockEmail = { send: vi.fn() };
124const service = new OrderService(mockDb, mockEmail);
125```
126 
127```ts
128// MSW for API mocking (intercepts at the network level)
129import { http, HttpResponse } from 'msw';
130import { setupServer } from 'msw/node';
131 
132const server = setupServer(
133  http.get('/api/users/:id', ({ params }) => {
134    return HttpResponse.json({ id: params.id, name: 'Alice' });
135  }),
136);
137 
138beforeAll(() => server.listen());
139afterEach(() => server.resetHandlers());
140afterAll(() => server.close());
141```
142 
143## React/UI Testing
144 
145### Testing Library Philosophy
146- Test what the user sees and does, not component internals
147- Query by role, label, text — not by CSS class or test ID
148- Prefer `userEvent` over `fireEvent` for realistic interactions
149 
150```tsx
151import { render, screen } from '@testing-library/react';
152import userEvent from '@testing-library/user-event';
153 
154it('shows validation error when submitting empty form', async () => {
155  const user = userEvent.setup();
156  render(<LoginForm onSubmit={vi.fn()} />);
157 
158  await user.click(screen.getByRole('button', { name: /sign in/i }));
159 
160  expect(screen.getByText(/email is required/i)).toBeInTheDocument();
161});
162 
163it('calls onSubmit with form data when valid', async () => {
164  const user = userEvent.setup();
165  const handleSubmit = vi.fn();
166  render(<LoginForm onSubmit={handleSubmit} />);
167 
168  await user.type(screen.getByLabelText(/email/i), 'test@example.com');
169  await user.type(screen.getByLabelText(/password/i), 'secure123');
170  await user.click(screen.getByRole('button', { name: /sign in/i }));
171 
172  expect(handleSubmit).toHaveBeenCalledWith({
173    email: 'test@example.com',
174    password: 'secure123',
175  });
176});
177```
178 
179## Test Data Management
180- Use factories for test data generation (factory_boy, fishery)
181- Use Faker for realistic random data
182- Create minimal test data — only the fields relevant to the test
183- Use builder patterns for complex object creation
184- Reset database state between tests (transactions or truncation)
185 
186```ts
187// factories.ts
188import { faker } from '@faker-js/faker';
189 
190export function buildUser(overrides: Partial<User> = {}): User {
191  return {
192    id: faker.string.uuid(),
193    email: faker.internet.email(),
194    name: faker.person.fullName(),
195    createdAt: faker.date.past(),
196    ...overrides,
197  };
198}
199```
200 
201## Error and Edge Case Testing
202- Test error paths, not just happy paths
203- Test boundary conditions (empty arrays, zero values, max lengths)
204- Test concurrent operations when relevant
205- Test authorization: users accessing resources they don't own
206- Test invalid input: wrong types, missing fields, malformed data
207 
208## Performance
209- Tests should run in seconds, not minutes
210- Parallelize test execution where possible
211- Mock slow I/O in unit tests
212- Use `beforeAll` for expensive setup shared across tests
213- Profile slow tests with `--verbose` or timing reporters
214 
215## Common Pitfalls
216- Testing implementation details instead of behavior (brittle tests)
217- Shared mutable state between tests (flaky tests)
218- Not resetting mocks between tests (`vi.restoreAllMocks()`)
219- Over-mocking — testing that mocks return what you told them to return
220- Snapshot testing for dynamic content (snapshots break constantly)
221- Ignoring test failures — fix or delete, never skip permanently
222- Not testing async error paths (unhandled rejections in tests)
223- Writing tests after code is done (loses TDD benefits)
224