node-update-visual-snapshots.yml

# Node Update Visual Snapshots
#
# Reusable workflow for regenerating Playwright visual baseline screenshots.
# Intended to be called from a workflow_dispatch trigger in the consuming repo
# whenever the UI changes intentionally and the baselines need refreshing.
#
# Runs on ubuntu-latest — the same OS as CI visual-test jobs — so the
# committed *-chromium-linux.png files always match what CI compares against.
#
# After generating new snapshots the workflow commits them back to the branch
# with "[skip ci]" to avoid triggering a CI loop.
#
# Typical lifecycle:
#   1. First-time setup OR after an intentional UI change:
#        consuming repo → Actions → "Update Visual Snapshots" → Run workflow
#   2. This workflow generates new *-chromium-linux.png files and commits them.
#   3. Subsequent CI runs compare the live render against those committed files.
#
# Usage in a consuming repository:
#
#   on:
#     workflow_dispatch:
#       inputs:
#         branch:
#           description: 'Branch to update snapshots on (leave blank for current branch)'
#           required: false
#           default: ''
#
#   jobs:
#     update-snapshots:
#       uses: orangitfi/platform-tooling/.github/workflows/node-update-visual-snapshots.yml@<sha>
#       with:
#         branch: ${{ github.event.inputs.branch }}
#       permissions:
#         contents: write
#
# All inputs have sensible defaults — a consuming repo only needs to override
# what differs from the defaults below.

name: Update Visual Snapshots

on:
  workflow_call:
    inputs:
      branch:
        description: >
          Branch to check out and push updated snapshots to.
          Leave empty to use the ref that triggered the calling workflow.
        required: false
        default: ""
        type: string
      node-version:
        description: "Node.js version to use"
        required: false
        default: "20"
        type: string
      working-directory:
        description: "Directory containing package.json"
        required: false
        default: "."
        type: string
      build-command:
        description: "npm script to build the frontend (e.g. build, build:prod)"
        required: false
        default: "build"
        type: string
      update-snapshots-command:
        description: "npm script that runs Playwright with --update-snapshots"
        required: false
        default: "test:e2e:update-snapshots"
        type: string
      snapshot-path:
        description: "Repo-relative path containing the generated snapshot files"
        required: false
        default: "e2e/visual/__snapshots__/"
        type: string
      vite-api-base-url:
        description: >
          Value for VITE_API_BASE_URL baked into the Vite bundle at build time.
          All API calls are intercepted by page.route() in tests so the host
          does not need to be reachable — it only needs to be a valid URL.
        required: false
        default: "http://localhost:3001"
        type: string
      playwright-base-url:
        description: "Base URL Playwright navigates to (must match the preview server port)"
        required: false
        default: "http://localhost:4173"
        type: string

permissions:
  contents: write

jobs:
  update-snapshots:
    name: Generate / Update Visual Baseline Snapshots (Linux · Chromium)
    runs-on: ubuntu-latest

    # Allow this job to commit the new baseline images back to the branch.
    permissions:
      contents: write

    steps:
      - name: Checkout code
        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
        with:
          # Honour the optional branch input; fall back to the triggering ref.
          # persist-credentials is true by default — required for the git push below.
          ref: ${{ inputs.branch || github.ref }}

      - name: Set up Node.js
        uses: actions/setup-node@53b83947a5a98c8d113130e565377fae1a50d02f # v6.3.0
        with:
          node-version: ${{ inputs.node-version }}
          cache: "npm"

      - name: Install dependencies
        shell: bash
        working-directory: ${{ inputs.working-directory }}
        run: npm ci

      - name: Install Playwright Chromium
        shell: bash
        working-directory: ${{ inputs.working-directory }}
        run: npx playwright install --with-deps chromium

      - name: Build frontend
        shell: bash
        working-directory: ${{ inputs.working-directory }}
        run: npm run ${{ inputs.build-command }}
        env:
          # Baked into the Vite bundle at build time.
          # All API calls are intercepted by page.route() so the host does not
          # need to be reachable, but it must be a syntactically valid URL.
          VITE_API_BASE_URL: ${{ inputs.vite-api-base-url }}

      - name: Generate / update visual baseline snapshots
        shell: bash
        working-directory: ${{ inputs.working-directory }}
        run: npm run ${{ inputs.update-snapshots-command }}
        env:
          # Tell playwright.config.ts to auto-start `vite preview` before tests.
          PLAYWRIGHT_WEB_SERVER: "true"
          # `vite preview` listens on 4173 by default.
          PLAYWRIGHT_BASE_URL: ${{ inputs.playwright-base-url }}
          CI: "true"

      # Always upload freshly rendered snapshots as an artifact so you can
      # inspect them in the Actions UI before (or after) they land in the repo.
      - name: Upload generated snapshots as artifact
        if: always()
        uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0
        with:
          name: visual-snapshots-linux-chromium
          path: ${{ inputs.snapshot-path }}
          retention-days: 30

      - name: Commit and push updated snapshots
        shell: bash
        run: |
          git config user.name  "github-actions[bot]"
          git config user.email "github-actions[bot]@users.noreply.github.com"
          git add "${{ inputs.snapshot-path }}"
          if git diff --staged --quiet; then
            echo "No snapshot changes — baselines are already up to date."
          else
            git commit -m "chore: update visual baseline snapshots [skip ci]"
            git push
            echo "Snapshots committed and pushed."
          fi