shipkit-qa-visual

shipkit-qa-visual

Visual QA for SaaS apps using Playwright as a lightweight browser automation library — not a test framework. Write an inline script, run it, screenshot meaningful states, read the screenshots, report against UI goals.

---

Modes

Parse $ARGUMENTS to determine mode:

• --setup → Run the Setup flow (one-time per project)
• Anything else (or empty) → Run the Visual QA flow

---

Setup Mode (--setup)

One-time project setup. Walk through each step, skip any that are already done.

1. Install Playwright

Check if playwright is in package.json devDependencies. If not:

npm install -D @playwright/test playwright

Then install Chromium (warn user about ~200MB download):

npx playwright install chromium

2. Create playwright.config.ts

Only if it doesn't exist at the project root. Detect the app's base URL first:

1. Check $ARGUMENTS for a URL
2. Probe common ports: curl -s -o /dev/null -w "%{http_code}" http://localhost:3000 (try 3000, 5173, 4321, 8080, 6847)
3. Check package.json scripts for port hints
4. Ask the user if none found

import { defineConfig, devices } from '@playwright/test';

export default defineConfig({
  testDir: './e2e',
  fullyParallel: false,
  retries: 0,
  timeout: 120_000,
  expect: { timeout: 30_000 },
  use: {
    baseURL: '<detected-url>',
    trace: 'on-first-retry',
    screenshot: 'only-on-failure',
  },
  projects: [
    { name: 'chromium', use: { ...devices['Desktop Chrome'] } },
  ],
});

3. Create directories

mkdir -p screenshots e2e

Add screenshots/ to .gitignore if not already there.

4. Create UI Goals

This is the interactive step. The goals document grounds all future visual feedback.

Scan the codebase for routes/pages:

• Next.js: glob app/**/page.{tsx,ts,jsx,js} and pages/**/*.{tsx,ts,jsx,js} (exclude _app, _document, api/)
• React Router: grep for <Route or createBrowserRouter
• Other: grep for route definitions