test(web): playwright e2e for key flows + axe a11y smoke (#95)

.github/workflows/ci.yml

@@ -160,3 +160,30 @@ jobs:
               -F body=@coverage-summary.md > /dev/null
             echo "created comment"
           fi
+
+  # E2E + accessibility smoke (#95). Runs the Worker locally (react-router dev → miniflare) against a
+  # freshly migrated + seeded local D1, then drives the key user flows and axe-scans the key pages.
+  # Kept in a separate job because it installs a browser and is heavier than the unit lane.
+  e2e:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - uses: pnpm/action-setup@0977fd99725f1db4007ccb2928dbb4e90d06cc86 # v6.0.10
+      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
+        with:
+          node-version: 22
+          cache: pnpm
+      - run: pnpm install --frozen-lockfile
+      - name: Install Playwright browser
+        run: pnpm --filter @sigma/web exec playwright install --with-deps chromium
+      # test:e2e is self-contained: `node e2e/seed.mjs` migrates + seeds a hermetic D1, then Playwright
+      # starts the dev server itself.
+      - name: E2E (Playwright + axe)
+        run: pnpm --filter @sigma/web test:e2e
+      - name: Upload Playwright report
+        if: ${{ !cancelled() }}
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: playwright-report
+          path: apps/web/playwright-report/
+          retention-days: 7

.gitignore

@@ -14,6 +14,11 @@ coverage/
 # rendered by scripts/check-coverage.mjs for the CI artifact/PR comment
 /coverage-summary.md
 
+# Playwright E2E (#95)
+playwright-report/
+test-results/
+/apps/web/playwright/.cache/
+
 # Cloudflare / wrangler
 .wrangler/
 .dev.vars

apps/web/e2e/a11y.spec.ts

@@ -0,0 +1,58 @@
+import { test, expect } from '@playwright/test';
+import AxeBuilder from '@axe-core/playwright';
+
+// Accessibility smoke over the key pages. For a government site a11y is mandatory; this is the
+// regression net (concrete fixes live in #71/#73). The gate fails only on serious/critical
+// violations to stay actionable — minor/moderate issues are surfaced but not blocking initially.
+const WCAG_TAGS = ['wcag2a', 'wcag2aa', 'wcag21a', 'wcag21aa'];
+
+// Known pre-existing serious violations, owned by the a11y-fix issues #71/#73: `definition-list` on
+// the home page and `nested-interactive` on the list pages. Baselined so this net blocks NEW
+// serious/critical regressions without failing on debt this PR is not scoped to fix. Remove ids here
+// as #71/#73 land.
+const BASELINE_RULES = new Set(['definition-list', 'nested-interactive']);
+
+async function scanBlocking(page: import('@playwright/test').Page) {
+  const results = await new AxeBuilder({ page }).withTags(WCAG_TAGS).analyze();
+  return results.violations.filter(
+    (v) => (v.impact === 'serious' || v.impact === 'critical') && !BASELINE_RULES.has(v.id),
+  );
+}
+
+function describeViolations(violations: Awaited<ReturnType<typeof scanBlocking>>) {
+  return violations.map((v) => `${v.id} (${v.impact}): ${v.help}`).join('\n');
+}
+
+const STATIC_PAGES = [
+  { name: 'home', path: '/' },
+  { name: 'contracts list', path: '/contracts' },
+  { name: 'methodology', path: '/methodology' },
+];
+
+for (const { name, path } of STATIC_PAGES) {
+  test(`a11y smoke: ${name}`, async ({ page }) => {
+    await page.goto(path);
+    const blocking = await scanBlocking(page);
+    expect(
+      blocking,
+      `axe found blocking violations on ${name}:\n${describeViolations(blocking)}`,
+    ).toEqual([]);
+  });
+}
+
+test('a11y smoke: contract detail', async ({ page }) => {
+  await page.goto('/contracts');
+  // The seed always carries contracts, so assert the row is there — skipping here would hide a broken
+  // row selector behind a green run instead of failing on it.
+  const firstTitle = page.locator('.contract-row .title').first();
+  await expect(firstTitle).toBeVisible();
+
+  await firstTitle.click();
+  await expect(page.getByRole('heading', { level: 1 })).toBeVisible();
+
+  const blocking = await scanBlocking(page);
+  expect(
+    blocking,
+    `axe found blocking violations on contract detail:\n${describeViolations(blocking)}`,
+  ).toEqual([]);
+});

apps/web/e2e/contract-detail.spec.ts

@@ -0,0 +1,19 @@
+import { test, expect } from '@playwright/test';
+
+// Critical flow: list → contract detail. Navigates from the first list row and confirms the detail
+// page renders its subject as the <h1>.
+test.describe('contract detail', () => {
+  test('navigating from the list opens a contract page', async ({ page }) => {
+    await page.goto('/contracts');
+
+    const firstTitle = page.locator('.contract-row .title').first();
+    await expect(firstTitle).toBeVisible();
+
+    await firstTitle.click();
+    await expect(page).toHaveURL(/\/contracts\/.+/);
+
+    const heading = page.getByRole('heading', { level: 1 });
+    await expect(heading).toBeVisible();
+    await expect(heading).not.toHaveText('');
+  });
+});

apps/web/e2e/csv-export.spec.ts

@@ -0,0 +1,26 @@
+import { test, expect } from '@playwright/test';
+
+// Critical flow: CSV export. We fetch the export URL directly instead of driving a browser download
+// — the CSV route streams from R2 behind a rate limiter, which makes the download event flaky. A
+// single request stays well under the limiter budget and still exercises the streamed response.
+test.describe('CSV export', () => {
+  test('contracts CSV link resolves to a streamed CSV', async ({ page, request }) => {
+    await page.goto('/contracts');
+
+    const link = page.getByRole('link', { name: 'Изтегли CSV' });
+    await expect(link).toBeVisible();
+
+    const href = await link.getAttribute('href');
+    expect(href).toContain('/contracts.csv');
+
+    const res = await request.get(href!);
+    // The CSV is streamed, so the response is 206 Partial Content (or 200 for a small body).
+    expect([200, 206]).toContain(res.status());
+    expect(res.headers()['content-type']).toContain('csv');
+
+    const body = await res.text();
+    expect(body.length).toBeGreaterThan(0);
+    // First line is a header row with delimited columns.
+    expect(body.split('\n')[0]).toContain(',');
+  });
+});

apps/web/e2e/list-filters.spec.ts

@@ -0,0 +1,34 @@
+import { test, expect } from '@playwright/test';
+
+// Critical flow: filtering a list. Filters live in the URL (shareable), and the FilterRail form
+// auto-submits on change. We assert the selected facet lands in the URL and survives a reload —
+// the URL is the single source of truth, which stands in for the (not-yet-built) save-filter idea.
+test.describe('list filters', () => {
+  test('applying a filter updates the URL and persists on reload', async ({ page }) => {
+    await page.goto('/contracts');
+
+    const rail = page.getByRole('complementary', { name: 'Филтри' });
+    // Pick the first VISIBLE facet checkbox with a name — options inside a collapsed category
+    // subgroup are hidden; the top-level facets (year / procedure) render their options directly.
+    const facet = rail
+      .locator('form label.check:visible')
+      .filter({ has: page.locator('input[type="checkbox"][name]') })
+      .first();
+    await expect(facet).toBeVisible();
+
+    const input = facet.locator('input[type="checkbox"][name]');
+    const name = await input.getAttribute('name');
+    const value = await input.getAttribute('value');
+    expect(name).toBeTruthy();
+
+    // Clicking the label fires the FilterRail form's change handler, which auto-submits the facet
+    // into the query string (shareable state).
+    await facet.click();
+    await expect(page).toHaveURL(new RegExp(`[?&]${name}=`));
+
+    const filteredUrl = page.url();
+    await page.goto(filteredUrl);
+    // Shareable: reloading the filtered URL keeps the exact facet checked (URL is the source of truth).
+    await expect(rail.locator(`form input[name="${name}"][value="${value}"]`)).toBeChecked();
+  });
+});

apps/web/e2e/mobile-nav.spec.ts

@@ -0,0 +1,23 @@
+import { test, expect } from '@playwright/test';
+
+// Critical flow: mobile navigation. Runs under the `mobile-chrome` project (Pixel 5 viewport),
+// where the primary nav is collapsed behind the "Меню" toggle.
+test.describe('mobile navigation', () => {
+  test('menu opens and routes to a section', async ({ page }) => {
+    await page.goto('/');
+
+    const nav = page.locator('.site-nav');
+    const toggle = page.getByRole('button', { name: 'Меню' });
+    await expect(toggle).toBeVisible();
+
+    await toggle.click();
+    await expect(nav).toHaveClass(/is-open/);
+
+    const link = nav.getByRole('link').first();
+    const href = await link.getAttribute('href');
+    expect(href).toBeTruthy();
+
+    await link.click();
+    await expect(page).toHaveURL(new RegExp(`${href}$`));
+  });
+});

apps/web/e2e/pagination.spec.ts

@@ -0,0 +1,21 @@
+import { test, expect } from '@playwright/test';
+
+// Critical flow: pagination. The E2E seed carries 20 contracts against PAGE_SIZE.contracts = 15, so a
+// next page always exists — assert the pager rather than skip on it, or a broken pager selector would
+// turn a real regression into a silent green skip.
+test.describe('pagination', () => {
+  test('advances to the next page when one exists', async ({ page }) => {
+    await page.goto('/contracts');
+
+    const pager = page.getByRole('navigation', { name: 'Навигация по страници' });
+    const next = pager.getByRole('link', { name: /Следваща/ });
+
+    await expect(next).toBeVisible();
+
+    const before = page.url();
+    await next.click();
+
+    await expect(page).not.toHaveURL(before);
+    await expect(page.locator('.contract-row').first()).toBeVisible();
+  });
+});

apps/web/e2e/search.spec.ts

@@ -0,0 +1,22 @@
+import { test, expect } from '@playwright/test';
+
+// Critical flow: hero search → results. Asserts the round-trip through the /search loader (which
+// queries D1) without depending on specific sample rows — the page either lists results or shows a
+// graceful empty state, both of which prove the pipeline ran end-to-end.
+test.describe('search', () => {
+  test('hero search submits and renders the search page', async ({ page }) => {
+    await page.goto('/');
+
+    const hero = page.locator('.smart-search--hero');
+    await expect(hero).toBeVisible();
+
+    // The hero field carries role="combobox" (it offers autocomplete suggestions), so target it by
+    // its form field name rather than the searchbox role.
+    await hero.locator('input[name="q"]').fill('договор');
+    await hero.getByRole('button', { name: 'Намери' }).click();
+
+    await expect(page).toHaveURL(/\/search\?q=/);
+    // PageHeader renders the echoed query as the <h1> on the results page.
+    await expect(page.getByRole('heading', { level: 1 })).toContainText('договор');
+  });
+});

apps/web/e2e/seed-e2e.sql

@@ -0,0 +1,65 @@
+-- Deterministic domain fixture for the Playwright E2E lane (#95).
+--
+-- The dev/CI smoke seed (scripts/seed.sql) only fills the RAW ingest tables and deliberately does not
+-- feed the ETL, so the explorer's domain `contracts` table stays empty and every list/detail/search
+-- page renders nothing. Rather than run the full EOP import (needs the downloaded feed), this fixture
+-- inserts a small set of raw entities + domain `contracts` directly, then scripts/precompute.sql
+-- derives every rollup and the FTS search index from them — the same read model production serves.
+--
+-- Synthetic values only: amounts, dates and CPV codes are illustrative and NOT production-shaped.
+-- 20 contracts (> PAGE_SIZE.contracts = 15) so the list paginates.
+
+-- Authorities (domain ids follow the 'auth:' || ЕИК convention).
+INSERT OR IGNORE INTO authorities (id, name, bulstat, region, type_group, settlement) VALUES
+  ('auth:000696327', 'Община София', '000696327', 'BG411', 'община', 'София'),
+  ('auth:831661388', 'Министерство на регионалното развитие', '831661388', 'BG411', 'министерство', 'София');
+
+-- Winning bidders (valid 9-digit ЕИК so eik_valid = 1).
+INSERT OR IGNORE INTO bidders (id, name, bulstat, eik_normalized, eik_valid, kind) VALUES
+  ('eik:111111111', 'Алфа ЕООД', '111111111', '111111111', 1, 'company'),
+  ('eik:222222222', 'Бета АД', '222222222', '222222222', 1, 'company'),
+  ('eik:333333333', 'Гама ООД', '333333333', '333333333', 1, 'company');
+
+-- 20 awarded tenders, cycling authority / CPV division / procedure_type so the year/procedure/EU
+-- facets and the sector rollup all get non-trivial buckets.
+WITH RECURSIVE seq(n) AS (SELECT 1 UNION ALL SELECT n + 1 FROM seq WHERE n < 20)
+INSERT OR IGNORE INTO tenders
+  (id, source_id, title, authority_id, cpv_code, procedure_type, status, published_at)
+SELECT
+  't:E2E-' || printf('%04d', n),
+  'AOP-E2E-' || printf('%04d', n),
+  'Договор за '
+    || CASE n % 4
+         WHEN 0 THEN 'доставка на оборудване'
+         WHEN 1 THEN 'строителни дейности'
+         WHEN 2 THEN 'консултантски услуги'
+         ELSE 'софтуерна поддръжка'
+       END
+    || ' №' || n,
+  CASE n % 2 WHEN 0 THEN 'auth:000696327' ELSE 'auth:831661388' END,
+  CASE n % 4 WHEN 0 THEN '30000000' WHEN 1 THEN '45000000' WHEN 2 THEN '79000000' ELSE '72000000' END,
+  CASE n % 3 WHEN 0 THEN 'открита процедура' WHEN 1 THEN 'публично състезание' ELSE 'директно възлагане' END,
+  'awarded',
+  date('2024-01-01', '+' || (n * 7) || ' days')
+FROM seq;
+
+-- One clean, summable contract per tender.
+WITH RECURSIVE seq(n) AS (SELECT 1 UNION ALL SELECT n + 1 FROM seq WHERE n < 20)
+INSERT OR IGNORE INTO contracts
+  (id, tender_id, bidder_id, amount, currency, signed_at, amount_eur, value_flag, eu_funded)
+SELECT
+  'c:E2E-' || printf('%04d', n),
+  't:E2E-' || printf('%04d', n),
+  CASE n % 3 WHEN 0 THEN 'eik:111111111' WHEN 1 THEN 'eik:222222222' ELSE 'eik:333333333' END,
+  (100000 + n * 50000) * 1.0,
+  'BGN',
+  date('2024-01-05', '+' || (n * 7) || ' days'),
+  ROUND((100000 + n * 50000) / 1.95583, 2), -- BGN→EUR at the fixed peg
+  'ok',
+  CASE n % 2 WHEN 0 THEN 1 ELSE 0 END
+FROM seq;
+
+-- Freshness row the UI reads for its "данни към" line (precompute sets home_totals.as_of, but the
+-- per-feed freshness table is normally filled by normalize-raw, which we skip here).
+INSERT OR REPLACE INTO data_freshness (source, as_of, rows, refreshed_at)
+VALUES ('admin', date('now'), 20, datetime('now'));

apps/web/e2e/seed.mjs

@@ -0,0 +1,33 @@
+#!/usr/bin/env node
+// Seeds the hermetic E2E database, run as the pre-step of `test:e2e` (before Playwright starts the
+// dev server). Kept a plain node script — not a Playwright globalSetup — because Playwright
+// transpiles setup files into a cache dir, which moved the relative --persist-to target off the
+// source tree and silently left the DB empty. Run via pnpm, cwd is always apps/web.
+//
+// migrations apply → e2e/seed-e2e.sql (raw entities + domain contracts) → precompute.sql (rollups +
+// FTS search index). Uses a dedicated D1 persist dir (matching vite.config's E2E branch) so it never
+// touches the developer's local dev DB. Fail-loud: throws if the derive left home_totals empty.
+import { execFileSync } from 'node:child_process';
+
+const PERSIST = '.wrangler/e2e-state';
+const D1 = ['d1', 'execute', 'sigma', '--local', '--persist-to', PERSIST];
+
+function wrangler(args, opts = {}) {
+  return execFileSync('pnpm', ['exec', 'wrangler', ...args], {
+    stdio: opts.capture ? ['inherit', 'pipe', 'inherit'] : 'inherit',
+    encoding: 'utf8',
+  });
+}
+
+wrangler(['d1', 'migrations', 'apply', 'sigma', '--local', '--persist-to', PERSIST]);
+wrangler([...D1, '--file', 'e2e/seed-e2e.sql']);
+wrangler([...D1, '--file', '../../scripts/precompute.sql']);
+
+const out = wrangler([...D1, '--command', 'SELECT COUNT(*) AS n FROM home_totals;', '--json'], {
+  capture: true,
+});
+const rows = JSON.parse(out)?.[0]?.results ?? [];
+if (Number(rows[0]?.n) < 1) {
+  throw new Error(`E2E seed failed: home_totals is empty after precompute (persist=${PERSIST}).`);
+}
+console.log('E2E database seeded (rollups + FTS index built).');

apps/web/package.json

@@ -9,6 +9,7 @@
     "preview": "react-router build && vite preview",
     "deploy": "react-router build && node ../../scripts/wrangler-render.mjs build/server/wrangler.json && wrangler deploy --config build/server/wrangler.deploy.json",
     "test": "vitest run --config vitest.config.ts",
+    "test:e2e": "node e2e/seed.mjs && playwright test",
     "typecheck": "wrangler types && react-router typegen && tsc -b",
     "cf-typegen": "wrangler types"
   },
@@ -26,7 +27,9 @@
     "react-router": "7.18.0"
   },
   "devDependencies": {
+    "@axe-core/playwright": "^4.10.2",
     "@cloudflare/vite-plugin": "^1.29.1",
+    "@playwright/test": "^1.56.1",
     "@react-router/dev": "7.18.0",
     "@tailwindcss/vite": "^4.2.2",
     "@types/node": "^22",