test(playwright): finalize automated screenshot flow per issue #40 (handoff)

[jdjioe5-cpu]

Contributor: @jdjioe5-cpu
PR picks up PR #39 (copilot/automated-playwright-screenshot-flow) on top of upstream/main and addresses every check from GoodBounty issue #40.

Refs: #40, #39, #38

What changed (commits on jdjioe5-cpu/issue40-playwright-final)

• tests-playwright/wallet-flows.e2e.ts
  • Stores defaultLoginMethod as a JSON-encoded string so useLocalStorageValue's JSON.parse round-trip no longer throws SyntaxError: Unexpected token 'e' on every run.
  • Moves screenshots under per-flow directories (tests-playwright/<flow>/screenshot-<state>-<viewport>.png) per the issue [PLAN] Automated Playwright and Screenshot Flow #38 layout, using semantic state names.
• package.json
  • Replaces the misleading test:e2e:screenshots (--update-snapshots against a suite with no snapshot assertion) with a real --grep filter that targets the three approved screenshot flows.
  • Adds test:e2e:headed, test:e2e:debug, and test:e2e:update-baselines helpers that match the documented baseline policy.
• .gitignore
  • Ignores generated Playwright screenshots, traces, videos, and reports while whitelisting the intentional screenshot-<state>-<viewport>.png baseline pattern under each flow directory.
• README.md
  • Adds a Playwright contributor guide covering install, run, test-mode boundaries, screenshot layout, adding a flow, intentional baseline updates, and failure triage.
• .github/workflows/playwright-agent.yml — see "Agent-triggered CI" below.

Agent-triggered CI

The CI workflow is workflow_dispatch only so it never becomes an unconditional PR gate. When launched from the Actions tab (or via gh workflow run playwright-agent.yml), it:

1. Re-runs yarn install --immutable.
2. Installs the Playwright Chromium binary.
3. Runs yarn biome:verify:all and the Playwright suite.
4. Uploads tests-playwright/**/screenshot-*.png, tests-playwright/artifacts/, playwright-report/, and test-results/ as a single playwright-artifacts artifact with a 14-day retention.

The existing .github/workflows/goodwallet-pr.yml (Biome, build, Vitest) is left untouched and continues to gate every PR.

Constraint on this PR

The contributor token does not carry the GitHub workflow OAuth scope, so .github/workflows/playwright-agent.yml is not part of the diff pushed by this branch. GitHub rejected the push with:

refusing to allow an OAuth App to create or update workflow .github/workflows/playwright-agent.yml without workflow scope

The full YAML is reproduced below so any maintainer (or any account with workflow scope) can paste it into .github/workflows/playwright-agent.yml and the workflow will run unchanged:

name: Playwright screenshot flow (agent-triggered)

on:
  workflow_dispatch:
    inputs:
      grep:
        description: "Optional Playwright --grep filter (defaults to the three approved screenshot flows)"
        required: false
        default: ""
        type: string

jobs:
  playwright-agent:
    name: Run Playwright suite and upload artifacts
    runs-on: ubuntu-latest
    timeout-minutes: 30

    permissions:
      contents: read

    env:
      NEXT_PUBLIC_PLAYWRIGHT_TEST_MODE: "true"
      NEXT_PUBLIC_LOGIN_GOOGLE_ENABLED: "false"
      NEXT_PUBLIC_LOGIN_FACEBOOK_ENABLED: "false"
      NEXT_PUBLIC_LOGIN_PWLESS_ENABLED: "false"
      NEXT_PUBLIC_TEST_LOGIN_ENABLED: "true"
      NODE_OPTIONS: --max_old_space_size=4096

    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Install Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 24
          cache: yarn

      - name: Install dependencies (immutable)
        run: yarn install --immutable

      - name: Install Playwright Chromium browser
        run: yarn playwright install --with-deps chromium

      - name: Run Biome check
        uses: borales/actions-yarn@v5
        with:
          cmd: biome:verify:all

      - name: Run Playwright suite
        run: |
          if [ -n "${{ inputs.grep }}" ]; then
            yarn test:e2e --grep "${{ inputs.grep }}"
          else
            yarn test:e2e
          fi

      - name: Upload screenshots, traces, videos, and HTML report
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: playwright-artifacts
          path: |
            tests-playwright/**/screenshot-*.png
            tests-playwright/artifacts/
            playwright-report/
            test-results/
          if-no-files-found: warn
          retention-days: 14

      - name: Summarize suite run
        if: always()
        run: |
          {
            echo "### Playwright agent run"
            echo "- Trigger: workflow_dispatch"
            echo "- Status: ${{ job.status }}"
            echo "- Branch: ${{ github.ref }}"
            echo "- Run URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}"
          } >> "$GITHUB_STEP_SUMMARY"

Verification

Run from the repo root on jdjioe5-cpu/issue40-playwright-final:

Command	Result
yarn install --immutable	Pass — workspace installs cleanly with the updated Playwright + Vitest resolution.
yarn biome:verify:all	Pass — 411 files checked, no diagnostics.
yarn test	Pass — 4 Vitest files, 83 unit tests.
yarn playwright install chromium	Pass — Chromium 145.x downloaded into ~/.cache/ms-playwright.
yarn test:e2e	Pass — desktop + mobile Chromium projects run the three approved flows and write screenshots under tests-playwright/<flow>/. Browser console shows zero SyntaxError from useDefaultLoginMethod.ts.
Agent-triggered CI	Cannot run from the contributor branch (no workflow scope). The YAML above and the gh workflow run playwright-agent.yml command in the README are the documented reproduction path; a maintainer-run dispatch will publish the same artifact bundle.

Playwright scenarios a reviewer can run

yarn install --immutable
yarn playwright install chromium
yarn test:e2e               # all three flows, desktop + mobile
yarn test:e2e:screenshots   # only the three approved flows
yarn test:e2e:headed        # visible browser
yarn test:e2e:debug         # Playwright Inspector

The three flows captured as committed baselines are:

1. tests-playwright/login-onboarding/screenshot-onboarding-da-{desktop,mobile}.png (locale-aware onboarding/login entry).
2. tests-playwright/home/screenshot-home-balances-overflow-en-{desktop,mobile}.png (authenticated home + mobile action overflow).
3. tests-playwright/claim/screenshot-claim-requires-verification-en-{desktop,mobile}.png (GoodDollar claim UI with verification-required state).

Screenshot/artifact locations

• Committed baselines: tests-playwright/<flow>/screenshot-<state>-<viewport>.png.
• Per-run artifacts (gitignored): tests-playwright/artifacts/, playwright-report/, test-results/.

Remaining risks

• The .github/workflows/playwright-agent.yml file itself is held back until a maintainer pastes it (token-scope limit). The behavior, trigger semantics, and artifact paths are documented above and in README.md.
• The currently shipped goodwallet-pr.yml keeps using a non-immutable yarn install path for speed; this PR does not touch it.
• Future flows should keep the credential-free boundary (NEXT_PUBLIC_PLAYWRIGHT_TEST_MODE, wallet seed generated per run, all non-local requests aborted at the browser boundary).

ETA: 24h from maintainer ack.

[vercel]

@jdjioe5-cpu is attempting to deploy a commit to the GoodDollarTeam Team on Vercel.

A member of the Team first needs to authorize it.