Visual regression testing

Run automated visual regression tests to compare your Quant-hosted pages against their remote origins. The CLI uses Playwright and Chromium to capture screenshots and Pixelmatch to detect differences.

How it works

The VRT command crawls your Quant project, captures screenshots of each page on both the Quant URL and the remote origin URL, and compares them pixel by pixel. Any differences above the threshold are flagged.

Run a test

qc vrt

Options

Flag	Description
--project <project>	Specific projects to test (comma-separated for multiple)
--threshold <threshold>	Pixel difference threshold from 0 to 1 (default: 0.01)
--max-pages <maxPages>	Maximum pages to crawl per project
--max-depth <maxDepth>	Maximum crawl depth
--csv <file>	Generate a CSV report file
--quant-auth <credentials>	Basic auth for Quant URLs (user:pass)
--remote-auth <credentials>	Basic auth for remote URLs (user:pass)
--output-dir <dir>	Output directory for screenshots (default: ./vrt-results)

Configuration file

Create a configuration file at ~/.quant/vrt-config.json to define project mappings and default settings:

{
  "projects": {
    "my-project": "https://example.com",
    "protected-project": {
      "url": "https://example2.com",
      "remoteAuth": "user:pass",
      "quantAuth": "user:pass"
    }
  },
  "threshold": 0.01,
  "maxPages": 10,
  "maxDepth": 3
}

Project formats

Projects can be defined in two formats:

• Simple — a string URL for the remote origin: "my-project": "https://example.com"
• Detailed — an object with URL and optional auth credentials for password-protected sites

Examples

# Run VRT for all configured projects
qc vrt

# Test a specific project
qc vrt --project my-project

# Test multiple projects
qc vrt --project project-a,project-b

# Use a stricter threshold
qc vrt --threshold 0.005

# Limit crawl scope
qc vrt --max-pages 5 --max-depth 2

# Generate a CSV report
qc vrt --csv ./report.csv

# Test a password-protected site
qc vrt --project my-project --quant-auth admin:secret --remote-auth admin:secret

Output

Screenshots are saved to the output directory (default ./vrt-results) and include:

• Screenshots of the Quant-hosted page
• Screenshots of the remote origin page
• Diff images highlighting pixel differences

Each page is reported as PASS, FAIL, or ERROR based on the threshold.