Add Playwright visual regression tests at 320px, 768px, and 1440px breakpoints #124

New Issue

marcel · 2026-03-27T18:36:30+01:00

marcel commented

2026-03-27 18:36:30 +01:00

Problem

The E2E suite takes screenshots only on test failure — reactive, not proactive. There are no baseline screenshot comparisons. A layout regression at mobile (320px) or desktop (1440px) won't be caught unless it also breaks a functional assertion. Visual regressions from CSS changes are invisible to CI.

Why This Matters

Tailwind CSS 4 utility changes, component restructuring, and i18n string length differences all affect layout in ways that functional tests don't catch. A misaligned save bar on mobile, an overflowing tag list at tablet width, or a broken dark mode contrast ratio are real user-facing bugs that the current test suite would ship silently.

What Needs To Be Done

Create e2e/visual.spec.ts with snapshot tests at each breakpoint:

import { test, expect } from '@playwright/test';

const breakpoints = [
  { name: 'mobile', width: 320, height: 812 },
  { name: 'tablet', width: 768, height: 1024 },
  { name: 'desktop', width: 1440, height: 900 },
];

for (const bp of breakpoints) {
  test.describe(`${bp.name} (${bp.width}px)`, () => {
    test.use({ viewport: { width: bp.width, height: bp.height } });

    test('home page', async ({ page }) => {
      await page.goto('/');
      await expect(page).toHaveScreenshot(`home-${bp.name}.png`);
    });

    test('document detail', async ({ page }) => {
      // navigate to a seeded document
      await expect(page).toHaveScreenshot(`document-detail-${bp.name}.png`);
    });
  });
}

Run in both light mode and dark mode (Playwright's colorScheme option)
Store baseline snapshots in e2e/snapshots/ and commit them to the repo
CI uploads a diff report as an artifact when snapshots don't match
Diffs are reviewed and approved before merge (not auto-approved)

Priority pages for visual regression

Home / document search
Document detail
Document edit form
Persons list

Acceptance Criteria

Visual snapshot tests exist for 4 pages × 3 breakpoints × 2 color schemes = 24 snapshots
Baseline snapshots committed to repo
CI fails on unreviewed snapshot diff
Diff artifacts uploaded on mismatch

## Problem The E2E suite takes screenshots only on test failure — reactive, not proactive. There are no baseline screenshot comparisons. A layout regression at mobile (320px) or desktop (1440px) won't be caught unless it also breaks a functional assertion. Visual regressions from CSS changes are invisible to CI. ## Why This Matters Tailwind CSS 4 utility changes, component restructuring, and i18n string length differences all affect layout in ways that functional tests don't catch. A misaligned save bar on mobile, an overflowing tag list at tablet width, or a broken dark mode contrast ratio are real user-facing bugs that the current test suite would ship silently. ## What Needs To Be Done 1. Create `e2e/visual.spec.ts` with snapshot tests at each breakpoint: ```typescript import { test, expect } from '@playwright/test'; const breakpoints = [ { name: 'mobile', width: 320, height: 812 }, { name: 'tablet', width: 768, height: 1024 }, { name: 'desktop', width: 1440, height: 900 }, ]; for (const bp of breakpoints) { test.describe(`${bp.name} (${bp.width}px)`, () => { test.use({ viewport: { width: bp.width, height: bp.height } }); test('home page', async ({ page }) => { await page.goto('/'); await expect(page).toHaveScreenshot(`home-${bp.name}.png`); }); test('document detail', async ({ page }) => { // navigate to a seeded document await expect(page).toHaveScreenshot(`document-detail-${bp.name}.png`); }); }); } ``` 2. Run in both **light mode** and **dark mode** (Playwright's `colorScheme` option) 3. Store baseline snapshots in `e2e/snapshots/` and commit them to the repo 4. CI uploads a diff report as an artifact when snapshots don't match 5. Diffs are reviewed and approved before merge (not auto-approved) ## Priority pages for visual regression - Home / document search - Document detail - Document edit form - Persons list ## Acceptance Criteria - [ ] Visual snapshot tests exist for 4 pages × 3 breakpoints × 2 color schemes = 24 snapshots - [ ] Baseline snapshots committed to repo - [ ] CI fails on unreviewed snapshot diff - [ ] Diff artifacts uploaded on mismatch

marcel added the test label 2026-03-27 18:45:11 +01:00

marcel commented

2026-03-27 18:54:29 +01:00

Architect review (@mkeller): Descoping for now.

24 committed baseline screenshots (4 pages × 3 breakpoints × 2 color schemes) create significant friction during active UI development. Every intentional CSS change — Tailwind utility tweak, component restructure, i18n string length difference — invalidates baselines and triggers a snapshot update cycle. During active development that cost is too high relative to the value.

Visual regression testing is the right tool for a UI in maintenance mode where stability is the primary concern. Come back to this ticket once the UI has settled and layout regressions are the main risk. The functional E2E tests and accessibility checks from #118 cover the meaningful regression surface for now.

**Architect review (@mkeller):** Descoping for now. 24 committed baseline screenshots (4 pages × 3 breakpoints × 2 color schemes) create significant friction during active UI development. Every intentional CSS change — Tailwind utility tweak, component restructure, i18n string length difference — invalidates baselines and triggers a snapshot update cycle. During active development that cost is too high relative to the value. Visual regression testing is the right tool for a UI in maintenance mode where stability is the primary concern. Come back to this ticket once the UI has settled and layout regressions are the main risk. The functional E2E tests and accessibility checks from #118 cover the meaningful regression surface for now.

marcel added the descoped label 2026-03-27 18:54:45 +01:00

marcel referenced this issue

2026-03-29 14:13:22 +02:00

feat(#153): notification history page (/notifications) #155

marcel referenced this issue

2026-04-24 13:22:03 +02:00

feat(mobile): reader surfaces (Home · /documents · /briefwechsel · /persons) pass mobile-first bar at 375 px #318

marcel referenced this issue

2026-05-07 17:37:16 +02:00

feat(mobile): reader surfaces (Home · /documents · /briefwechsel · /persons) pass mobile-first bar at 375 px #318

marcel referenced this issue

2026-05-07 17:38:04 +02:00