@muuktest/failure-capture

Automatic test failure capture for Playwright - captures DOM state, screenshots, and error details when tests fail.

Installation

npm install @muuktest/failure-capture

Quick Setup

Run the setup wizard:

npx failure-capture init

The wizard will:

1. Detect if you have existing Playwright fixtures
2. Either modify your fixtures or create a new one
3. Update your test imports automatically
4. Create an MD file to to instruct the agent

CLI Options

npx failure-capture init [options]

Options

| Option | Short | Description | Default | |--------|-------|-------------|---------| | --fixture-path <path> | -f | Path for the fixture file | tests/fixtures.ts | | --output-dir <path> | -o | Directory for failure output files | test-results/dom-failures | | --help | -h | Show help message | |

Examples

# Use defaults
npx failure-capture init

# Custom fixture location
npx failure-capture init --fixture-path src/e2e/fixtures.ts
npx failure-capture init -f lib/test-base.ts

# Custom output directory for failure files
npx failure-capture init --output-dir ./my-failures
npx failure-capture init -o ./reports/failures

# Both options
npx failure-capture init -f e2e/base.ts -o ./test-output/failures

# JavaScript project
npx failure-capture init --fixture-path tests/fixtures.js

Environment Variables

You can also configure the tool using environment variables:

| Variable | Description | Used At | |----------|-------------|---------| | MUUKTEST_FIXTURE_PATH | Path for the fixture file | Setup time (CLI) | | MUUKTEST_OUTPUT_DIR | Directory for failure output files | Setup time & Runtime |

Examples

# Set fixture path via env var
MUUKTEST_FIXTURE_PATH=src/fixtures.ts npx failure-capture init

# Set output directory via env var
MUUKTEST_OUTPUT_DIR=./failures npx failure-capture init

# Runtime: override output directory when running tests
MUUKTEST_OUTPUT_DIR=./ci-failures npx playwright test

Manual Setup

If you prefer to set up manually instead of using the CLI:

Option 1: Create a fixtures file (Recommended)

Create a file like tests/fixtures.ts:

import { test as base, expect } from '@playwright/test';
import { setupFailureCapture } from '@muuktest/failure-capture/global';

export const test = base.extend({});
export { expect };

// Basic setup
setupFailureCapture(test);

// Or with custom output directory
setupFailureCapture(test, { outputDir: './my-failures' });

Then update your test files to import from your fixtures:

// Before
import { test, expect } from '@playwright/test';

// After
import { test, expect } from './fixtures';

Option 2: Add to existing fixtures

If you already have a fixtures file, add these lines:

import { setupFailureCapture } from '@muuktest/failure-capture/global';

// After your test definition
setupFailureCapture(test);

// Or with options
setupFailureCapture(test, { outputDir: './my-failures' });

Output Files

When a test fails, the following files are generated in the output directory:

| File | Description | |------|-------------| | dom_elements.json | DOM tree with interactive and reference elements | | failure_screenshot.png | Screenshot at the moment of failure | | failure_info.json | Error details, selector, action, and location |

Example failure_info.json

{
  "selector": "button[type='submit']",
  "action": "click",
  "error": "Timeout waiting for element to be visible",
  "location": "login.spec.ts:42",
  "context": "Full error message..."
}

Example dom_elements.json

{
  "metadata": {
    "timestamp": "2024-01-15T10:30:00.000Z",
    "url": "https://example.com/login",
    "total_elements": 45,
    "interactive_elements": 12,
    "reference_elements": 33,
    "screenshot": "failure_screenshot.png"
  },
  "elements": [
    {
      "tag": "button",
      "attributes": { "type": "submit", "class": "btn-primary" },
      "content": "Sign In",
      "selector": "button[type='submit']",
      "coords": { "x": 100, "y": 200, "width": 80, "height": 40 },
      "is_interactive": true,
      "is_reference": false
    }
  ]
}

Development

Testing Changes Locally

To test your changes locally in another project before publishing:

1. Build the package:

   npm run build

2. Create a global link:

   npm link

3. In your test project, link to your local package:

   npm link @muuktest/failure-capture

4. Make changes and rebuild:

   # After making changes to the source code
   npm run build

   Your linked project will automatically use the updated code.

5. Unlink when done testing:

   # In your test project
   npm unlink @muuktest/failure-capture
   
   # In the package directory (optional cleanup)
   npm unlink

Publishing to npm

1. Update the version:

   # Patch version (1.0.0 -> 1.0.1)
   npm version patch
   
   # Minor version (1.0.0 -> 1.1.0)
   npm version minor
   
   # Major version (1.0.0 -> 2.0.0)
   npm version major

2. Publish to npm:

   npm publish --access public

   The prepublishOnly script will automatically build the package before publishing.

3. Push the version tag to git:

   git push && git push --tags

License

MIT