playwright-spec-doc-reporter.

Default Playwright reporters show pass/fail counts. That's it. When a test fails in CI, you get a stack trace and maybe a screenshot — then you spend the next 30 minutes reconstructing what the test was actually doing and why it might have broken.

Meanwhile, BDD documentation (if it exists at all) lives in a separate tool, disconnected from actual test execution. The gap between "what we say we test" and "what actually ran" widens every sprint.

playwright-spec-doc-reporter closes that gap. One reporter. One self-contained HTML file. Everything in one place.

npm install -D playwright-spec-doc-reporter

Because Playwright reporters are loaded in a separate worker context, create a thin reporter.mjs shim in your project root:

export { default } from 'playwright-spec-doc-reporter/reporter';

Then reference it in playwright.config.ts:

import { defineConfig } from '@playwright/test';

export default defineConfig({
  reporter: [
    ['./reporter.mjs', {
      outputFolder: './test-results',
      theme: 'dark-glossy',       // 'dark-glossy' | 'dark' | 'light'
      aiAnalysis: true,
      aiProvider: 'anthropic',    // 'anthropic' | 'openai' | 'azure' | custom
      jiraIntegration: false,
      prComment: false
    }]
  ]
});

Add structured metadata to any test using annotation helpers from the package. The reporter extracts these at runtime and renders them as navigable BDD documentation alongside execution results.

import { test } from '@playwright/test';
import { feature, scenario, behaviour } from 'playwright-spec-doc-reporter/annotations';

test('user can complete checkout', async ({ page }) => {
  feature('Checkout Flow');
  scenario('Complete purchase with credit card');
  behaviour('Given the user has items in their cart');
  behaviour('When they proceed to checkout and submit payment');
  behaviour('Then an order confirmation is displayed');

  await page.goto('/cart');
  // ... test steps
});

When a test fails, instead of just seeing TimeoutError: locator.click() timed out, the dashboard surfaces a structured explanation:

"The checkout button wasn't clickable because a promotional modal appeared and blocked the element. This is likely a race condition — the modal loads asynchronously after page navigation but before the click action executes. Consider waiting for the modal to dismiss or handling it in test setup."

Analysis runs against Claude (Anthropic), GPT-4 (OpenAI), Azure OpenAI, or any custom provider endpoint you configure. Context sent to the model includes the error message, test code, BDD annotations, and any attached screenshots.