Artifacts

Stepwright captures various artifacts during script execution for debugging and analysis. These artifacts are essential for Fixwright to analyze failures and propose fixes.

Automatic Capture on Failure

Configuration

Enable automatic artifact capture:

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

Stepwright.create('My Script')
  .config({
    screenshotOnFailure: true,  // Capture screenshot when step fails
    domOnFailure: true,         // Capture DOM when step fails
    artifactDir: './artifacts', // Output directory
    trace: { mode: 'on-failure' }, // Capture Playwright trace
  })

What Gets Captured

When a step fails, Stepwright automatically captures:

Artifact	Description	Fixwright Use
Screenshot	Full page screenshot (PNG)	Visual context for AI analysis
DOM	HTML snapshot of the page	Element structure analysis
Console logs	Browser console messages	Error detection
Trace	Playwright trace file (.zip)	Step-by-step action replay
Video	Recording of execution	Visual debugging
URL	Current page URL	Context
Title	Current page title	Context

Accessing Artifacts

Artifacts are available in the result:

const result = await script.run();

if (!result.success && result.failedStep) {
  const { artifacts } = result.failedStep;

  console.log('Screenshot:', artifacts.screenshot);
  console.log('DOM:', artifacts.dom);
  console.log('Console logs:', artifacts.console);
  console.log('Trace:', artifacts.trace);
  console.log('Video:', artifacts.video);
  console.log('URL:', artifacts.url);
  console.log('Title:', artifacts.title);
}

Trace Recording

Traces are powerful diagnostic tools that capture the complete execution history, including:

• Every action performed (clicks, fills, navigations)
• Network requests and responses
• Console logs
• DOM snapshots at each step
• Screenshots at each action

Trace Configuration

Stepwright.create('My Script')
  .config({
    trace: {
      mode: 'on-failure',  // When to record traces
      screenshots: true,   // Include screenshots in trace
      snapshots: true,     // Include DOM snapshots
      sources: true,       // Include source files
    },
  })

Trace Modes

Mode	Description	Recommended For
'off'	Never record traces	Production with high volume
'on'	Always record traces	Development, debugging
'on-failure'	Record only on failure	CI/CD, Fixwright integration
'retain-on-failure'	Keep only failed traces	Balanced storage/debugging

Trace Mode Examples

// Development - always capture traces
.config({
  trace: { mode: 'on' },
})

// CI/CD - only on failure (recommended)
.config({
  trace: { mode: 'on-failure' },
})

// Production - never
.config({
  trace: { mode: 'off' },
})

Viewing Traces

Traces can be viewed in Playwright Trace Viewer:

npx playwright show-trace trace.zip

Or upload to trace.playwright.dev.

Tip

Traces are invaluable for Fixwright. They allow the AI to see exactly what happened during script execution, making it easier to identify why a step failed.

Video Recording

Enable Video

Record video of the entire script execution:

.config({
  video: {
    mode: 'on-failure',  // When to record
    size: { width: 1280, height: 720 },
  },
})

Or use the shorthand:

.video(true)  // Always record
.video('on-failure')  // Record on failure only

Video Modes

Mode	Description
'off'	Never record video
'on'	Always record video
'on-failure'	Record only when script fails
'retain-on-failure'	Keep video only if failed

Access Video Path

const result = await script.run();

if (result.video) {
  console.log('Video saved to:', result.video);
}

Screenshots

Automatic Screenshots

Screenshots are captured automatically on failure when enabled:

.config({
  screenshotOnFailure: true,
})

Manual Screenshots

Capture screenshots at any point:

.step('Take screenshot', async (ctx) => {
  // Capture current state
  const path = await ctx.screenshot('after-login');
  console.log('Screenshot saved to:', path);
})

Screenshot names are automatically prefixed with step information:

artifacts/
├── step-001-Navigate-after-login.png
├── step-002-FillForm-form-complete.png
└── step-003-Submit-failure.png

Screenshot Options

.step('Capture', async (ctx) => {
  // Full page screenshot
  await ctx.screenshot('full-page', { fullPage: true });

  // Element screenshot
  await ctx.screenshot('button', {
    selector: 'button.submit'
  });
})

DOM Snapshots

Automatic DOM Capture

DOM is captured automatically on failure when enabled:

.config({
  domOnFailure: true,
})

Manual DOM Capture

Get the current DOM as a string:

.step('Capture DOM', async (ctx) => {
  // Get full page DOM
  const fullDom = await ctx.getDOM();

  // Get specific element DOM
  const formDom = await ctx.getDOM('#signup-form');

  console.log('Form HTML:', formDom);
})

Console Logs

Console messages are collected automatically during execution:

const result = await script.run();

if (result.consoleLogs) {
  for (const log of result.consoleLogs) {
    console.log(`[${log.type}] ${log.text}`);
  }
}

Console Log Types

• log - Regular console.log
• warning - console.warn
• error - console.error
• info - console.info

Artifact Directory Structure

Default structure:

.stepwright/artifacts/
├── run-2024-01-15T10-30-00/
│   ├── step-001-Navigate.png
│   ├── step-001-Navigate.html
│   ├── step-002-Login-failure.png
│   ├── step-002-Login-failure.html
│   ├── step-002-Login-console.log
│   ├── trace.zip
│   └── video.webm

Custom Directory

.config({
  artifactDir: './my-custom-artifacts',
})

Failure Cases

Generating Failure Cases

Failure cases bundle all artifacts for Fixwright:

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

const script = Stepwright.create('Login Test')
  .config({
    screenshotOnFailure: true,
    domOnFailure: true,
    trace: { mode: 'on-failure' },
    // Automatically generate failure case on failure
    failureCaseDir: './failure-cases',
  });

const result = await script.run();

if (!result.success) {
  console.log('Failure case generated:', result.failureCasePath);
  // -> ./failure-cases/fc-2024-01-15-abc123.json
}

Manual Failure Case Generation

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

const result = await script.run();

if (!result.success && result.failedStep) {
  const failureCase = generateFailureCase(result, {
    scriptInfo: {
      name: 'Login Test',
      path: 'scripts/login.ts',
    },
    repository: {
      url: 'https://github.com/org/repo',
      branch: 'main',
    },
  });

  // Save for Fixwright
  await fs.writeFile(
    './failure-cases/login-failure.json',
    JSON.stringify(failureCase, null, 2)
  );
}

Failure Case Structure

interface FailureCase {
  id: string;
  status: 'pending' | 'processing' | 'fixed' | 'unfixable';
  timestamp: string;
  script: {
    name: string;
    path: string;
    repository?: {
      url: string;
      branch: string;
    };
  };
  failure: {
    step: string;
    checkpoint?: string;
    error: {
      message: string;
      stack?: string;
    };
    artifacts: {
      screenshot?: string;  // Path to screenshot
      dom?: string;         // Path to DOM HTML
      console?: string;     // Path to console logs
      trace?: string;       // Path to trace.zip
      video?: string;       // Path to video
    };
    url?: string;
    title?: string;
  };
  sourceCode?: {
    content: string;
    lineNumber: number;
    context: string[];
  };
}

Complete Example with All Artifacts

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

const script = Stepwright.create('E2E Test with Full Artifacts')
  .config({
    headless: true,

    // Screenshot configuration
    screenshotOnFailure: true,

    // DOM capture
    domOnFailure: true,

    // Trace recording - captures everything
    trace: {
      mode: 'on-failure',
      screenshots: true,
      snapshots: true,
      sources: true,
    },

    // Video recording
    video: {
      mode: 'on-failure',
      size: { width: 1280, height: 720 },
    },

    // Output directories
    artifactDir: './artifacts',
    failureCaseDir: './failure-cases',
  })

  .checkpoint('Login')

  .step('Navigate', async (ctx) => {
    await ctx.page.goto('https://app.example.com/login');
  })

  .step('Fill credentials', async (ctx) => {
    await ctx.page.fill('#email', 'test@example.com');
    await ctx.page.fill('#password', 'password123');
  })

  .step('Submit', async (ctx) => {
    await ctx.page.click('button[type="submit"]');
    await ctx.page.waitForURL('**/dashboard');

    // Take a success screenshot
    await ctx.screenshot('login-success');
  })

  .endCheckpoint();

const result = await script.run();

if (result.success) {
  console.log('All steps passed!');
} else {
  console.log('Script failed at step:', result.failedStep?.name);
  console.log('Failure case:', result.failureCasePath);
  console.log('Trace file:', result.artifacts?.trace);
}

Best Practices

Always Enable Trace on Failure

// Always enable in production scripts for Fixwright
.config({
  screenshotOnFailure: true,
  domOnFailure: true,
  trace: { mode: 'on-failure' },
})

Clean Up Old Artifacts

# Add to CI cleanup
rm -rf .stepwright/artifacts

Or programmatically:

import { rm } from 'fs/promises';

await rm('.stepwright/artifacts', { recursive: true, force: true });

Include Context in Names

.step('Verify dashboard', async (ctx) => {
  // Include relevant context in screenshot names
  await ctx.screenshot(`user-${ctx.data.userId}-dashboard`);
})

Don’t Capture Sensitive Data

Caution

Screenshots and DOM may contain sensitive information. Be careful when sharing artifacts or enabling automatic capture in production.

// Clear sensitive fields before capturing
.step('Login', async (ctx) => {
  await ctx.page.fill('#password', ctx.data.password);
  // Clear password before any screenshots
  await ctx.page.fill('#password', '********');
  await ctx.screenshot('login-form');
})

Next Steps

• Reporters - Format and output results
• CLI - Run scripts from command line
• Fixwright Overview - Use artifacts with Fixwright