AI Trace Plugin

AI Trace Plugin generates AI-friendly trace files for debugging with AI agents like Claude Code.

When a test fails, you need to understand what went wrong: what the page looked like, what elements were present, what errors occurred, and what led to the failure. This plugin automatically captures all that information and organizes it in a format optimized for AI analysis.

Quick Start

Enable the plugin in your codecept.conf.js:

export const config = {
  tests: './*_test.js',
  output: './output',
  helpers: {
    Playwright: {
      url: 'https://example.com',
      // Optional: Enable HAR/trace for HTTP capture
      recordHar: {
        mode: 'minimal',
        content: 'embed',
      },
      trace: 'on',
      keepTraceForPassedTests: true,
    },
  },
  plugins: {
    aiTrace: {
      enabled: true,
    },
  },
}

Run tests:

npx codeceptjs run

After test execution, trace files are created in output/trace_*/trace.md.

Artifacts Created

For each test, a trace_<sha256> directory is created with the following files:

trace.md - AI-friendly markdown file with test execution history

0000_step_name_screenshot.png - Screenshot for each step (file names include step names)

0000_step_name_page.html - Full HTML of the page at each step. Processed through a minify -> clean -> beautify pipeline so the file is multi-line indented, free of <script> / <style> / <noscript> content, free of inline style="" attributes, and free of trash class names (Tailwind utilities, framework-generated v-* / ember-*, hashed classes, scoped xl:hidden-style classes). Semantic attributes (id, aria-*, data-*, role, etc.) are preserved.

0000_step_name_aria.txt - ARIA accessibility snapshot (AI-readable structure without HTML noise; Playwright only)

0000_step_name_console.json - Browser console logs, normalized to plain { type, text } objects (Playwright ConsoleMessage instances are coerced via their .type() / .text() methods so the JSON file is genuinely useful — not full of empty objects).

When HAR or trace recording is enabled in your helper config, links to those files are also included.

Note: Artifact files are named using step names for easier identification (e.g., 0000_I_see_Product_screenshot.png instead of just 0000_screenshot.png).

Storage state: Cookies and localStorage are intentionally not captured per-step by aiTrace (they rarely change between actions, so per-step _storage.json files would be noise). Use the pageInfo plugin or the MCP snapshot() tool when you need a storage snapshot.

Trace File Format

The trace.md file contains a structured execution log with links to all artifacts:

file: /path/to/test.js
name: My test scenario
time: 3.45s
---

I am on page "https://example.com"
  > navigated to https://example.com/
  > [HTML](./0000_I_am_on_page_https_example.com_page.html)
  > [ARIA Snapshot](./0000_I_am_on_page_https_example.com_aria.txt)
  > [Screenshot](./0000_I_am_on_page_https_example.com_screenshot.png)
  > [Browser Logs](./0000_I_am_on_page_https_example.com_console.json) (7 entries)
  > HTTP: see [HAR file](../har/...) for network requests

I see "Welcome"
  > navigated to https://example.com/
  > [HTML](./0001_I_see_Welcome_page.html)
  > [ARIA Snapshot](./0001_I_see_Welcome_aria.txt)
  > [Screenshot](./0001_I_see_Welcome_screenshot.png)
  > [Browser Logs](./0001_I_see_Welcome_console.json) (0 entries)

Files are named with step descriptions for easier navigation and debugging.

Configuration

Basic Configuration

plugins: {
  aiTrace: {
    enabled: true,
  }
}

Advanced Configuration

plugins: {
  aiTrace: {
    enabled: true,

    // Artifact capture options
    captureHTML: true,          // Save HTML for each step
    captureARIA: true,          // Save ARIA snapshots
    captureBrowserLogs: true,   // Save console logs
    captureHTTP: true,          // Links to HAR/trace files
    captureDebugOutput: true,   // CodeceptJS debug messages

    // Screenshot options
    fullPageScreenshots: false, // Full page or viewport only

    // Output options
    output: './output',         // Where to save traces
    deleteSuccessful: false,    // Delete traces for passed tests

    // Step filtering
    ignoreSteps: [
      /^grab/,                  // Ignore all grab* steps
      /^wait/,                  // Ignore all wait* steps
    ],
  }
}

Configuration Options

Best Practices

Optimize for Failing Tests

Save disk space by only keeping traces for failed tests:

plugins: {
  aiTrace: {
    enabled: true,
    deleteSuccessful: true,  // Only keep failing tests
  }
}

Ignore Noise

Don't capture logs for grab and wait steps:

plugins: {
  aiTrace: {
    enabled: true,
    ignoreSteps: [/^grab/, /^wait/],
  }
}

Selective Artifact Capture

Capture only what you need to reduce file sizes:

plugins: {
  aiTrace: {
    enabled: true,
    captureHTML: false,        // Skip HTML (saves ~500KB per step)
    captureARIA: true,         // Keep ARIA (only ~16KB)
    captureBrowserLogs: false, // Skip console logs
  }
}

Enable HTTP Capture

For network debugging, enable HAR/trace in your helper:

helpers: {
  Playwright: {
    recordHar: {
      mode: 'minimal',
      content: 'embed',
    },
    trace: 'on',
    keepTraceForPassedTests: true,
  },
  plugins: {
    aiTrace: {
      enabled: true,
      captureHTTP: true,  // Links to HAR/trace files
    },
  },
}

Using with AI Agents

The trace format is optimized for AI agents like Claude Code. When debugging a failing test, just point the AI agent to the trace.md file - it will read the file and all linked artifacts automatically to analyze the failure.

Troubleshooting

No trace files created

Possible causes:

1. Plugin not enabled
2. No steps executed
3. Tests skipped

Solution:

# Check if plugin is enabled
grep -A 5 "aiTrace" codecept.conf.js

# Run with verbose output
npx codeceptjs run --verbose

ARIA snapshots missing

Possible cause: Helper doesn't support grabAriaSnapshot

Solution: Use Playwright or update to latest CodeceptJS

HAR files missing

Possible cause: HAR/trace not enabled in helper config

Solution:

helpers: {
  Playwright: {
    recordHar: { mode: 'minimal' },
    trace: 'on',
  },
}

Related

• AI Features - AI-powered testing features
• Plugins - All available plugins
• Configuration - General configuration
• Playwright Helper - Playwright-specific configuration