@yofix/browser
Advanced tools
Intelligent browser automation for visual regression testing of route changes
Intelligent browser automation for visual regression testing of route changes. Powered by Playwright and Claude AI.
npm install @yofix/browser
Or use directly with npx:
npx @yofix/browser capture --help
route-impact-browser capture \
--codebase ./my-app \
--base-url https://example.com \
--routes / /about /pricing \
--viewports "1920x1080:desktop,768x1024:tablet,375x667:mobile"
route-impact-browser capture \
--codebase ./my-app \
--base-url https://preview.example.com \
--routes /dashboard /settings \
--enable-auth \
--auth-email user@example.com \
--auth-password "password" \
--llm-api-key sk-ant-api03-... \
--viewports "1920x1080:desktop"
import { captureRouteScreenshots } from '@yofix/browser'
const result = await captureRouteScreenshots({
codebase: { path: './my-app' },
routes: ['/dashboard', '/settings'],
baseUrl: 'https://preview.example.com',
loginUrl: '/login/password', // Optional: custom login URL (default: '/login')
credentials: {
email: 'user@example.com',
password: 'password'
},
options: {
viewports: [
{ width: 1920, height: 1080, name: 'desktop' }
],
llm: {
provider: 'anthropic',
apiKey: process.env.CLAUDE_API_KEY, // or CLAUDE_API_KEY
model: 'claude-sonnet-4-5-20250929'
},
auth: {
enabled: true,
forceRefresh: false, // Use cached login config
skipLoginIfAuthenticated: true, // Skip if already logged in
cache: {
enabled: true,
ttl: 30 * 24 * 60 * 60 * 1000 // 30 days
}
},
browser: {
headless: true,
timeout: 30000,
waitUntil: 'networkidle' // 'load' | 'domcontentloaded' | 'networkidle'
},
storage: {
provider: 'local', // 'local' | 'github-actions-artifact'
artifactName: 'screenshots' // For GitHub Actions
},
verbose: false
}
})
console.log(`Captured ${result.metadata.totalScreenshots} screenshots`)
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 }}'
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 (or use AUTH_EMAIL env var)--auth-password <password> - Authentication password (or use AUTH_PASSWORD env var)--llm-api-key <key> - Claude API key for login detection (or use CLAUDE_API_KEY env var)--llm-model <model> - Claude model to use (default: claude-sonnet-4-5-20250929)--force-refresh-login - Force re-detection of login flow (ignore cache)--skip-login-if-authenticated - Skip login if already authenticatedBrowser 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 nameOther Options:
--verbose - Verbose output# Clear cached login flow
route-impact-browser clear-cache --codebase ./my-app
# View cache statistics
route-impact-browser cache-stats --codebase ./my-app
On the first run with authentication enabled, the tool:
loginUrl if provided)Example detected config:
{
"loginUrl": "/login",
"selectors": {
"emailInput": "input[type='email']",
"passwordInput": "input[type='password']",
"submitButton": "button[type='submit']",
"successIndicator": "[data-testid='user-menu']"
},
"waitConditions": {
"waitForNavigation": true,
"waitForSelector": "[data-testid='user-menu']",
"timeout": 30000
},
"confidence": "high",
"framework": "NextAuth.js",
"reasoning": "Detected NextAuth.js patterns in codebase..."
}
For each route:
load, domcontentloaded, or networkidle){output-dir}/{route-slug}/{viewport-name}.pngLocal: Screenshots saved to directory (default: screenshots-{datetime})
GitHub Actions: Uploaded as artifacts (available for 90 days)
WIDTHxHEIGHT[:NAME[:SCALE]]
# 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"
viewports: [
{ width: 1920, height: 1080, name: 'desktop' },
{ width: 768, height: 1024, name: 'tablet', deviceScaleFactor: 2 },
{ width: 375, height: 667, name: 'mobile', deviceScaleFactor: 3 }
]
The following environment variables can be used as alternatives to CLI options:
AUTH_EMAIL - Authentication email (alternative to --auth-email)AUTH_PASSWORD - Authentication password (alternative to --auth-password)CLAUDE_API_KEY or CLAUDE_API_KEY - Claude API key (alternative to --llm-api-key)GITHUB_ACTIONS - Auto-detected when running in GitHub Actions (enables artifact upload)screenshots-20240115_120530/
├── dashboard/
│ ├── desktop.png
│ ├── tablet.png
│ └── mobile.png
├── settings/
│ ├── desktop.png
│ ├── tablet.png
│ └── mobile.png
└── guard-trends/
└── desktop.png
{
success: boolean
metadata: {
timestamp: number
totalRoutes: number
totalScreenshots: number
successfulRoutes: number
failedRoutes: number
outputDirectory: string
authUsed: boolean
loginFlowDetected: boolean
totalDuration: number
baseUrl: string
}
screenshots: [
{
route: string
fullUrl: string
screenshots: [
{
viewport: string
path: string
destination: string
width: number
height: number
size: number
duration: number
contentType: string
metadata: {
route: string
fullUrl: string
viewport: string
width: string
height: string
}
}
]
timing: {
navigationTime: number
screenshotTime: number
totalTime: number
}
success: boolean
error?: string
}
]
errors?: [
{
code: string
message: string
route?: string
phase?: 'login' | 'navigation' | 'screenshot' | 'storage'
details?: unknown
}
]
artifactInfo?: {
uploaded: boolean
artifactName: string
artifactId?: number
size: number
}
}
--force-refresh-login to re-detect--timeout 60000--no-headlessroute-impact-browser clear-cache --codebase ./my-app--force-refresh-login to regenerateroute-impact-browser cache-stats --codebase ./my-appMIT
FAQs
Intelligent browser automation for visual regression testing of route changes
We found that @yofix/browser demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
/Security News
Impostor NuGet package Tracer.Fody.NLog typosquats Tracer.Fody and its author, using homoglyph tricks, and exfiltrates Stratis wallet JSON/passwords to a Russian IP address.
Security News
Deno 2.6 introduces deno audit with a new --socket flag that plugs directly into Socket to bring supply chain security checks into the Deno CLI.
Security News
New DoS and source code exposure bugs in React Server Components and Next.js: what’s affected and how to update safely.