Playwright Insight Reporter

A production-ready, extensible HTML reporting system for Playwright Test. Generates beautiful, interactive HTML reports with trend analysis, error clustering, and multi-browser support.

Features

• 📊 Interactive HTML Reports - Real-time test summaries, pass rates, and metrics
• 📈 Trend Analysis - Track test performance over time with historical data
• 🔍 Error Clustering - Group similar failures for faster debugging
• 🎨 Theme Support - Light/Dark/Auto modes with responsive design
• 📱 Mobile-Friendly - Works seamlessly on all devices
• 🎭 Multi-Browser - Full support for Chromium, Firefox, WebKit
• 📎 Attachments - Embed screenshots, videos, and custom logs
• ✅ Type-Safe - Full TypeScript support with type definitions

Installation

As an NPM Package (from local path)

npm install ./path/to/playwright-insight-reporter

Or with a relative path from your project root:

npm install ../playwright-insight-reporter

From GitHub (future releases)

npm install your-username/playwright-insight-reporter

Quick Start

1. Update playwright.config.ts

Add the reporter to your Playwright configuration:

import { defineConfig, devices } from '@playwright/test';
import InsightReporter from 'playwright-insight-reporter';

export default defineConfig({
  testDir: './tests',
  
  // Configure the reporter
  reporter: [
    ['html'], // Default Playwright HTML reporter (optional)
    [
      InsightReporter,
      {
        outputDir: './reports/custom-report',
        historyDir: './reports/history',
        outputFile: 'index.html',
        title: 'My Test Report',
        showTrends: true,
        maxHistoryEntries: 10,
        theme: 'auto', // 'light', 'dark', or 'auto'
        embedAttachments: true,
        open: 'never', // 'never', 'on-failure', or 'always'
      },
    ],
  ],

  use: {
    baseURL: 'http://localhost:3000',
  },

  projects: [
    {
      name: 'chromium',
      use: { ...devices['Desktop Chrome'] },
    },
    {
      name: 'firefox',
      use: { ...devices['Desktop Firefox'] },
    },
    {
      name: 'webkit',
      use: { ...devices['Desktop Safari'] },
    },
  ],
});

2. Run Tests

npx playwright test

The reporter will automatically generate an interactive HTML report in ./reports/custom-report/index.html.

Configuration Options

interface CustomReporterOptions {
  // Output directory for the HTML report
  outputDir?: string;                // default: './reports/custom-report'

  // Directory to store execution history
  historyDir?: string;               // default: './reports/history'

  // HTML filename
  outputFile?: string;               // default: 'index.html'

  // Report title
  title?: string;                    // default: 'Playwright Test Report'

  // Show trend charts and history
  showTrends?: boolean;              // default: true

  // Number of historical runs to keep
  maxHistoryEntries?: number;        // default: 10

  // Color theme
  theme?: 'light' | 'dark' | 'auto'; // default: 'auto'

  // Embed attachments in HTML (vs linking)
  embedAttachments?: boolean;        // default: false

  // Auto-open report after tests
  open?: 'never' | 'on-failure' | 'always'; // default: 'never'
}

Report Features

Dashboard View

• Test Summary: Total, passed, failed, skipped, and interrupted tests
• Pass Rate: Percentage and visual progress bar
• Duration: Total execution time and per-test breakdown
• Environment Info: OS, browser, Node.js, and Playwright versions

Suite Navigation

• Hierarchical suite structure
• Expandable/collapsible test groups
• Individual test details with full steps

Failure Analysis

• Error messages and stack traces
• Step-by-step execution details
• Screenshot/video attachments
• Failed vs flaky test distinction

Trend Analysis (when enabled)

• Pass rate trend over time
• Failed test count trend
• Duration trend
• Interactive charts with historical data

Search & Filter

• Search tests by name
• Filter by status (passed, failed, skipped)
• Quick navigation to failed tests

Example Configuration

Minimal Setup

reporter: [
  [InsightReporter, { title: 'My Project' }]
]

Full-Featured Setup

reporter: [
  [
    InsightReporter,
    {
      outputDir: './test-results/reports',
      historyDir: './test-results/history',
      title: 'E2E Test Report',
      showTrends: true,
      maxHistoryEntries: 30,
      theme: 'auto',
      embedAttachments: true,
      open: 'on-failure',
    },
  ],
]

CI/CD Integration

reporter: [
  [
    InsightReporter,
    {
      outputDir: process.env.CI ? './reports' : './reports/local',
      title: `Test Run - ${new Date().toISOString()}`,
      open: process.env.CI ? 'never' : 'on-failure',
    },
  ],
]

Usage with Other Reporters

You can use this reporter alongside other Playwright reporters:

reporter: [
  ['html'],                      // Default Playwright reporter
  ['json', { outputFile: 'results.json' }],
  ['junit', { outputFile: 'results.xml' }],
  [CustomHtmlReporter, { /* options */ }],
]

Generating Reports Locally

If you need to generate reports outside of Playwright's test execution:

import { ParserRegistry, HtmlBuilder } from 'playwright-insight-reporter';

const registry = new ParserRegistry();
const result = await registry.parse('./test-results/results.json');

const builder = new HtmlBuilder({
  outputDir: './reports',
  title: 'My Report',
});

await builder.generate(result);

Building the Package

npm install
npm run build

The compiled JavaScript and type definitions will be in the dist/ folder.

Development

File Structure

├── src/
│   ├── index.ts                      # Main exports
│   ├── customPlaywrightReporter.ts   # Reporter class
│   ├── types.ts                      # Type definitions
│   ├── reportGenerator.ts            # CLI entry point
│   ├── builder/
│   │   ├── htmlBuilder.ts            # HTML generation
│   │   └── trendBuilder.ts           # Trend analysis
│   ├── parser/
│   │   ├── playwrightParser.ts       # Playwright format support
│   │   └── cucumberParser.ts         # Cucumber format support
│   ├── utils/
│   │   ├── fileUtils.ts              # File operations
│   │   └── gzipUtils.ts              # Compression handling
│   └── templates/
│       ├── styles.css                # Report styling
│       └── script.js                 # Interactive features
├── dist/                             # Compiled output
├── package.json
├── tsconfig.json
└── README.md

Scripts

npm run build     # Compile TypeScript to dist/

API Reference

CustomHtmlReporter

Main reporter class implementing Playwright's Reporter interface.

import CustomHtmlReporter from 'playwright-insight-reporter';

const reporter = new CustomHtmlReporter({
  outputDir: './reports',
  title: 'My Report',
});

Utilities

import {
  CustomHtmlReporter,
  HtmlBuilder,
  TrendBuilder,
  ParserRegistry,
  PlaywrightParser,
  CucumberParser,
  // Type exports
  type CustomReporterOptions,
  type TestRunResult,
  type TestResult,
  type SuiteResult,
  // Utilities
  ensureDirectoryExists,
  readJsonFile,
  writeJsonFile,
  copyDirectory,
} from 'playwright-insight-reporter';

Publishing to NPM

1. Update Version

npm version patch   # or minor/major

2. Build

npm run build

3. Publish

npm publish

Or for scoped packages:

npm publish --access public

Troubleshooting

Report not generating

• Check that outputDir exists or can be created
• Verify file permissions
• Check console output for errors

History not tracking

• Ensure historyDir is writable
• Check that showTrends is set to true
• Verify history files aren't being deleted

Styling issues

• Clear browser cache
• Check that template files (CSS/JS) are copied to output directory
• Verify templates/ folder is included in npm package

License

MIT

Support

For issues, questions, or contributions, please refer to the project repository.

Version: 1.0.0
Maintained by: Raghav Rathi