Add single-command visual regression workflow

Add compare-branches.sh that automates the baseline generation and
comparison workflow into a single npm run test:visual command. The
script checks out trunk (or a specified base branch), generates
baseline snapshots, switches back to the feature branch, and runs
the comparison.

Author: josephfusco

package.json

@@ -129,7 +129,7 @@
 		"test:php": "node ./tools/local-env/scripts/docker.js run --rm php ./vendor/bin/phpunit",
 		"test:coverage": "npm run test:php -- --coverage-html ./coverage/html/ --coverage-php ./coverage/php/report.php --coverage-text=./coverage/text/report.txt",
 		"test:e2e": "wp-scripts test-playwright --config tests/e2e/playwright.config.js",
-		"test:visual": "wp-scripts test-playwright --config tests/visual-regression/playwright.config.js",
+		"test:visual": "bash tests/visual-regression/compare-branches.sh",
 		"gutenberg:checkout": "node tools/gutenberg/checkout-gutenberg.js",
 		"gutenberg:build": "node tools/gutenberg/build-gutenberg.js",
 		"gutenberg:copy": "node tools/gutenberg/copy-gutenberg-build.js",

tests/visual-regression/README.md

@@ -4,8 +4,32 @@ These tests make use of Playwright, with a setup very similar to that of the e2e
 
 ## How to Run the Tests Locally
 
-1. Check out trunk.
-2. Run `npm run test:visual` to generate some base snapshots.
-3. Check out the feature branch to be tested.
-4. Run `npm run test:visual` again. If any tests fail, the diff images can be found in `artifacts/`
+From a feature branch with a clean working tree, run:
+
+```bash
+npm run test:visual
+```
+
+This will automatically:
+1. Check out trunk to generate baseline snapshots.
+2. Return to your feature branch.
+3. Compare the current branch against those baselines.
+
+If any tests fail, diff images can be found in `artifacts/`.
+
+### Specifying a Base Branch
 
+By default, baselines are generated from `trunk`. To compare against a different branch:
+
+```bash
+npm run test:visual -- some-other-branch
+```
+
+### Manual 2-Step Workflow
+
+You can also generate baselines and compare manually:
+
+1. Check out the base branch (e.g. trunk).
+2. Run `npx playwright test --config tests/visual-regression/playwright.config.js --update-snapshots`
+3. Check out the feature branch to be tested.
+4. Run `npx playwright test --config tests/visual-regression/playwright.config.js`

tests/visual-regression/compare-branches.sh

@@ -0,0 +1,25 @@
+#!/bin/bash
+set -e
+
+CURRENT_BRANCH=$(git rev-parse --abbrev-ref HEAD)
+BASELINE_BRANCH="${1:-trunk}"
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+CONFIG="$SCRIPT_DIR/playwright.config.js"
+
+if [ "$CURRENT_BRANCH" = "$BASELINE_BRANCH" ]; then
+	echo "Error: Already on $BASELINE_BRANCH. Checkout a feature branch first."
+	exit 1
+fi
+
+if ! git diff-index --quiet HEAD --; then
+	echo "Error: Uncommitted changes detected. Please commit or stash before running."
+	exit 1
+fi
+
+echo "Generating baselines from $BASELINE_BRANCH..."
+git checkout "$BASELINE_BRANCH"
+npx playwright test --config "$CONFIG" --update-snapshots
+
+echo "Comparing against $CURRENT_BRANCH..."
+git checkout "$CURRENT_BRANCH"
+npx playwright test --config "$CONFIG"