Skip to content
Autowright

Overview

Stepwright is a fluent API wrapper for Playwright that makes browser automation scripts more readable, maintainable, and resilient. It works seamlessly with Fixwright for AI-powered maintenance.

Why Stepwright?

While Playwright is a powerful browser automation library, complex scripts can become difficult to read and maintain. Stepwright addresses this with:

Fluent API

Chain steps together for readable, self-documenting scripts

Checkpoints

Group related steps with automatic retry on failure

Data Management

Type-safe data passing between steps

Rich Artifacts

Automatic screenshots, traces, and DOM capture on failure

Basic Example

import { Stepwright } from '@autowright/stepwright';


const script = Stepwright.create('Login Flow')
  .config({
    headless: false,
    screenshotOnFailure: true,
    trace: { mode: 'on-failure' },
  })


  .checkpoint('Login')
    .step('Navigate to login', async (ctx) => {
      await ctx.page.goto('https://app.example.com/login');
    })
    .step('Enter credentials', async (ctx) => {
      await ctx.page.fill('#email', 'user@example.com');
      await ctx.page.fill('#password', 'password123');
    })
    .step('Submit form', async (ctx) => {
      await ctx.page.click('button[type="submit"]');
      await ctx.page.waitForURL('**/dashboard');
    })
  .endCheckpoint()


  .checkpoint('Verify Dashboard')
    .step('Check welcome message', async (ctx) => {
      const welcome = ctx.page.locator('h1');
      await expect(welcome).toContainText('Welcome');
    })
  .endCheckpoint();


const result = await script.run();
console.log('Success:', result.success);

Key Features

Fluent API

Chain methods together to build readable scripts:

Stepwright.create('My Script')
  .config({ headless: true })
  .data({ userId: '123' })
  .checkpoint('Setup')
    .step('Step 1', ...)
    .step('Step 2', ...)
  .endCheckpoint()
  .run();

Step-by-Step Execution

Each step runs sequentially with full error handling:

  • Individual timeouts and retries
  • Automatic artifact capture on failure
  • Clear error reporting with step context

Checkpoint-Based Recovery

Group related steps into checkpoints for intelligent retry:

.checkpoint('Login', { maxRetries: 2 })
  .step('Fill form', ...)
  .step('Submit', ...)
.endCheckpoint()

If any step in a checkpoint fails, the entire checkpoint retries from the beginning.

Type-Safe Data

Pass data between steps with full TypeScript support:

interface MyData {
  username: string;
  token?: string;
}


Stepwright.create<MyData>('My Script')
  .data({ username: 'testuser' })
  .step('Get token', async (ctx) => {
    ctx.data.token = await fetchToken();
  });

Trace Recording

Capture detailed execution traces for debugging and Fixwright analysis:

.config({
  trace: {
    mode: 'on-failure',  // Record only when script fails
    screenshots: true,   // Include screenshots
    snapshots: true,     // Include DOM snapshots
  },
})

Integration with Fixwright

Stepwright is designed to work seamlessly with Fixwright. When a script fails:

  1. Stepwright captures rich failure context (screenshots, traces, DOM, console logs)
  2. Generates a FailureCase JSON file
  3. Fixwright processes the failure and proposes AI-powered fixes
┌─────────────────────────────────────────────────────────────┐
│                       STEPWRIGHT                             │
│  Write scripts → Run → Capture failure context on error      │
└─────────────────────────────┬───────────────────────────────┘
                              │ FailureCase (trace, screenshot, DOM)
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                       FIXWRIGHT                              │
│  Read failures → AI analysis → Create fix → Open PR          │
└─────────────────────────────────────────────────────────────┘

Architecture

┌─────────────────────────────────────────────────────────────────┐
│                        Stepwright                                │
├─────────────────────────────────────────────────────────────────┤
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐        │
│  │  Config  │  │   Data   │  │   Steps  │  │Reporters │        │
│  └──────────┘  └──────────┘  └──────────┘  └──────────┘        │
├─────────────────────────────────────────────────────────────────┤
│                     TaskQueue (Execution)                        │
├─────────────────────────────────────────────────────────────────┤
│  ┌─────────────────┐    ┌─────────────────────────────────┐    │
│  │   Checkpoints   │    │        Background Tasks         │    │
│  └─────────────────┘    └─────────────────────────────────┘    │
├─────────────────────────────────────────────────────────────────┤
│                     Playwright (Browser)                         │
└─────────────────────────────────────────────────────────────────┘

When to Use Stepwright

Use Stepwright when:

  • Writing complex multi-step automations
  • You need checkpoint-based retry logic
  • You want automatic artifact capture
  • You’re building scripts that Fixwright will maintain

Consider vanilla Playwright when:

  • Simple one-off scripts
  • Performance-critical scenarios
  • You need maximum control

Next Steps