Testing

Test behavior the user cares about, through public interfaces, so tests survive refactors and fail
only when something is actually broken.

1. Which kind of test

• Unit: pure logic (parsers, calculations, validation, reducers). Fast, many.
• Integration: a route + DB, a component + its hooks, a service + real filesystem. The best value
  per test for most apps.
• E2E (Playwright): 3–10 critical user journeys (sign up, checkout, create item). Slow; keep few.
• Bug fix: first write a test that reproduces the bug and fails, then fix, then see it pass.

2. Set up the runner (use what the project already has)

• First look at package.json's "test" script (or pytest.ini / pyproject.toml): if the project already runs
  tests one way — node --test, Jest, Vitest, pytest — write the tests for that and run them with it. Don't
  install or switch to another framework unless the user asks.
• JS/TS with no test setup yet (Vite or any modern project): Vitest. npm i -D vitest, script "test": "vitest".
  Run once: npx vitest run. React components: npm i -D @testing-library/react @testing-library/jest-dom jsdom
  and test: { environment: 'jsdom' } in vite.config.ts.
• Existing Jest project: keep Jest (npx jest).
• API routes (Node): npm i -D supertest and call the app object without listening on a port.
• Python: pip install pytest (add pytest-asyncio for async, httpx for FastAPI TestClient).
  Run python -m pytest -q.
• E2E: npm init playwright@latest, then npx playwright test. Use webServer in
  playwright.config.ts to start the app automatically.

3. Write good tests

• Name says behavior and condition: returns 422 when email is missing, test_total_applies_discount_over_100.
• Arrange, act, assert, separated by blank lines; one behavior per test.
• Assert outcomes (returned value, HTTP response, DB row, visible text), not internal calls.
• Test the edges: empty, one, many, boundary values, invalid input, error from a dependency.

import { describe, it, expect } from 'vitest';
import { applyDiscount } from './pricing';
describe('applyDiscount', () => {
  it('takes 10% off orders over 100', () => {
    expect(applyDiscount(200)).toBe(180);
  });
  it('leaves orders of exactly 100 unchanged', () => {
    expect(applyDiscount(100)).toBe(100);
  });
});

def test_create_user_rejects_duplicate_email(client):
    client.post("/users", json={"email": "a@b.co"})
    res = client.post("/users", json={"email": "a@b.co"})
    assert res.status_code == 409

4. Fixtures and data

• Build test data with small factory functions (makeUser({ role: 'admin' })) with sensible defaults.
• pytest fixtures for app client, temp DB (tmp_path), and cleanup; Vitest beforeEach for resets.
• Each test sets up its own data; tests must pass in any order and in isolation.
• Use an in-memory or temp SQLite DB, or a disposable test database; never the dev or prod DB.

5. Mock only boundaries

• Mock: network calls to third-party APIs, time (vi.useFakeTimers(), freezegun), randomness, email/SMS.
• Do not mock your own modules to make tests pass; that tests the mock. Prefer real DB in integration tests.
• HTTP mocking: MSW (npm i -D msw) for JS, respx for httpx or responses for requests in Python.

6. Playwright e2e

test('user can add a todo', async ({ page }) => {
  await page.goto('/');
  await page.getByLabel('New todo').fill('Buy milk');
  await page.getByRole('button', { name: 'Add' }).click();
  await expect(page.getByRole('listitem')).toHaveText(['Buy milk']);
});

Select by role/label/text, not CSS classes. Use web-first assertions (auto-wait); never waitForTimeout.

7. Running and reading failures

1. Run the single failing test first (npx vitest run path -t "name", python -m pytest path::test_name -x).
2. Read the first failure fully: expected vs received, and the top stack frame in your code.
3. Decide whether the test or the code is wrong based on the intended behavior; never weaken an assertion
   just to get green.
4. Re-run the whole suite before finishing.

Check before you finish

1. Run the full suite and quote the summary line (e.g. Tests 24 passed).
2. Temporarily break the code under test: the new test must fail (proves it tests something).
3. No .only, skip, or commented-out tests left behind; no flaky sleeps.

Common mistakes

• Snapshot tests of large output that nobody reads.
• Testing implementation details (private functions, state shape, call counts).
• Shared mutable state between tests; reliance on test order.
• Tests that hit real external APIs or depend on the current date.