Sync baselines

Baselines (also called reference images) are the approved screenshots that VisualQ compares against during test runs. Every scenario needs a baseline before visual testing can detect changes.

Capturing baselines

From the project header, click "Sync refs". This:

1. Launches Playwright captures for all scenarios in the project
2. Takes screenshots at each configured viewport
3. Applies content rules and click selectors
4. Uploads the resulting images as the new baselines

When to sync baselines

You should re-sync baselines when:

• Setting up a new project — initial baseline capture
• After intentional changes — a redesign, new feature, or layout update
• After approving changes — the approve action does this automatically per scenario

Baseline storage

Baselines are stored in S3 with the following path structure:

vrt/[projectId]/env/[envId]/baselines/[label]_[viewport]_[browser]_0_document.png

Each scenario × viewport × browser combination produces one baseline image per environment. Legacy projects that predate environments may still use the flat path vrt/[projectId]/baselines/... — the platform falls back to this automatically.

Baseline for a single scenario

Instead of re-syncing all baselines, you can capture a baseline for a single scenario from its detail page. Click the Sync button on the scenario page.

CI/CD baselines

When using the GitHub Action or REST API, set the run type to baseline to capture baselines in CI:

- uses: visualq/visualq-action@v1
  with:
    api-key: ${{ secrets.VISUALQ_API_KEY }}
    project: my-project
    type: baseline

See GitHub Action for the full reference.