@yofix/browser

Route Impact Browser

Intelligent browser automation for visual regression testing of route changes. Powered by Playwright and Claude AI.

Features

• 🚀 Framework-agnostic - Works with any frontend framework
• 🔐 Smart authentication - AI-powered login flow detection
• 📱 Multi-viewport - Capture screenshots at different screen sizes
• 💾 Flexible storage - Local or GitHub Actions artifacts
• ⚡ Cache-first - Fast subsequent runs with cached login configs
• 🎯 Type-safe - Full TypeScript support
• 🔧 Dual interface - CLI + programmatic API

Installation

npm install @route-impact-analyzer/browser

Or use directly with npx:

npx @route-impact-analyzer/browser capture --help

Quick Start

Basic Usage (No Authentication)

route-impact-browser capture \
  --codebase ./my-app \
  --base-url https://example.com \
  --routes / /about /pricing \
  --viewports "1920x1080:desktop,768x1024:tablet,375x667:mobile"

With Authentication

route-impact-browser capture \
  --codebase ./my-app \
  --base-url https://preview.example.com \
  --routes /dashboard /settings \
  --enable-auth \
  --auth-email [e-mail] \
  --auth-password "password" \
  --llm-api-key sk-ant-api03-... \
  --viewports "1920x1080:desktop"

Programmatic API

import { captureRouteScreenshots } from '@route-impact-analyzer/browser'

const result = await captureRouteScreenshots({
  codebase: { path: './my-app' },
  routes: ['/dashboard', '/settings'],
  baseUrl: 'https://preview.example.com',
  credentials: {
    email: '[e-mail]',
    password: 'password'
  },
  options: {
    viewports: [
      { width: 1920, height: 1080, name: 'desktop' }
    ],
    llm: {
      provider: 'anthropic',
      apiKey: process.env.ANTHROPIC_API_KEY,
      model: 'claude-sonnet-4-5-20250929'
    },
    auth: {
      enabled: true,
      forceRefresh: false // Use cached login config
    },
    browser: {
      headless: true,
      timeout: 30000
    },
    storage: {
      provider: 'local'
    }
  }
})

console.log(`Captured ${result.metadata.totalScreenshots} screenshots`)

GitHub Actions Integration

name: Visual Regression Testing

on:
  pull_request:
    types: [opened, synchronize]

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

      - name: Capture route screenshots
        uses: ./.github/actions/screenshot-routes
        with:
          codebase-path: '.'
          base-url: ${{ needs.deploy-preview.outputs.url }}
          routes: '/,/dashboard,/settings'
          viewports: '1920x1080:desktop,768x1024:tablet'
          enable-auth: 'true'
          auth-email: ${{ secrets.TEST_EMAIL }}
          auth-password: ${{ secrets.TEST_PASSWORD }}
          claude-api-key: ${{ secrets.CLAUDE_API_KEY }}
          artifact-name: 'screenshots-${{ github.event.pull_request.number }}'

CLI Commands

Capture Screenshots

route-impact-browser capture [options]

Required Options:

• --codebase <path> - Path to codebase directory
• --base-url <url> - Base URL of the running application
• --routes <routes...> - Routes to capture (space-separated)
• --routes-file <path> - File containing routes (one per line)

Authentication Options:

• --enable-auth - Enable authentication
• --auth-email <email> - Authentication email
• --auth-password <password> - Authentication password
• --llm-api-key <key> - Claude API key for login detection
• --force-refresh-login - Force re-detection of login flow
• --skip-login-if-authenticated - Skip login if already authenticated

Browser Options:

• --viewports <viewports> - Viewport dimensions (default: "1920x1080:desktop")
• --headless / --no-headless - Run browser in headless mode
• --timeout <ms> - Navigation timeout (default: 30000)

Storage Options:

• --output-dir <path> - Output directory for screenshots
• --storage <provider> - Storage provider: local | github-actions-artifact
• --artifact-name <name> - GitHub Actions artifact name

Other Options:

• --verbose - Verbose output

Cache Management

# Clear cached login flow
route-impact-browser clear-cache --codebase ./my-app

# View cache statistics
route-impact-browser cache-stats --codebase ./my-app

How It Works

1. Login Flow Detection (First Run)

On the first run with authentication enabled, the tool:

• Analyzes your codebase structure
• Uses Claude AI to identify:
  • Login page URL
  • Email/password input selectors
  • Submit button selector
  • Success indicator (post-login element)
• Caches the configuration for 30 days

Example detected config:

{
  "loginUrl": "/login",
  "selectors": {
    "emailInput": "input[type='email']",
    "passwordInput": "input[type='password']",
    "submitButton": "button[type='submit']",
    "successIndicator": "[data-testid='user-menu']"
  },
  "confidence": "high"
}

2. Screenshot Capture

For each route:

• Navigates to the URL
• Waits for page load
• Captures screenshots at each configured viewport
• Saves with naming: {output-dir}/{route-slug}/{viewport}.png

3. Storage

Local: Screenshots saved to directory (default: screenshots-{datetime})

GitHub Actions: Uploaded as artifacts (available for 90 days)

Viewport Configuration

Format

WIDTHxHEIGHT[:NAME[:SCALE]]

Examples

# Single viewport
--viewports "1920x1080"

# With custom name
--viewports "1920x1080:desktop"

# Multiple viewports
--viewports "1920x1080:desktop,768x1024:tablet,375x667:mobile"

# With device scale factor (for retina displays)
--viewports "1920x1080:desktop:2"

Programmatic API

viewports: [
  { width: 1920, height: 1080, name: 'desktop' },
  { width: 768, height: 1024, name: 'tablet', deviceScaleFactor: 2 },
  { width: 375, height: 667, name: 'mobile', deviceScaleFactor: 3 }
]

Environment Variables

• AUTH_EMAIL - Authentication email (alternative to CLI option)
• AUTH_PASSWORD - Authentication password (alternative to CLI option)
• ANTHROPIC_API_KEY - Claude API key (alternative to CLI option)
• GITHUB_ACTIONS - Auto-detected for artifact upload

Output Structure

screenshots-20240115_120530/
├── dashboard/
│   ├── desktop.png
│   ├── tablet.png
│   └── mobile.png
├── settings/
│   ├── desktop.png
│   ├── tablet.png
│   └── mobile.png
└── guard-trends/
    └── desktop.png

Result Object

{
  success: boolean
  metadata: {
    timestamp: number
    totalRoutes: number
    totalScreenshots: number
    successfulRoutes: number
    failedRoutes: number
    outputDirectory: string
    authUsed: boolean
    loginFlowDetected: boolean
    totalDuration: number
  }
  screenshots: [
    {
      route: string
      fullUrl: string
      screenshots: [
        { viewport: string, path: string, width: number, height: number, size: number }
      ]
      timing: { navigationTime: number, screenshotTime: number, totalTime: number }
      success: boolean
      error?: string
    }
  ]
  errors?: [
    { code: string, message: string, route?: string, phase?: string }
  ]
  artifactInfo?: {
    uploaded: boolean
    artifactName: string
    artifactId?: number
    size: number
  }
}

Troubleshooting

Login Detection Fails

• Ensure Claude API key is provided
• Check that your codebase has login-related files
• Use --force-refresh-login to re-detect
• Manually verify the detected selectors work

Screenshots Fail

• Increase timeout: --timeout 60000
• Run non-headless to debug: --no-headless
• Check routes are valid and accessible
• Ensure authentication succeeded

Cache Issues

• Clear cache: route-impact-browser clear-cache --codebase ./my-app
• Use --force-refresh-login to regenerate
• Check cache stats: route-impact-browser cache-stats --codebase ./my-app

License

MIT

Related Projects

• @route-impact-analyzer/core - Analyze route impacts from file changes

browser