Testing
Use the repository's existing test runner, scripts, fixtures, and configuration. Inspect the
package or build files before choosing a test level. Do not impose a Next.js, oRPC, Supabase,
Playwright, port, or folder layout on a project that uses something else.
Stack
| Level |
Best for |
Boundary |
| Unit |
Pure logic and edge cases |
One function or module |
| Component |
Interactive UI states that do not need the whole app |
Rendered component |
| Integration/API |
Contracts among application modules, storage, or HTTP |
Real owned boundary where practical |
| Browser/E2E |
Critical user journeys and browser-visible behavior |
Running application in a real browser |
Prefer the lowest level that proves the behavior. A small unit or integration test is often
clearer and faster than reproducing every rule through a browser. Use browser tests for behavior
that depends on navigation, rendering, accessibility, browser APIs, or a full user journey.
Test Boundaries
- Exercise the application's own critical path with its real implementation and configured test
services when practical.
- A narrow fake or route interception is appropriate at an unstable, expensive, destructive, or
unavailable third-party boundary. Keep the contract shape realistic and cover the owned
integration separately when the risk warrants it.
- Do not mock the code under test, recreate production schemas in the test, or assert private
implementation details.
- Reuse existing factories and fixtures. Add the smallest deterministic fixture only when the
repository has no suitable one.
What TO Test
| Type |
Where |
What |
| Unit/component |
Project convention |
Logic branches, state transitions, accessible UI behavior |
| Integration/API |
Project convention |
Auth, validation, persistence, response and error contracts |
| Browser/E2E |
Existing Playwright location |
Critical navigation, forms, rendering, and browser behavior |
Browser Pattern
import { test, expect } from '@playwright/test';
test('submits the form', async ({ page }) => {
await page.goto('/settings');
await page.getByLabel('Display name').fill('Ada');
await page.getByRole('button', { name: 'Save' }).click();
await expect(page.getByRole('status')).toHaveText('Saved');
});
Selector Priority (E2E)
getByRole('button', { name: 'Submit' }) — prefer how users and assistive technology perceive it
getByLabel('Email') — form fields
getByText('Welcome') — visible text
getByPlaceholder('Search...') — inputs
getByTestId('x') — last resort
Prefer semantic contracts and stable test IDs. Use a CSS locator when no useful user-facing
contract exists and the selector is intentionally stable; avoid selectors coupled to styling,
DOM depth, or nth-child.
Readiness and Waiting
Playwright locators, actions, and web-first assertions already wait for actionability and expected
state. Wait for the user-visible result, URL, or specific response that proves readiness.
// WRONG
await page.waitForTimeout(3000);
// RIGHT
await expect(page.getByText('Dashboard')).toBeVisible();
await page.waitForURL('/dashboard');
Do not use fixed sleeps in committed tests. Do not use networkidle as a general readiness signal;
live connections, polling, and analytics can prevent it, while an idle network does not prove the UI
is usable.
Flaky Failures
- Read the original error and the trace from the failing environment before editing.
- Classify timing/readiness, shared state, hydration, environment drift, or resource contention.
- Fix the narrow cause. Do not lengthen a timeout until evidence shows the operation legitimately
needs a different budget.
- Re-run the focused test repeatedly and with CI-like worker settings. A retry pass is evidence of
a flake, not evidence of a fix.
npx playwright test path/to/spec --trace on --repeat-each=5
npx playwright test path/to/spec --workers=4 --repeat-each=5
Troubleshooting
| Problem |
Fix |
| Flaky timeout |
Inspect trace; wait for the observable state, not elapsed time |
| Element not found |
Check route, frame, accessible name, rendering state, and trace |
| Auth state bleeds |
Separate browser contexts per test |
| CI-only failure |
Match CI workers/env and inspect its retained trace/video |
1---2name: testing3description: >4 Choose, write, and run the smallest meaningful test for the project's actual stack,5 including unit, integration, API, component, and browser tests.6 Use for "write tests", "test this", "e2e test", "playwright", "add coverage",7 "fix flaky test", "run tests".8metadata:9 source: https://skillmd.com/skills/dabhiram13/testing10---1112# Testing1314Use the repository's existing test runner, scripts, fixtures, and configuration. Inspect the15package or build files before choosing a test level. Do not impose a Next.js, oRPC, Supabase,16Playwright, port, or folder layout on a project that uses something else.1718## Stack1920| Level | Best for | Boundary |21|-------|----------|----------|22| Unit | Pure logic and edge cases | One function or module |23| Component | Interactive UI states that do not need the whole app | Rendered component |24| Integration/API | Contracts among application modules, storage, or HTTP | Real owned boundary where practical |25| Browser/E2E | Critical user journeys and browser-visible behavior | Running application in a real browser |2627Prefer the lowest level that proves the behavior. A small unit or integration test is often28clearer and faster than reproducing every rule through a browser. Use browser tests for behavior29that depends on navigation, rendering, accessibility, browser APIs, or a full user journey.3031## Test Boundaries3233- Exercise the application's own critical path with its real implementation and configured test34 services when practical.35- A narrow fake or route interception is appropriate at an unstable, expensive, destructive, or36 unavailable third-party boundary. Keep the contract shape realistic and cover the owned37 integration separately when the risk warrants it.38- Do not mock the code under test, recreate production schemas in the test, or assert private39 implementation details.40- Reuse existing factories and fixtures. Add the smallest deterministic fixture only when the41 repository has no suitable one.4243## What TO Test4445| Type | Where | What |46|------|-------|------|47| Unit/component | Project convention | Logic branches, state transitions, accessible UI behavior |48| Integration/API | Project convention | Auth, validation, persistence, response and error contracts |49| Browser/E2E | Existing Playwright location | Critical navigation, forms, rendering, and browser behavior |5051## Browser Pattern5253```typescript54import { test, expect } from '@playwright/test';5556test('submits the form', async ({ page }) => {57 await page.goto('/settings');58 await page.getByLabel('Display name').fill('Ada');59 await page.getByRole('button', { name: 'Save' }).click();60 await expect(page.getByRole('status')).toHaveText('Saved');61});62```6364## Selector Priority (E2E)65661. `getByRole('button', { name: 'Submit' })` — prefer how users and assistive technology perceive it672. `getByLabel('Email')` — form fields683. `getByText('Welcome')` — visible text694. `getByPlaceholder('Search...')` — inputs705. `getByTestId('x')` — last resort7172Prefer semantic contracts and stable test IDs. Use a CSS locator when no useful user-facing73contract exists and the selector is intentionally stable; avoid selectors coupled to styling,74DOM depth, or `nth-child`.7576## Readiness and Waiting7778Playwright locators, actions, and web-first assertions already wait for actionability and expected79state. Wait for the user-visible result, URL, or specific response that proves readiness.8081```typescript82// WRONG83await page.waitForTimeout(3000);84// RIGHT85await expect(page.getByText('Dashboard')).toBeVisible();86await page.waitForURL('/dashboard');87```8889Do not use fixed sleeps in committed tests. Do not use `networkidle` as a general readiness signal;90live connections, polling, and analytics can prevent it, while an idle network does not prove the UI91is usable.9293## Flaky Failures94951. Read the original error and the trace from the failing environment before editing.962. Classify timing/readiness, shared state, hydration, environment drift, or resource contention.973. Fix the narrow cause. Do not lengthen a timeout until evidence shows the operation legitimately98 needs a different budget.994. Re-run the focused test repeatedly and with CI-like worker settings. A retry pass is evidence of100 a flake, not evidence of a fix.101102```bash103npx playwright test path/to/spec --trace on --repeat-each=5104npx playwright test path/to/spec --workers=4 --repeat-each=5105```106107## Troubleshooting108109| Problem | Fix |110|---------|-----|111| Flaky timeout | Inspect trace; wait for the observable state, not elapsed time |112| Element not found | Check route, frame, accessible name, rendering state, and trace |113| Auth state bleeds | Separate browser contexts per test |114| CI-only failure | Match CI workers/env and inspect its retained trace/video |