visualcheck 0.2.0

Visual regression checking with figma-first baselines, pixel+SSIM diffing, ignore regions, and HTML reports.

visualcheck

Visual regression checking with:

• Figma-first baselines (optionally synced via Figma API)
• Runtime baselines (auto-create when missing; never overwrite by default)
• Pixel diff % + SSIM (with optional resize-on-mismatch + WARN)
• Ignore regions (mask dynamic areas via selectors + explicit rects)
• Self-contained HTML report + report.json

Install

pip install visualcheck
playwright install chromium

Config (visualcheck.yaml)

project: consumer_website
suite: daily_sanity

envs:
  prod: "https://www.wakefit.co"

views:
  desktop_profiles: ["desktop_1440x900", "macbook_1440x900"]
  mobile_devices: ["iPhone 15 Pro Max", "iPhone 13 mini", "Pixel 7"]

pages:
  - id: home
    url: "/"
    wait_for: "body"
    full_page: true

# Optional flows (multi-step user journeys)
flows:
  - id: search_flow
    start_url: "/"
    steps:
      - action: click
        selector: "text=Search"
      - action: wait
        ms: 500
    snapshots:
      - id: after_search
        wait_for: "body"
        full_page: true

baseline:
  # Locked resolution order:
  # figma -> runtime -> create runtime baseline (if enabled)
  priority: ["figma", "runtime"]
  create_if_missing: true
  never_overwrite: true
  on_created: "INFO"  # INFO|WARN|FAIL

compare:
  resize_on_mismatch: true
  mismatch_level: "WARN"  # WARN|FAIL
  thresholds:
    max_pixel_diff_pct: 0.10
    min_ssim: 0.995

ignore_regions:
  global:
    selectors: ["#cookie-banner", ".chat-widget"]
  by_snapshot:
    home:
      rects:
        - {x: 0, y: 0, width: 300, height: 120}

# Optional Figma sync (writes into visual_baseline/<project>/<suite>/figma/...)
# figma:
#   token_env: FIGMA_TOKEN
#   file_key: "<FIGMA_FILE_KEY>"
#   frames:
#     - id: home
#       node_id: "123:456"
#       view_id: "desktop_1440x900"   # optional

Commands

Run full check

visualcheck run --env prod

Outputs:

• Baselines:
  • visual_baseline/<project>/<suite>/figma/<view>/<snapshot>.png
  • visual_baseline/<project>/<suite>/runtime/<view>/<snapshot>.png
• Run artifacts:
  • test_report/<project>/visual_runs/<run_id>/current/...
  • test_report/<project>/visual_runs/<run_id>/diff/...
  • test_report/<project>/visual_runs/<run_id>/report/report.html
  • test_report/<project>/visual_runs/<run_id>/report/report.json

Capture only

visualcheck capture --env prod --out current

Diff only

visualcheck diff --baseline visual_baseline/myproj/mysuite/runtime --current current --out report

Sync Figma baselines

export FIGMA_TOKEN="..."
visualcheck figma-sync

Approve current run as runtime baseline (explicit)

visualcheck approve --env prod --run-id 20260207_235500
# Overwrite existing runtime baselines only with:
visualcheck approve --env prod --run-id 20260207_235500 --force

Baseline rules (locked)

For each snapshot + view:

1. If a Figma baseline exists → use it
2. Else if a runtime baseline exists → use it
3. Else → capture and create runtime baseline (controlled by baseline.create_if_missing)

Notes

• Ignore regions are masked with a solid color before diffing.
• If screenshot sizes differ and compare.resize_on_mismatch=true, current is resized to baseline size and a warning is recorded.

License

MIT