tibi-svelte-starter/.github/instructions/testing.instructions.md

name, description, applyTo

name	description	applyTo
Testing	Playwright test conventions, fixtures, and visual regression.	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.