Skip to main content

Test Runs

Test runs capture multiple pages and compare them all to their baselines. Perfect for CI/CD integration.

Creating Test Runs

# Run all configured pages
run = BrainzLab::Vision.run_tests

# Run specific pages
run = BrainzLab::Vision.run_tests(
  pages: ["Homepage", "Pricing", "Dashboard"]
)

# Run a page group
run = BrainzLab::Vision.run_tests(group: "Marketing Pages")

Test Run Status

run = BrainzLab::Vision.test_run("run_abc123")

puts run.status          # :running, :passed, :failed, :pending_review
puts run.total_pages     # 10
puts run.passed_count    # 8
puts run.failed_count    # 1
puts run.pending_count   # 1
puts run.progress        # 100
puts run.duration        # 45.2 (seconds)

Test Run Results

run = BrainzLab::Vision.test_run("run_abc123")

run.comparisons.each do |comparison|
  puts "#{comparison.page_name}: #{comparison.status}"
  if comparison.failed?
    puts "  Diff: #{comparison.diff_percentage}%"
    puts "  Review: #{comparison.review_url}"
  end
end

CI/CD Integration

GitHub Actions

name: Visual Tests

on: [push, pull_request]

jobs:
  visual-tests:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Run Visual Tests
        run: bundle exec rake vision:test
        env:
          BRAINZLAB_SECRET_KEY: ${{ secrets.BRAINZLAB_SECRET_KEY }}
          VISION_BASE_URL: ${{ github.event.deployment_status.target_url }}

      - name: Upload Results
        if: failure()
        run: echo "Visual tests failed. Review at $VISION_RESULTS_URL"

Rake Task

# lib/tasks/vision.rake
namespace :vision do
  desc "Run visual regression tests"
  task test: :environment do
    run = BrainzLab::Vision.run_tests(
      base_url: ENV["VISION_BASE_URL"] || "http://localhost:3000"
    )

    run.wait_for_completion

    if run.failed?
      puts "Visual tests failed!"
      puts "Review at: #{run.review_url}"
      exit 1
    elsif run.pending_review?
      puts "Visual changes detected - review required"
      puts "Review at: #{run.review_url}"
      exit 2  # Special exit code for review required
    else
      puts "All visual tests passed!"
    end
  end
end

Parallel Execution

Run tests faster with parallel capture:
run = BrainzLab::Vision.run_tests(
  pages: ["Homepage", "Pricing", "Dashboard", "About"],
  parallel: 4  # Capture 4 pages simultaneously
)

Environment-Specific Tests

# Test staging before production
staging_run = BrainzLab::Vision.run_tests(
  base_url: "https://staging.example.com",
  environment: :staging
)

if staging_run.passed?
  # Promote to production testing
  prod_run = BrainzLab::Vision.run_tests(
    base_url: "https://example.com",
    environment: :production
  )
end

Scheduled Tests

# Run tests on schedule (via cron/Solid Queue)
BrainzLab::Vision.schedule_tests(
  pages: ["Homepage", "Critical Pages"],
  schedule: "0 */4 * * *",  # Every 4 hours
  notify: :slack
)

Test Run Comparison

Compare runs between deploys:
before = BrainzLab::Vision.test_run("run_before_deploy")
after = BrainzLab::Vision.test_run("run_after_deploy")

comparison = BrainzLab::Vision.compare_runs(before, after)

comparison.changes.each do |change|
  puts "#{change.page}: #{change.diff_percentage}% changed"
end

Webhooks

Receive notifications when runs complete:
BrainzLab::Vision.configure do |config|
  config.webhook_url = "https://example.com/vision-webhook"
  config.webhook_events = [:run_completed, :review_required]
end