GitHub Action

The VisualQ GitHub Action makes it easy to run visual tests directly in your GitHub Actions workflow.

Quick start

name: Visual Regression Tests
on: [pull_request]

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

Inputs

Input	Required	Default	Description
`api-key`	Yes	—	VisualQ API key (use GitHub secrets)
`project`	Yes	—	VisualQ project slug
`type`	No	`test`	Run type: `test`, `baseline`, `perf`, or `seo`
`environment`	No	—	Environment name or slug (e.g., `staging`)
`scenarios`	No	—	Comma-separated scenario labels to test
`wait`	No	`true`	Wait for completion (`true`/`false`)
`api-url`	No	`https://visualq.ai`	VisualQ API base URL
`browsers`	No	—	Comma-separated: `chromium`, `firefox`, `webkit`
`jira-key`	No	—	Jira issue key (e.g., `PROJ-123`)
`perf-budgets`	No	—	JSON performance budgets (e.g., `{"lcp":2500,"fcp":1800,"cls":0.1,"tbt":300,"ttfb":800,"score":75}`)

Outputs

Output	Description
`run-id`	The unique VRT run identifier
`status`	Final status: `completed`, `failed`, or `started` (when `wait: false`)
`passed`	Number of passed scenarios
`failed`	Number of failed scenarios
`report-url`	URL to the visual report on VisualQ
`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

Run visual tests on every PR and fail the check if differences are detected:

name: Visual Tests
on: pull_request

jobs:
  vrt:
    runs-on: ubuntu-latest
    steps:
      - uses: visualq/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

Automatically sync baselines when code is merged to main:

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

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

Test specific scenarios

Only test certain scenarios for faster feedback:

- uses: visualq/visualq-action@v1
  with:
    api-key: ${{ secrets.VISUALQ_API_KEY }}
    project: my-website
    scenarios: "Homepage,Pricing page,Login"

Test against a specific environment

Run tests against your staging environment:

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

Test multiple environments

Run the same tests against staging and production in parallel:

jobs:
  visual-test:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        environment: [staging, production]
    steps:
      - uses: visualq/visualq-action@v1
        with:
          api-key: ${{ secrets.VISUALQ_API_KEY }}
          project: my-website
          environment: ${{ matrix.environment }}

Multi-browser testing

Test across multiple browsers:

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

Firefox and WebKit require Pro plan or higher

Timeout

The action polls for up to 300 seconds (5 minutes) for the run to complete. If wait is set to false, the action returns immediately after triggering the run.

Troubleshooting

Action fails with "unauthorized"

Verify your API key is correctly stored in GitHub Secrets and matches the project slug.

Action times out

Large projects with many scenarios may take longer than 5 minutes. Consider testing specific scenarios or splitting into multiple jobs.

On this page