Install from npm · VS Code extension · View the source on GitHub

Playwright Logbook turns every test run into a searchable, self-contained report with failure details, retry history, flaky-test tracking, project views, and CI-friendly summaries. It also gives coding agents focused evidence from a selected failure and its history, helping them investigate likely causes and evaluate proposed fixes across runs.

It works with the Playwright setup you already have. There is no hosted service, database, or account to configure.

Contents

• Why teams use it · Install · Add it to Playwright
• VS Code extension · Investigate with a coding agent
• Use it in CI · Portable CI run bundles · Terminal commands
• Reporter options · Attachments and privacy · What happens to your data? · Documentation

Why teams use it

• Find the failed test, its attempts, error, code frame, steps, and artifacts in one place.
• See flaky tests and recent run history instead of investigating one run at a time.
• Review results across projects and CI shards in a single HTML report.
• Give a coding agent a bounded investigation task with errors, retries, steps, artifact references, and prior outcomes for one test.
• Keep reports local and offline by default. Logbook does not change Playwright's exit code or upload data automatically.

Install

npm install --save-dev playwright-logbook

Logbook supports Node.js 20+ and Playwright 1.42+.

Add it to Playwright Suite

Add Logbook to your existing reporter list in playwright config:

// playwright.config.ts
import { defineConfig } from '@playwright/test';

export default defineConfig({
  reporter: [['list'], ['playwright-logbook']],
});

Run Playwright normally:

npx playwright test

Then open .logbook/report/index.html. The report is a single local HTML file and works without a server.

VS Code extension

Install Playwright Logbook for VS Code alongside the reporter. Run your tests, then open Logbook in VS Code's activity bar. Open the folder containing your Playwright configuration; the extension reads its .logbook/ history. It requires desktop VS Code 1.95+.

• Find a run or test: Filter Recent Runs by status, branch, test name, ID, project, or path. You can also filter to a spec or test from the editor. Open a run overview for counts and project breakdowns.
• Browse tests across runs: Switch the sidebar to Tests to see each folder's indexed test count and open the newest loaded execution for history and comparison.
• Share an offline snapshot: Export a run or one test as a single HTML file from the extension. Available attachments are embedded as downloadable links.
• Investigate a failure: Read the recorded error, retries, steps, logs, and available attachments. Jump to the failure location or test definition in the current checkout.
• Compare history: Select an earlier execution to see what changed, including a source diff when the recorded revisions are available locally.
• Bring CI evidence home: Fetch a recent GitHub Actions artifact or import a portable run bundle to inspect its recorded results in the same history view.

VS Code Recent Runs sidebar showing recorded tests

VS Code test failure detail with error, retries, source actions, and history

VS Code comparison of a passing and failing execution

See the extension README for setup, monorepos, custom history paths, and CI imports.

Investigate with a coding agent

Prepare a task for one recorded test execution with its errors, retries, steps, available attachment paths, and matching history:

npx playwright-logbook analyze --run latest --test <testId> --source

Review the task and submit it to your coding agent. In VS Code, select a test and choose Analyze with AI to hand an unsent task to a supported installed assistant. The agent can inspect the evidence and code, propose a fix, and use later test runs to assess it. Logbook does not edit tests, run an agent, or treat a passing retry as proof of a fix. Use debug for a compact evidence packet; see the CLI reference.

Use it in CI

Each shard writes its own record. Give all shards the same run ID and upload their shard files as CI artifacts:

LOGBOOK_RUN_ID=ci-123 npx playwright test --shard=1/4

In a follow-up job, download the shard artifacts and merge them:

npx playwright-logbook merge \
  --run-id ci-123 \
  --from all-shards \
  --fail-on-incomplete

npx playwright-logbook summary --run ci-123 --format markdown

The merge creates .logbook/report/index.html and updates local history. Persist .logbook/runs/ and .logbook/index.jsonl between CI runs to keep trends and flaky-test history.

See CI recipes for GitHub Actions, Azure DevOps, artifact retention, and Playwright blob-report workflows.

Portable CI run bundles

Export a saved run as a ZIP and import runs from other machines into existing local history. Optional file attachments include screenshots, videos, traces, and custom logs. See setup, CI recipe, and import behavior. Bundle support requires playwright-logbook 0.3.0 or newer.

Terminal commands

npx playwright-logbook history
npx playwright-logbook flaky
npx playwright-logbook summary --format markdown
npx playwright-logbook report --run latest
npx playwright-logbook debug --run latest --test <testId> --format markdown

Use --root <dir> when running the CLI outside your Playwright project. See the CLI reference for all commands and exit codes.

Reporter options

reporter: [['playwright-logbook', {
  outputDir: '.logbook',
  historyLimit: 30,
  captureDetails: true,
}]],

| Option | Default | Description | | --- | --- | --- | | outputDir | .logbook | Output directory, relative to the project root | | runId | Detected | Explicit run ID; LOGBOOK_RUN_ID can also set it | | title | None | Label shown in the report | | redact | [] | Strings or regular expressions to remove from diagnostics | | autoMerge | true | Merge automatically when the run is not sharded | | autoReport | true | Generate HTML after an automatic merge | | historyLimit | 30 | Number of runs used for trends and flaky analysis | | maxTextLength | 4000 | Maximum stored diagnostic text length | | quiet | false | Suppress the final Logbook terminal line | | captureDetails | false | Capture steps, output, and failed-test screenshots |

Attachments and privacy

Logbook stores outcomes, attempts, errors, tags, case IDs, project metadata, and relative artifact references. It does not copy trace, video, or screenshot files into run records.

Configure traces in Playwright, for example:

use: { trace: 'on-first-retry' }

If you enable captureDetails, Logbook can store sanitized steps, output tails, and bounded PNG/JPEG images from failed or flaky tests. Screenshots can contain sensitive information; text redaction cannot remove secrets visible in pixels. Review reports and debug packets before sharing them.

What happens to your data?

By default, the reporter writes history under your project's .logbook/. Logbook has no hosted retention policy and performs no automatic AI or test-management upload. CI fetches and manual ZIP imports add runs to local history. Remove .logbook/ when you no longer need it.

Documentation

• CLI reference
• CI recipes
• Record schema
• Adapter guidance
• Changelog

License

MIT