Skip to content
Autowright

Overview

Fixwright is an AI-powered service that automatically detects and fixes broken Playwright scripts using Claude AI. It works seamlessly with Stepwright failure cases.

Why Fixwright?

Browser automation tests break frequently. Selectors change, page layouts evolve, and timing issues occur. Fixwright automates the maintenance:

AI Analysis

Claude AI analyzes failures using screenshots, traces, and error context

Automatic Fixes

Proposes and applies code fixes automatically

Validation

Re-runs scripts to validate fixes actually work

PR Creation

Creates pull requests with detailed explanations

How It Works

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│   Stepwright    │────▶│    Fixwright    │────▶│   Pull Request  │
│  Failure Case   │     │   AI Analysis   │     │   with Fix      │
└─────────────────┘     └─────────────────┘     └─────────────────┘
        │                       │                       │
        ▼                       ▼                       ▼
   Screenshots              Claude AI              Validated
   DOM Snapshot            Agent SDK               Working Fix
   Trace Files
   Console Logs
  1. Capture - Stepwright captures failure artifacts (screenshots, traces, DOM, console logs)
  2. Analyze - Claude AI examines the failure and understands the root cause
  3. Fix - AI applies code changes to resolve the issue
  4. Validate - Re-runs the script with Stepwright to verify the fix works
  5. PR - Creates a pull request with the fix and explanation

Basic Example

import { FixingLoop, FileFailureSource } from '@autowright/fixwright';


const source = new FileFailureSource('./failure-cases');


const fixingLoop = new FixingLoop({
  ai: {
    apiKey: process.env.ANTHROPIC_API_KEY!,
    model: 'claude-sonnet-4-20250514',
    permissionMode: 'bypassPermissions',
    allowDangerouslySkipPermissions: true,
  },
  git: {
    baseBranch: 'main',
    fixBranchPrefix: 'fix/stepwright-',
  },
  github: {
    token: process.env.GITHUB_TOKEN!,
    owner: 'your-org',
    repo: 'your-repo',
  },
  validation: {
    stepwrightPath: 'npx stepwright',
    timeout: 120000,
  },
  fixing: {
    maxAttempts: 3,
    maxRetriesPerAttempt: 2,
  },
  workDir: process.cwd(),
}, source);


// Listen to events
fixingLoop.on('attempt:success', (attempt) => {
  console.log('Fix successful!', attempt.analysis?.causeType);
});


fixingLoop.on('pr:created', (prUrl) => {
  console.log('PR created:', prUrl);
});


// Process a failure case
const failureCase = JSON.parse(await fs.readFile('./failure.json', 'utf-8'));
await fixingLoop.processFailure(failureCase);

Key Features

Claude Agent SDK Integration

Fixwright uses the Claude Agent SDK for autonomous code analysis and fixing:

  • Reads source files to understand context
  • Searches codebase with grep/glob patterns
  • Applies targeted code edits
  • Validates changes compile correctly
ai: {
  apiKey: process.env.ANTHROPIC_API_KEY!,
  model: 'claude-sonnet-4-20250514',
  maxTurns: 30,
  systemPrompt: {
    type: 'preset',
    preset: 'claude_code',
    append: 'Focus on fixing Playwright selectors and timing issues.',
  },
}

Multiple Failure Sources

Process failures from different sources:

import {
  FileFailureSource,
  DatabaseFailureSource,
} from '@autowright/fixwright';


// File-based (for development)
const fileSource = new FileFailureSource('./failure-cases');


// Database (for production)
const dbSource = new DatabaseFailureSource({
  connectionString: process.env.DATABASE_URL!,
  tableName: 'stepwright_failures',
});


// Use with FixingLoop
const fixingLoop = new FixingLoop(config, fileSource);

Automatic Retry Logic

Multiple fix attempts with learning:

fixing: {
  maxAttempts: 3,          // Try up to 3 different fixes
  maxRetriesPerAttempt: 2, // Retry validation 2 times
  cooldownMs: 1000,        // Wait between attempts
}

Full Event System

Subscribe to detailed events:

// Attempt lifecycle
fixingLoop.on('attempt:start', (attempt) => ...);
fixingLoop.on('attempt:analyzing', (attempt) => ...);
fixingLoop.on('attempt:fixing', (attempt) => ...);
fixingLoop.on('attempt:validating', (attempt) => ...);
fixingLoop.on('attempt:success', (attempt) => ...);
fixingLoop.on('attempt:failed', (attempt) => ...);


// Agent activity
fixingLoop.on('agent:thinking', (text) => ...);
fixingLoop.on('agent:tool_use', (tool, input) => ...);
fixingLoop.on('agent:edit', (editInfo) => ...);


// Results
fixingLoop.on('pr:created', (prUrl) => ...);
fixingLoop.on('failure:completed', (summary) => ...);

Architecture

┌─────────────────────────────────────────────────────────────────┐
│                         Fixwright                                │
├─────────────────────────────────────────────────────────────────┤
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────────────┐  │
│  │FailureSource │  │  FixingLoop  │  │    EventEmitter      │  │
│  └──────────────┘  └──────────────┘  └──────────────────────┘  │
├─────────────────────────────────────────────────────────────────┤
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────────────┐  │
│  │  AgentFixer  │  │  GitManager  │  │     PRCreator        │  │
│  └──────────────┘  └──────────────┘  └──────────────────────┘  │
├─────────────────────────────────────────────────────────────────┤
│                   Claude Agent SDK                               │
│            (Read, Edit, Bash, Grep, Glob tools)                 │
└─────────────────────────────────────────────────────────────────┘

Requirements

  • Node.js 18.x or higher
  • Anthropic API key - For Claude AI access
  • GitHub token (optional) - For PR creation

Configuration

interface ResolvedAiFixConfig {
  // Required: Claude Agent SDK configuration
  ai: {
    apiKey: string;
    model?: string;  // Default: 'claude-sonnet-4-20250514'
    maxTurns?: number;
    permissionMode?: 'default' | 'acceptEdits' | 'bypassPermissions';
    allowDangerouslySkipPermissions?: boolean;
  };


  // Git branch configuration
  git: {
    baseBranch: string;
    fixBranchPrefix: string;
  };


  // GitHub for PR creation
  github?: {
    token: string;
    owner: string;
    repo: string;
  };


  // Validation settings (runs Stepwright)
  validation: {
    stepwrightPath: string;  // e.g., 'npx stepwright'
    timeout?: number;
  };


  // Retry settings
  fixing: {
    maxAttempts: number;
    maxRetriesPerAttempt: number;
  };


  // Working directory
  workDir: string;
}

Next Steps