Skip to content
Zen Reporter

Installation & Quick Start Guide

This guide walks you through installing Zen Reporter, integrating it with your Playwright test configuration, running your test suite, and viewing the generated interactive reports.

📥 Prerequisites

Section titled “📥 Prerequisites”
  • Node.js: Version 18.0.0 or higher
  • Playwright: @playwright/test version >=1.63.0 (may work with slightly older Playwright versions, but upgrading your Playwright version is recommended)
  • Optional peer dependency: @duckdb/node-api (version 1.5.5-r.5) for local CLI historical intelligence commands.

🛠️ Step 1: Installation

Section titled “🛠️ Step 1: Installation”

Install zen-reporter using your preferred Node package manager:

bash npm install --save-dev @arpanp/zen-reporter

(Optional) Install DuckDB Peer Dependency for History Intelligence

Section titled “(Optional) Install DuckDB Peer Dependency for History Intelligence”

If you plan to use historical trend analysis, test regression tracking, or DuckDB CLI queries (npx zr history), install @duckdb/node-api:

bash npm install --save-dev @duckdb/node-api

⚙️ Step 2: Configure Playwright

Section titled “⚙️ Step 2: Configure Playwright”

Add @arpanp/zen-reporter to your Playwright configuration file (playwright.config.ts or playwright.config.js).

Basic Setup (Default Options)

Section titled “Basic Setup (Default Options)”
import { defineConfig } from "@playwright/test";


export default defineConfig({
  reporter: "@arpanp/zen-reporter",
});
Section titled “Recommended Production Setup”

Use Playwright’s tuple array syntax to supply reporter options:

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


export default defineConfig({
  reporter: [
    [
      "@arpanp/zen-reporter",
      {
        outputDir: "zen-report",
        projectName: "E2E Web Suite",
        testRunName: "Build #{N}",
        theme: "Cafe",
        darkMode: false,
        singleSummaryFile: true,
        enableHistory: "auto",
        consoleProgress: "auto",
      },
    ],
  ],
});

🚀 Step 3: Run Your Tests

Section titled “🚀 Step 3: Run Your Tests”

Run your Playwright tests using your preferred package manager:

bash npx playwright test

During execution, zen-reporter output depends on your terminal interactive state:

  • Interactive TTY Terminals: Displays a live dynamic single-line progress bar showing active workers, completed tests, pass/fail counts, and current test title.
  • Non-TTY / CI Environments: Outputs clean dot progress (. for pass, F for fail, s for skip, ± for flaky).
  • Completion Summary: Prints an ANSI-formatted terminal summary table upon execution completion.

🌐 Step 4: Open & View the Report

Section titled “🌐 Step 4: Open & View the Report”

Once test execution completes, the HTML report will be generated at <outputDir>/index.html (default: zen-report/index.html).

Method 1: Using the Built-in zr CLI Tool

Section titled “Method 1: Using the Built-in zr CLI Tool”

Zen Reporter provides a built-in CLI command zr (or zen-reporter) to launch a local server and open the report in your default browser:

Terminal window
npx zr show

Method 2: Opening Directly in Browser

Section titled “Method 2: Opening Directly in Browser”

Because index.html is completely standalone with zero external network requests, you can double-click or open zen-report/index.html directly in any web browser or view it served over any static file host.

🔄 Next Steps

Section titled “🔄 Next Steps”