Skip to main content

Baselines

Baselines are the reference screenshots that Vision compares against. When you approve a change, it becomes the new baseline.

How Baselines Work

First Capture ──► Becomes Baseline


Second Capture ──► Compare to Baseline

                       ├── Match ──────► Pass

                       └── Difference ─► Approve/Reject

                                    Approve ──┴──► New Baseline

Initial Baseline

The first capture of a page automatically becomes the baseline:
# First capture creates baseline
page = BrainzLab::Vision.create_page(
  name: "Homepage",
  url: "https://example.com"
)

snapshot = page.capture
# snapshot.baseline? => true (first capture is always baseline)

Viewing Baselines

# Get current baseline for a page
baseline = BrainzLab::Vision.baseline("Homepage")

puts baseline.captured_at
puts baseline.browser
puts baseline.viewport
puts baseline.image_url

# View baseline history
baselines = BrainzLab::Vision.baseline_history("Homepage")
baselines.each do |b|
  puts "#{b.version}: #{b.captured_at} - #{b.approved_by}"
end

Updating Baselines

Approve a Comparison

When a comparison detects changes, approve to update the baseline:
comparison = BrainzLab::Vision.comparison("cmp_abc123")

if comparison.review_required?
  # After reviewing the diff...
  comparison.approve(reason: "Intentional redesign of header")
  # This snapshot becomes the new baseline
end

Manual Baseline Update

# Force a new capture as baseline
page = BrainzLab::Vision.page("Homepage")
page.update_baseline

# Or use a specific snapshot
snapshot = BrainzLab::Vision.snapshot("snap_xyz789")
snapshot.set_as_baseline

Baseline per Browser/Viewport

Separate baselines are maintained for each configuration:
# Desktop Chromium has its own baseline
BrainzLab::Vision.baseline("Homepage",
  browser: :chromium,
  viewport: :desktop
)

# Mobile WebKit has a different baseline
BrainzLab::Vision.baseline("Homepage",
  browser: :webkit,
  viewport: :mobile
)

Baseline Branches

For different environments or feature branches:
# Create baseline branch
BrainzLab::Vision.create_baseline_branch("feature-redesign")

# Capture to branch
snapshot = page.capture(branch: "feature-redesign")

# Merge branch baselines to main
BrainzLab::Vision.merge_baseline_branch("feature-redesign")

Rollback Baseline

Restore a previous baseline:
# View history
history = BrainzLab::Vision.baseline_history("Homepage")

# Rollback to specific version
BrainzLab::Vision.rollback_baseline("Homepage", version: 3)

Bulk Operations

# Update all baselines (after major redesign)
BrainzLab::Vision.update_all_baselines(
  pages: ["Homepage", "Pricing", "About"],
  reason: "Q1 2024 redesign"
)

# Reset baselines (start fresh)
BrainzLab::Vision.reset_baselines(
  pages: ["Homepage"],
  confirm: true
)

Baseline Storage

Baselines are stored in S3/MinIO:
baseline = BrainzLab::Vision.baseline("Homepage")

puts baseline.image_url      # S3 URL
puts baseline.image_size     # File size in bytes
puts baseline.dimensions     # { width: 1280, height: 720 }