Guides
CI/CD Integration
Set up automated visual regression testing in GitHub Actions, GitLab CI, CircleCI, and other CI providers.
Quick setup
Generate a workflow file automatically:
npx ui-inspect ci-setup --provider githubOr configure manually for full control.
GitHub Actions
name: Visual Regression Tests
on: [pull_request]
jobs:
visual-test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: pnpm/action-setup@v4
- uses: actions/setup-node@v4
with:
node-version: 22
cache: pnpm
- run: pnpm install
- run: pnpm build
- name: Start app
run: pnpm start &
env:
PORT: 3000
- name: Wait for app
run: npx wait-on http://localhost:3000
- name: Run visual tests
run: |
npx ui-inspect build \
--project ${{ secrets.UI_INSPECT_PROJECT_ID }} \
--fail-on-diff \
--report \
--pr ${{ github.event.pull_request.number }}
env:
UI_INSPECT_TOKEN: ${{ secrets.UI_INSPECT_TOKEN }}name: Visual Regression Tests
on: [pull_request]
jobs:
visual-test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0 # Required for TurboSnap git analysis
- uses: pnpm/action-setup@v4
- uses: actions/setup-node@v4
with:
node-version: 22
cache: pnpm
- run: pnpm install
- run: pnpm build
- run: pnpm start &
- run: npx wait-on http://localhost:3000
- name: Run visual tests with TurboSnap
run: |
npx ui-inspect build \
--project ${{ secrets.UI_INSPECT_PROJECT_ID }} \
--fail-on-diff \
--report \
--pr ${{ github.event.pull_request.number }} \
--turbosnap \
--base-branch main
env:
UI_INSPECT_TOKEN: ${{ secrets.UI_INSPECT_TOKEN }}name: Visual Regression Tests
on: [pull_request]
jobs:
visual-test:
runs-on: ubuntu-latest
strategy:
matrix:
viewport: [desktop, mobile, tablet]
steps:
- uses: actions/checkout@v4
- uses: pnpm/action-setup@v4
- uses: actions/setup-node@v4
with:
node-version: 22
cache: pnpm
- run: pnpm install && pnpm build
- run: pnpm start &
- run: npx wait-on http://localhost:3000
- name: Run visual tests (${{ matrix.viewport }})
run: |
npx ui-inspect build \
--project ${{ secrets.UI_INSPECT_PROJECT_ID }} \
--fail-on-diff
env:
UI_INSPECT_TOKEN: ${{ secrets.UI_INSPECT_TOKEN }}When using TurboSnap, set fetch-depth: 0 in the checkout step so git history
is available for merge-base analysis.
GitLab CI
visual-regression:
image: node:22
stage: test
before_script:
- corepack enable
- pnpm install
- pnpm build
script:
- pnpm start &
- npx wait-on http://localhost:3000
- npx ui-inspect build --project $UI_INSPECT_PROJECT_ID --fail-on-diff
variables:
UI_INSPECT_TOKEN: $UI_INSPECT_TOKEN
only:
- merge_requestsCircleCI
version: 2.1
jobs:
visual-regression:
docker:
- image: cimg/node:22.0-browsers
steps:
- checkout
- run: corepack enable && pnpm install
- run: pnpm build
- run:
name: Start app
command: pnpm start
background: true
- run: npx wait-on http://localhost:3000
- run:
name: Visual regression tests
command: |
npx ui-inspect build \
--project $UI_INSPECT_PROJECT_ID \
--fail-on-diff
workflows:
test:
jobs:
- visual-regressionRequired secrets
| Secret | Description |
|---|---|
UI_INSPECT_TOKEN | API key from Settings → API Keys |
UI_INSPECT_PROJECT_ID | Project ID from dashboard |
PR comments
When using --report, the CLI posts a comment on the PR with:
- Pass/fail status
- Screenshot count and diff summary
- Links to the dashboard for detailed review
- Stability indicators for flaky detections
The comment uses a hidden marker to update (not duplicate) on subsequent pushes.
Status checks
Add --status-check to the report command to also post a GitHub commit status:
npx ui-inspect report --pr 42 --status-checkThis shows a check in the PR's status area that can block merging if visual regressions are found.