certctl/.github/workflows/e2e.yml

# Phase 8 closure (TEST-H1 + TEST-H2): browser-driven E2E + visual
# regression. Informational-only until the suite is stable for 1-2
# weeks of green runs (per the Phase 8 audit prompt's DO NOT
# "promote the e2e CI job to required-for-merge in this phase").
#
# The job is intentionally NOT in the merge gate. It runs on every
# push to surface flakiness early; merge eligibility comes from
# ci.yml's existing gates (Vitest, lint, build, the 34 CI guards).
#
# Once 1-2 weeks of green runs accumulate:
#   1. Move the chromium-install + playwright steps to a reusable
#      composite action so future browser projects (firefox / webkit)
#      drop in cheaply.
#   2. Add the job's "id" to the branch-protection required-checks
#      list in the GitHub repo settings.
#   3. Delete the "Informational" banner from this file's header.
#
# Visual regression: the 04-visual-regression.spec.ts file uses
# Playwright `toHaveScreenshot()`. First-run on a new branch
# regenerates baselines via the `--update-snapshots` flag; the
# operator commits the resulting PNG bytes to git. Subsequent runs
# pixel-diff. The dispatch input below provides an explicit knob
# for that initial baseline pass without needing to edit the
# workflow file.

name: Frontend E2E (informational)

on:
  push:
    branches: [master]
    paths:
      - 'web/**'
      - '.github/workflows/e2e.yml'
  pull_request:
    paths:
      - 'web/**'
      - '.github/workflows/e2e.yml'
  workflow_dispatch:
    inputs:
      update_snapshots:
        description: 'Regenerate visual-regression baselines (use sparingly)'
        type: boolean
        default: false

permissions:
  contents: read

jobs:
  e2e:
    name: Playwright E2E + visual regression (informational)
    runs-on: ubuntu-latest
    # Currently informational — do not block merges on this job.
    # Update protected-branch rules in repo settings once stable.
    continue-on-error: true
    timeout-minutes: 15
    steps:
      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5  # v4

      - name: Set up Node.js
        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020  # v4
        with:
          node-version: '22'

      - name: Install Dependencies
        working-directory: web
        run: npm ci

      - name: Install Playwright browsers
        working-directory: web
        # --with-deps installs OS packages (libnss3, libatk1.0-0, etc.)
        # the chromium browser needs. Skipping this is the #1 source
        # of "tests pass locally but fail on CI" for new Playwright
        # users. The browser binary downloads to ~/.cache/ms-playwright;
        # the actions/setup-node cache key does NOT include it, so each
        # CI run re-downloads. Add an actions/cache step targeting
        # ~/.cache/ms-playwright keyed by the @playwright/test version
        # in package-lock.json once the suite is stable.
        run: npx playwright install --with-deps chromium

      - name: Run Playwright E2E + visual regression
        working-directory: web
        # The webServer block in playwright.config.ts boots `npm run dev`
        # automatically and waits for http://localhost:5173 to be
        # responsive before the first test fires. No separate "start
        # server" step needed.
        run: |
          if [[ "${{ github.event.inputs.update_snapshots }}" == "true" ]]; then
            echo "::warning::Regenerating visual-regression baselines"
            npx playwright test --update-snapshots
          else
            npx playwright test
          fi

      - name: Upload Playwright report on failure
        if: failure()
        uses: actions/upload-artifact@b4b15b8c7c6ac21ea08fcf65892d2ee8f75cf882  # v4
        with:
          name: playwright-report
          path: web/playwright-report/
          retention-days: 7

      - name: Upload visual-regression diffs on failure
        if: failure()
        uses: actions/upload-artifact@b4b15b8c7c6ac21ea08fcf65892d2ee8f75cf882  # v4
        with:
          name: visual-regression-diffs
          path: web/test-results/
          retention-days: 7