42 lines
2.9 KiB
Markdown
42 lines
2.9 KiB
Markdown
---
|
||
name: Testing
|
||
description: Playwright test conventions, fixtures, and visual regression.
|
||
applyTo: "tests/**"
|
||
---
|
||
|
||
# Testing
|
||
|
||
- Playwright for API tests (`tests/api/`), E2E tests (`tests/e2e/`), mobile tests (`tests/e2e-mobile/`), and Visual Regression tests (`tests/e2e-visual/`). Config in `playwright.config.ts`.
|
||
- Self-test after code changes: run only affected spec files (`npx playwright test tests/e2e/filename.spec.ts` or `-g "test name"`), not a full test suite run – saves time.
|
||
- Always coordinate test adjustments with the user: do not fix broken tests to match buggy frontend or vice versa. When tests fail, first clarify whether the test or the code is wrong.
|
||
|
||
## BrowserSync Workaround
|
||
|
||
BrowserSync keeps a WebSocket open permanently, preventing `networkidle` and `load` from resolving. All fixture files override `page.goto()` and `page.reload()` to use `waitUntil: "domcontentloaded"` by default. Always use `domcontentloaded` for navigation waits.
|
||
|
||
## Fixtures & Helpers
|
||
|
||
- `tests/e2e/fixtures.ts` – Shared fixtures (`authedPage`, `testUser`) and helpers (`waitForSpaReady`, `navigateToRoute`, `clickSpaLink`).
|
||
- `tests/e2e-visual/fixtures.ts` – Visual test helpers (`waitForVisualReady`, `hideDynamicContent`, `prepareForScreenshot`, `expectScreenshot`, `getDynamicMasks`).
|
||
- `tests/e2e-mobile/fixtures.ts` – Mobile helpers (`openHamburgerMenu`, `isMobileViewport`, `isTabletViewport`, `isBelowLg`).
|
||
- `tests/api/fixtures.ts` – API fixtures (`api`, `authedApi`, `accessToken`).
|
||
- `tests/api/helpers/` – API test utilities (`test-user.ts`, `admin-api.ts`, `maildev.ts`).
|
||
- `tests/fixtures/test-constants.ts` – Central constants (`TEST_USER`, `ADMIN_TOKEN`, `API_BASE`).
|
||
|
||
## Visual Regression Tests
|
||
|
||
- Visual regression tests live in `tests/e2e-visual/` with separate Playwright projects (`visual-desktop`, `visual-iphonese`, `visual-ipad`).
|
||
- Run: `yarn test:visual`. Update baselines: `yarn test:visual:update`.
|
||
- Screenshots are stored in `tests/e2e-visual/__screenshots__/{projectName}/` and MUST be committed to the repo.
|
||
- Tolerance: `maxDiffPixelRatio: 0.02` (2%) for cross-OS/hardware rendering differences.
|
||
- Always call `prepareForScreenshot(page)` before `expectScreenshot()`.
|
||
- Use `waitForVisualReady(page)` instead of `waitForSpaReady()` – it additionally waits for skeleton loaders and CSS settling.
|
||
- Dynamic content: `hideDynamicContent(page)` disables BrowserSync overlay and animations; `getDynamicMasks(page)` returns locators for non-deterministic elements.
|
||
- For AI review of screenshots, run `./scripts/export-visual-screenshots.sh`.
|
||
|
||
## API Tests
|
||
|
||
- API tests use `tests/api/fixtures.ts` with `api` (unauthenticated) and `authedApi` (with Bearer token) fixtures.
|
||
- Helpers: `ensureTestUser()` (`tests/api/helpers/test-user.ts`), Admin API (`tests/api/helpers/admin-api.ts`), MailDev (`tests/api/helpers/maildev.ts`).
|
||
- After hook changes, run only affected API tests: `npx playwright test tests/api/filename.spec.ts`.
|