Skip to main content
VertaaUX Docs
CLICommands

baseline

Create and manage UX audit baselines for tracking improvements

vertaa baseline

Create baseline snapshots of audit results for tracking UX improvements over time.

Synopsis

vertaa baseline [options]

Description

The baseline command creates a snapshot of your current audit results. Use this baseline with subsequent audits to track new issues, resolved issues, and overall score trends. Baselines are essential for CI/CD quality gates that prevent regressions.

Why Use Baselines?

Baselines solve a common problem: you inherit a codebase with existing UX issues that can't all be fixed immediately. Instead of:

  1. Failing every audit (impractical)
  2. Ignoring all issues (defeats the purpose)

You can:

  1. Create a baseline of known issues
  2. Only fail on new issues introduced after the baseline
  3. Gradually improve while preventing regressions

Quick Examples

Create a baseline file
$vertaa baseline -u https://example.com -o baseline.json
Audit against the baseline
$vertaa audit -u https://example.com --baseline baseline.json
Update existing baseline
$vertaa baseline -u https://example.com --update baseline.json

Options

Options
ParameterTypeRequiredDescription
-u, --urlstringrequiredURL to audit for baseline creation
-o, --outputstringoptionalOutput file path for the baselineDefault: .vertaaux/baseline.json
--updatestringoptionalUpdate an existing baseline file instead of creating new
--modestringoptionalAudit mode: basic, standard, deepDefault: basic
--routesstringoptionalComma-separated routes to include in baseline
--mergebooleanoptionalMerge with existing baseline instead of replacingDefault: false

Baseline File Format

The baseline file is a JSON document containing:

{
  "version": "1.0",
  "created_at": "2026-01-15T10:30:00Z",
  "updated_at": "2026-01-15T10:30:00Z",
  "url": "https://example.com",
  "mode": "standard",
  "scores": {
    "overall": 78,
    "ux": 82,
    "accessibility": 71,
    "information_architecture": 80,
    "performance": 79
  },
  "issues": [
    {
      "fingerprint": "a1b2c3d4e5f6",
      "rule": "color-contrast",
      "severity": "error",
      "category": "accessibility",
      "selector": ".button-secondary",
      "message": "Color contrast ratio 3.2:1 below 4.5:1 minimum",
      "acknowledged": false,
      "acknowledged_by": null,
      "acknowledged_at": null,
      "reason": null
    }
  ],
  "summary": {
    "total_issues": 15,
    "errors": 3,
    "warnings": 8,
    "info": 4
  }
}

Issue Fingerprints

Each issue has a stable fingerprint hash based on:

  • Rule ID
  • Element selector
  • Issue message

This allows matching issues across audits even when line numbers or positions change.

Workflow

Initial Setup

  1. Run an audit to see current state:
$vertaa audit -u https://example.com
  1. Create a baseline capturing current issues:
$vertaa baseline -u https://example.com -o baseline.json
  1. Commit the baseline to version control:
git add baseline.json
git commit -m "Add UX audit baseline"

CI/CD Usage

Use the baseline in your CI pipeline to catch regressions:

Fail if any new errors introduced
$vertaa audit -u $PREVIEW_URL --baseline baseline.json --max-new-errors 0

Updating the Baseline

After fixing issues, update the baseline:

$vertaa baseline -u https://example.com --update baseline.json

Baseline Hygiene

Update your baseline periodically (e.g., after each release) to capture improvements. A stale baseline means new issues might be hidden among the "known" ones.

Acknowledging Issues

Mark issues as intentionally accepted:

{
  "fingerprint": "a1b2c3d4e5f6",
  "rule": "color-contrast",
  "acknowledged": true,
  "acknowledged_by": "designer@example.com",
  "acknowledged_at": "2026-01-15T10:30:00Z",
  "reason": "Brand colors approved by accessibility team"
}

Acknowledged issues are excluded from regression checks.

Exit Codes

CodeMeaning
0Baseline created/updated successfully
1Failed to create baseline (audit failed)
2Error writing baseline file

Examples

Create Baseline for Multiple Routes

Baseline specific routes
$vertaa baseline -u https://example.com --routes /,/about,/pricing -o baseline.json

Deep Analysis Baseline

Create baseline with deep audit
$vertaa baseline -u https://example.com --mode deep -o baseline.json

Merge with Existing Baseline

Add new page to existing baseline
$vertaa baseline -u https://example.com/new-page --merge baseline.json

Best Practices

Baseline Best Practices

  1. Commit baselines to version control - Track changes over time
  2. Use consistent audit modes - Don't create baseline with basic and audit with deep
  3. Review baseline updates - Don't blindly accept new issues
  4. Set up automated baseline updates - After releases or on schedule
  5. Document acknowledged issues - Future maintainers need context

diff

Compare two audit results directly

audit

Run audits with baseline comparison

policy

Configure quality gates with policies

CI/CD Integration

Automate baseline comparisons

Was this page helpful?

audit

Run UX and accessibility audits from the command line

diff

Compare two audit results to see changes over time

On this page

vertaa baselineSynopsisDescriptionWhy Use Baselines?Quick ExamplesOptionsBaseline File FormatIssue FingerprintsWorkflowInitial SetupCI/CD UsageUpdating the BaselineAcknowledging IssuesExit CodesExamplesCreate Baseline for Multiple RoutesDeep Analysis BaselineMerge with Existing BaselineBest PracticesRelated