visual-smoke

name	visual-smoke
description	Reference for what visual smoke covers (and doesn't) when a fix touches client-side UI or styles. The actual smoke runs automatically in CI; this skill documents the manual decision tree for routes CI can't reach (authenticated screens, multi-step flows, post-auth overlays).
source	https://github.com/Ethanon/developer.ai
license	MIT

Visual Smoke for Client Changes

CI-green code that was never rendered can ship a regression: a CSS token rename, a missing asset, an overlay misalignment. Unit tests pass, lint passes, build passes, and the screen is still broken to a human eye.

The cheapest defense is a smoke test in the testing sense: power the thing up and see if it explodes. For UI, that means build or start the app, render the affected screen in a real browser, take a screenshot.

How visual smoke runs today

Automatically, in CI. Configure a workflow (e.g. .github/workflows/visual-smoke.yml) to trigger on any PR whose diff touches:

• Templates or views: src/templates/**, templates/** (Django/Jinja), app/views/** (Flask)
• Static assets: static/**, assets/**, public/**
• Frontend source: frontend/src/**, client/src/** (if you have a bundled SPA)
• Bundler or build config: vite.config.*, webpack.config.*, pyproject.toml build section

The workflow installs dependencies, starts the dev or preview server, drives a headless browser (Playwright Chromium or Puppeteer) against it, captures a full-page screenshot of the landing screen, and posts a PR comment linking the artifact. No agent decision required; no manual step.

This catches:

• Boot breakage (the server crashes on startup or returns a 500 on the landing route).
• Template regressions on the landing screen (the most-touched shared rendering surface).
• Console / runtime errors during page load.
• Missing static assets, broken import paths, failed service-worker registration (if applicable).

What CI does NOT cover

The auto-smoke loads only the landing screen. It does not exercise:

• Authenticated screens (require a live session and a running backend).
• Multi-step flows (require state and, often, database fixtures).
• Settings or save operations (load fine, but persisting requires backend).
• Any view reachable only after login or interaction.

If your change affects one of these and the landing screenshot won't tell the reviewer anything useful, write a short Manual smoke section in the PR description naming what to click. Example:

## Manual smoke

The auto-smoke covers the landing screen only; this change touches
`templates/dashboard/stats_panel.html` which only renders after login.
Please sign in and confirm the stats panel renders without layout overflow
on a 1280px viewport.

The reviewer reads this and clicks. That is the current ceiling for routes the runner cannot reach.

Setting up the workflow

Django / Jinja templates

visual-smoke:
  if: >
    contains(github.event.pull_request.changed_files_url, 'templates/') ||
    contains(github.event.pull_request.changed_files_url, 'static/')
  runs-on: ubuntu-latest
  steps:
    - uses: actions/checkout@v4
    - uses: actions/setup-python@v5
      with:
        python-version: '3.12'
    - run: pip install -r requirements.txt
    - run: npx playwright install chromium --with-deps
    - name: Smoke screenshot
      run: |
        python manage.py runserver 8000 &
        sleep 3
        npx playwright screenshot --browser chromium http://localhost:8000 smoke.png
    - uses: actions/upload-artifact@v4
      with:
        name: smoke-screenshot
        path: smoke.png

FastAPI / Flask (uvicorn)

visual-smoke:
  if: >
    contains(github.event.pull_request.changed_files_url, 'templates/') ||
    contains(github.event.pull_request.changed_files_url, 'static/')
  runs-on: ubuntu-latest
  steps:
    - uses: actions/checkout@v4
    - uses: actions/setup-python@v5
      with:
        python-version: '3.12'
    - run: pip install -r requirements.txt
    - run: npx playwright install chromium --with-deps
    - name: Smoke screenshot
      run: |
        uvicorn app.main:app --port 8000 &
        sleep 3
        npx playwright screenshot --browser chromium http://localhost:8000 smoke.png
    - uses: actions/upload-artifact@v4
      with:
        name: smoke-screenshot
        path: smoke.png

Python backend + bundled SPA (Vite/webpack frontend served by the API)

visual-smoke:
  if: >
    contains(github.event.pull_request.changed_files_url, 'frontend/src/') ||
    contains(github.event.pull_request.changed_files_url, 'static/')
  runs-on: ubuntu-latest
  steps:
    - uses: actions/checkout@v4
    - uses: actions/setup-node@v4
      with:
        node-version: '20'
    - uses: actions/setup-python@v5
      with:
        python-version: '3.12'
    - run: npm ci --prefix frontend && npm run build --prefix frontend
    - run: pip install -r requirements.txt
    - run: npx playwright install chromium --with-deps
    - name: Smoke screenshot
      run: |
        uvicorn app.main:app --port 8000 &
        sleep 3
        npx playwright screenshot --browser chromium http://localhost:8000 smoke.png
    - uses: actions/upload-artifact@v4
      with:
        name: smoke-screenshot
        path: smoke.png

Adapt the start command (manage.py runserver, uvicorn, gunicorn, flask run) and the trigger paths to your project's layout.

Failure modes

If the auto-smoke job fails, do not skip it or merge anyway. Failure means one of:

1. Server crashed on startup. Check logs. Fix the boot error.
2. Page errored at load. Open the artifact, read the runtime error, fix the root cause.
3. Screenshot looks wrong to the human reviewer. Treat as a regression.

A "wait it'll pass next time" rerun is not a fix. Every smoke failure has a real cause.

Why this is a CI gate, not an agent decision

An earlier approach had the developer-agent invoke visual smoke before opening the PR. That made the agent the gate, which means a human PR could ship UI changes without smoke. CI is the better gate: every UI PR runs the smoke regardless of who opened it.

The skill remains as documentation for the not-runnable case. When the auto-smoke cannot reach the route the change affects, the PR description's ## Manual smoke section is the substitute. That is the only thing this skill asks of you today.