VisualQ — GitHub Action

Run visual regression tests and 6-pillar quality gates on every pull request with VisualQ. Catch pixel-level UI bugs, accessibility regressions, perf budget failures, and functional test regressions before production.

Free Quality Audit (no signup, real Lighthouse + axe): visualq.ai/audit

Also available: @visualq/cli for GitLab/Jenkins · @visualq/mcp for Cursor/Claude Desktop

Full documentation: visualq.ai/docs/ci-cd/github-action

Quick start

# .github/workflows/visual-test.yml
name: Visual Regression
on: [pull_request]

jobs:
  visual-test:
    runs-on: ubuntu-latest
    steps:
      - uses: abecms/visualq-action@v1
        with:
          api-key: ${{ secrets.VISUALQ_API_KEY }}
          project: "your-project-slug"

Get your API key

1. Sign up at visualq.ai
2. Open Settings → API keys in your project
3. Add the key as a repository secret: VISUALQ_API_KEY

Inputs

Input	Required	Default	Description
api-key	Yes	—	Your VisualQ API key (repository secret)
project	Yes	—	VisualQ project slug
type	No	test	Run type: test, baseline, perf, seo, a11y, security, tracking, or frt
feature-ids	No	—	Comma-separated FRT feature IDs (only when type: frt)
environment	No	—	Environment name or slug (e.g. staging, production)
scenarios	No	—	Comma-separated scenario labels to test
browsers	No	—	Comma-separated: chromium, firefox, webkit
wait	No	true	Wait for run completion (true or false)
api-url	No	https://visualq.ai	VisualQ API base URL
jira-key	No	—	Jira issue key to link results (e.g. PROJ-123)
perf-budgets	No	—	JSON perf budgets, e.g. {"lcp":2500,"fcp":1800,"cls":0.1,"tbt":300,"ttfb":800,"score":75}
locale	No	auto	Log language: en, fr, es, de, it, pt, pt-BR, nl, pl, tr, ru, zh, ja, ko, ar, hi. Auto-detected from LANG or VISUALQ_LOCALE when omitted

Outputs

Output	Description
run-id	The VRT run ID
status	Run status: completed, failed, or started (when wait: false)
passed	Number of passed scenarios
failed	Number of failed scenarios
frt-failed-steps	Number of failed FRT steps (when type: frt)
report-url	URL to the report on VisualQ (includes ?environmentId= when an environment was resolved)
perf-score	Performance score 0–100 (when type: perf)
seo-score	SEO score 0–100 (when type: seo)

Example workflows

Visual tests on pull requests

name: Visual Tests
on: pull_request

jobs:
  vrt:
    runs-on: ubuntu-latest
    steps:
      - uses: abecms/visualq-action@v1
        id: vrt
        with:
          api-key: ${{ secrets.VISUALQ_API_KEY }}
          project: my-website

      - name: Comment results
        if: always()
        uses: actions/github-script@v7
        with:
          script: |
            github.rest.issues.createComment({
              owner: context.repo.owner,
              repo: context.repo.repo,
              issue_number: context.issue.number,
              body: `Visual test: **${{ steps.vrt.outputs.status }}** — ${{ steps.vrt.outputs.passed }} passed, ${{ steps.vrt.outputs.failed }} failed. [View report](${{ steps.vrt.outputs.report-url }})`
            })

Update baselines on main

name: Update Baselines
on:
  push:
    branches: [main]

jobs:
  baseline:
    runs-on: ubuntu-latest
    steps:
      - uses: abecms/visualq-action@v1
        with:
          api-key: ${{ secrets.VISUALQ_API_KEY }}
          project: my-website
          type: baseline

Performance budgets

- uses: abecms/visualq-action@v1
  with:
    api-key: ${{ secrets.VISUALQ_API_KEY }}
    project: my-website
    type: perf
    environment: staging
    perf-budgets: '{"lcp":2500,"cls":0.1,"score":75}'

FRT functional tests

- uses: abecms/visualq-action@v1
  with:
    api-key: ${{ secrets.VISUALQ_API_KEY }}
    project: my-website
    type: frt
    environment: staging
    # feature-ids: feat_abc,feat_def

Test against staging

- uses: abecms/visualq-action@v1
  with:
    api-key: ${{ secrets.VISUALQ_API_KEY }}
    project: my-website
    environment: staging

Multi-browser testing

- uses: abecms/visualq-action@v1
  with:
    api-key: ${{ secrets.VISUALQ_API_KEY }}
    project: my-website
    browsers: "chromium,firefox,webkit"

Fire and forget

- uses: abecms/visualq-action@v1
  with:
    api-key: ${{ secrets.VISUALQ_API_KEY }}
    project: my-website
    wait: "false"

How it works

1. The action triggers a run via the VisualQ CI API (POST /api/ci/run)
2. VisualQ executes the requested audit type (VRT, perf, SEO, FRT, etc.)
3. The action polls for completion (up to 5 minutes) and reports results
4. On failure, the check fails with a link to the diff/report on VisualQ

PR context (commitSha, branch, prNumber) is sent automatically when the workflow runs on a pull request.

Troubleshooting

Issue	Fix
unauthorized	Verify VISUALQ_API_KEY secret and project slug
Timeout after 5 min	Test fewer scenarios (scenarios input) or split into parallel jobs
Marketplace badge 404	Listing not published yet — see docs/MARKETPLACE.md

License

MIT — see LICENSE.