deckhearth/tests/visual/homepage.spec.ts

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

/**
 * Visual baseline for the public homepage.
 *
 * The Screenshot diff workflow runs `playwright test --project=visual
 * --update-snapshots=none` (per .github/workflows/visual-diff.yml). The
 * `none` flag means "use the existing baseline; do not write a new one"
 * — drift between the rendered page and the committed PNG fails the
 * test. The committed Linux baseline lives at
 * `tests/visual/__screenshots__/home.png` (seeded by PR #58 `83a358b`,
 * 2026-06-02).
 *
 * Visual diff is a HARD MERGE GATE post-`harden-visual-diff-gate` brief 2
 * (PR #140). A failed diff blocks merge; there is no `continue-on-error`
 * escape valve. If the failure is intentional (real UI change), the
 * operator must dispatch the baseline-refresh workflow before merging
 * — see the section below.
 *
 * RE-SEEDING THE BASELINE (when the homepage changes intentionally):
 *   Always run on Linux — Mac-generated PNGs do not match CT 111 Linux
 *   output because `playwright.config.js`'s `snapshotPathTemplate` has
 *   no `{platform}` token. Two paths:
 *
 *   1. **Dispatch the seed-visual-baselines workflow (recommended).**
 *
 *        gh workflow run seed-visual-baselines.yml \
 *          -f base_url=<production-or-preview-vercel-url> \
 *          -f reason="<short reason>"
 *
 *      The workflow runs on the same CT 111 axiom runner as
 *      visual-diff.yml, so the captured PNG is byte-equivalent. It
 *      pushes the new baseline to a `bot/visual-baselines-<run_id>`
 *      branch. The auto-PR-open step requires the org-level "Allow
 *      GitHub Actions to create and approve pull requests" setting to
 *      be enabled (currently OFF for stwl-labs); if it fails, push
 *      the branch is fine and the operator opens the PR manually via:
 *
 *        gh pr create --base main \\
 *          --head bot/visual-baselines-<run_id> \\
 *          --title "chore(visual): refresh baselines ..."
 *
 *   2. **Playwright Docker image (host-independent).** Slower; useful
 *      if CT 111 is offline:
 *
 *        docker run --rm -v "$PWD":/work -w /work \\
 *          mcr.microsoft.com/playwright:v1.60.0-noble \\
 *          sh -c "npm ci && BASE_URL=https://<preview>.vercel.app \\
 *            VERCEL_AUTOMATION_BYPASS_SECRET=<value> \\
 *            npm run test:visual:update"
 *
 *      Then commit the regenerated `tests/visual/__screenshots__/home.png`.
 */
const BASE = process.env.BASE_URL ?? 'http://localhost:3000';

test.describe('visual: public homepage', () => {
  test('home renders consistently against baseline', async ({ page }) => {
    await page.goto(BASE);
    await expect(page).toHaveScreenshot('home.png');
  });
});