vertaa diff

Compare two audit results to identify new issues, resolved issues, and score changes.

Synopsis

vertaa diff [options]

Description

The diff command compares audit results to show what changed between two points in time. Use it to:

Review changes before merging a PR
Track improvements after fixes
Analyze score trends over time

Quick Examples

Compare current audit against baseline

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

Compare two saved audit files

$vertaa diff --before results-before.json --after results-after.json

Compare two live URLs

$vertaa diff --before https://main.example.com --after https://preview.example.com

Options

Parameter	Type	Required	Description
-u, --url	`string`	optional	URL to audit for comparison (used with --baseline)
--baseline	`string`	optional	Path to baseline file to compare against
--before	`string`	optional	First audit result (file path or URL)
--after	`string`	optional	Second audit result (file path or URL)
--format	`string`	optional	Output format: human, json, markdownDefault: `human`
-o, --output	`string`	optional	Write diff results to file
--mode	`string`	optional	Audit mode when auditing URLs: basic, standard, deepDefault: `basic`
--show-unchanged	`boolean`	optional	Include unchanged issues in outputDefault: `false`

Comparison Modes

Against Baseline File

Compare a live URL against a saved baseline:

Compare current state against baseline

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

Two Result Files

Compare two previously saved audit results:

Compare audits from different days

$vertaa diff --before monday.json --after friday.json

Two Live URLs

Audit and compare two URLs directly:

Compare production vs staging

$vertaa diff --before https://prod.example.com --after https://staging.example.com

Output Format

Human Readable (Default)

VertaaUX Diff Report
══════════════════════════════════════════════════════════

Score Changes
────────────────────────────────────────────────────────
Overall:       78 → 85  (+7)  ▲
UX:            82 → 88  (+6)  ▲
Accessibility: 71 → 79  (+8)  ▲
Info Arch:     80 → 85  (+5)  ▲
Performance:   79 → 80  (+1)  ▲

Issues Summary
────────────────────────────────────────────────────────
New Issues:      2
Resolved Issues: 9
Unchanged:       6

New Issues (2)
────────────────────────────────────────────────────────
[ERROR] Missing form label
        at input#email
        Rule: form-label-required

[WARN]  Image exceeds viewport on mobile
        at img.hero-banner
        Rule: responsive-images

Resolved Issues (9)
────────────────────────────────────────────────────────
[ERROR] Missing alt text on hero image ✓
[ERROR] Color contrast ratio below minimum ✓
[WARN]  No skip link for keyboard navigation ✓
... (6 more)

JSON Format

{
  "comparison": {
    "before": "baseline.json",
    "after": "https://example.com",
    "timestamp": "2026-01-15T10:30:00Z"
  },
  "scores": {
    "before": { "overall": 78, "ux": 82, "accessibility": 71 },
    "after": { "overall": 85, "ux": 88, "accessibility": 79 },
    "delta": { "overall": 7, "ux": 6, "accessibility": 8 }
  },
  "issues": {
    "new": [
      {
        "fingerprint": "x1y2z3",
        "rule": "form-label-required",
        "severity": "error",
        "message": "Missing form label"
      }
    ],
    "resolved": [
      {
        "fingerprint": "a1b2c3",
        "rule": "alt-text-required",
        "severity": "error",
        "message": "Missing alt text on hero image"
      }
    ],
    "unchanged": []
  },
  "summary": {
    "new_count": 2,
    "resolved_count": 9,
    "unchanged_count": 6,
    "improved": true
  }
}

Markdown Format

For PR comments and documentation:

Generate markdown report

$vertaa diff -u $PREVIEW_URL --baseline baseline.json --format markdown

## UX Audit Diff Report

### Score Changes

| Category | Before | After | Change |
|----------|--------|-------|--------|
| Overall | 78 | 85 | +7 |
| Accessibility | 71 | 79 | +8 |

### New Issues (2)

- **[ERROR]** Missing form label at `input#email`
- **[WARN]** Image exceeds viewport on mobile

### Resolved Issues (9)

- ~~Missing alt text on hero image~~
- ~~Color contrast ratio below minimum~~

Exit Codes

Code	Meaning
`0`	Comparison successful, improvements detected
`1`	Comparison successful, regressions detected (new issues)
`2`	Error during comparison (file not found, audit failed)

Common Workflows

PR Review Workflow

Compare preview deployment against main:

# In CI, compare PR preview against production baseline
vertaa diff \
  --before https://prod.example.com \
  --after $PREVIEW_URL \
  --format markdown \
  -o diff-report.md

Weekly Improvement Tracking

# Save this week's audit
vertaa audit -u https://example.com -o audits/week-$(date +%V).json

# Compare against last week
vertaa diff \
  --before audits/week-$(($(date +%V)-1)).json \
  --after audits/week-$(date +%V).json

A/B Comparison

Compare two variants of a page:

Compare page variants

$vertaa diff --before https://example.com/page-v1 --after https://example.com/page-v2

baseline

Create baselines for comparison

audit

Run audits with baseline comparison

CI/CD Integration

Automate diff reports in pipelines

Was this page helpful?

diff

baseline

audit

CI/CD Integration

On this page