Getting Started
Configuration
Configure UI Inspect projects, screenshots, thresholds, and TurboSnap.
Configuration file
UI Inspect uses a YAML configuration file at the root of your project. Create one with npx ui-inspect init or manually:
# Required: Your project ID from the dashboard
projectId: "uuid-from-dashboard"
# Base URL for screenshot capture (default: http://localhost:3000)
baseUrl: "http://localhost:3000"
# API URL (default: https://app.uiinspect.dev)
apiUrl: "https://app.uiinspect.dev"
# Pixel diff threshold (0-1, default: 0.1)
# Lower values are stricter. 0 = exact match, 1 = allow everything
threshold: 0.1
# Exit with code 1 if diffs exceed threshold (default: true)
failOnDiff: true
# Auto-approve screenshots that have no existing baseline (default: false)
autoApprove: false
# Directory for storing captured screenshots
screenshotDir: ".ui-inspect/screenshots"
# Screenshot definitions
screenshots:
- name: "homepage"
url: "/"
viewports:
- name: "desktop"
width: 1440
height: 900
- name: "tablet"
width: 768
height: 1024
- name: "mobile"
width: 375
height: 812
- name: "login"
url: "/login"
viewports:
- name: "desktop"
width: 1440
height: 1080
# TurboSnap configuration
turboSnap:
enabled: true
baseBranch: "main"
# Files that trigger full re-test when changed
globalDeps:
- "src/styles/**"
- "tailwind.config.*"
- "package.json"
# Include untracked files in analysis
includeUntracked: falseScreenshot configuration
Each screenshot entry defines a page to capture:
| Field | Type | Required | Description |
|---|---|---|---|
name | string | Yes | Unique identifier for this screenshot |
url | string | Yes | Path relative to baseUrl |
viewports | array | Yes | List of viewport sizes |
viewports[].name | string | Yes | Viewport label (e.g., "desktop") |
viewports[].width | number | Yes | Viewport width in pixels |
viewports[].height | number | Yes | Viewport height in pixels |
Threshold tuning
The threshold value controls how sensitive the diff detection is:
| Value | Sensitivity | Use case |
|---|---|---|
0 | Exact match | Pixel-perfect designs, static pages |
0.05 | Very strict | Design system components |
0.1 | Recommended | General visual regression |
0.2 | Lenient | Pages with dynamic content |
0.5 | Very lenient | Rough layout checks only |
The smart diff engine also applies anti-flake filtering and SSIM analysis on top of the pixel threshold, so even at strict thresholds, anti-aliasing noise won't cause false positives.
Environment variables
These override config file values:
| Variable | Description |
|---|---|
UI_INSPECT_TOKEN | API authentication token (required) |
UI_INSPECT_API_URL | Override API server URL |
UI_INSPECT_PROJECT_ID | Override project ID |
CI provider detection
The CLI auto-detects your CI environment and extracts branch/commit info:
| Provider | Detected via |
|---|---|
| GitHub Actions | GITHUB_ACTIONS |
| GitLab CI | GITLAB_CI |
| CircleCI | CIRCLECI |
| Buildkite | BUILDKITE |
| Travis CI | TRAVIS |
You can always override with --branch and --commit flags.