npm package: @sentinelqa/playwright-reporter
Description: Playwright reporter for CI debugging with optional Sentinel cloud dashboards
Latest version: 0.1.54

# Playwright Reporter

After every failed Playwright run, Sentinel gives you:

- a clear CLI diagnosis
- a shareable debugging link
- grouped failures by likely root cause

Sample run: https://app.sentinelqa.com/share/1f343d91-be17-4c14-b1b9-2d4e8ef448d2

[![npm](https://img.shields.io/npm/v/@sentinelqa/playwright-reporter)](https://www.npmjs.com/package/@sentinelqa/playwright-reporter)
[![downloads](https://img.shields.io/npm/dm/@sentinelqa/playwright-reporter)](https://www.npmjs.com/package/@sentinelqa/playwright-reporter)
[![license](https://img.shields.io/npm/l/@sentinelqa/playwright-reporter)](./LICENSE)

From failed CI run to root cause in seconds.

Works with no account and no API key.

![Sentinel Report Example](./docs/screenshot2.png)
![CLI Quick Diagnosis](./docs/CLI2.png)

## What It Does

Sentinel explains Playwright failures locally, groups them into real root causes, and gives you a shareable link to inspect the run.

The open-source reporter is focused on one job:

- tell you what broke
- show why it failed
- point to the likely root cause
- tell you what to check next

## Features

- Free hosted debugging links by default
- Deterministic CLI diagnosis after failed runs
- Failure grouping by likely root cause
- Shared run page with traces, screenshots, videos, and logs
- Failure pages that explain what broke, why, where, and what to do next
- Better timeout, actionability, assertion, navigation, and backend failure wording
- Public share links that are easy to paste into Slack, PRs, and issues
- Works with existing Playwright reporter setup

## Why Teams Use It

- You do not need to open raw logs first
- Repeated failures collapse into a smaller number of real issues
- The CLI explains the failure immediately in CI
- Anyone on the team can open the same shared debugging link
- The hosted report keeps the explanation, artifacts, and grouped failures in one place

## Requirements

- Node.js 18+
- `@playwright/test` 1.40+

## Quick Start

Install:

```bash
npm install -D @sentinelqa/playwright-reporter
```

Add Sentinel to your Playwright config:

```ts
import { defineConfig } from "@playwright/test";
import { withSentinel } from "@sentinelqa/playwright-reporter";

export default withSentinel(
  defineConfig({
    reporter: [["line"]],
    outputDir: "test-results",
    use: {
      trace: "retain-on-failure",
      screenshot: "only-on-failure",
      video: "retain-on-failure",
    },
  }),
  {
    project: "my-app",
  },
);
```

Run your tests:

```bash
npx playwright test
```

If tests fail, Sentinel uploads the run and prints a shareable link in the terminal.

## CLI Output

On failed runs, Sentinel prints a compact diagnosis that answers:

1. What failed?
2. What caused it?
3. Where is it?
4. What should I check next?

Typical output:

```text
Sentinel diagnosis
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

RECURRING FAILURE (12 previous runs)

❌ 4 failures (grouped)
Collapsed into 2 real issues

Issue 1: Blocked click on getByRole('button', { name: 'Save' }) (3 tests)
  Cause:        .modal-backdrop intercepted pointer events before the click completed
  Where:        checkout.spec.ts:22; billing.spec.ts:41
  Failing step: Click on getByRole('button', { name: 'Save' }) selector
  Blocker:      .modal-backdrop intercepting pointer events
  Likely fix:   dismiss or wait for .modal-backdrop to disappear before clicking Save
  Impact:       3 tests failing with same root cause

Issue 2: Assertion mismatch (getByTestId('metric-pass-rate')) (1 test)
  Cause:        getByTestId('metric-pass-rate') showed "88%" instead of "100%"
  Where:        app.spec.ts:68
  Failing step: Expect text on getByTestId('metric-pass-rate') selector
  Expected:     100%
  Received:     88%
  Likely fix:   fix the UI state or data behind getByTestId('metric-pass-rate') so it shows "100%"
  Impact:       1 test failing with this root cause
```

On passed runs, Sentinel stays quiet unless there is a strong risk signal worth surfacing.

## What The Shared Report Shows

The hosted report is simple on purpose.

It focuses on:

- grouped failures
- explanation of why each issue failed
- affected tests
- artifacts
- recent history

Open the link to inspect:

- failures grouped by likely root cause
- whether multiple failures appear related
- the best available explanation for each issue
- screenshots, traces, videos, and logs
- direct links you can share with the rest of the team

## Free Hosted Mode

If `SENTINEL_TOKEN` is not set, the reporter uploads the run to a free hosted Sentinel report and prints the public share URL.

This free flow includes:

- CLI diagnosis
- hosted run page
- grouped failures
- failure explanation
- public share links

## Optional Richer Capture

`withSentinel()` works on its own and is the simplest setup.

If you want richer failure evidence, you can also attach the failure capture fixture:

```ts
// tests/test.ts
import { test as base, expect } from "@playwright/test";
import { attachSentinelFailureCapture } from "@sentinelqa/playwright-reporter/fixtures";

export const test = attachSentinelFailureCapture(base);
export { expect };
```

Then import from that file in your specs:

```ts
import { test, expect } from "./test";
```

This improves the quality of:

- blocked action diagnosis
- assertion mismatch diagnosis
- timeout explanations
- DOM and state evidence in the report

## What `withSentinel()` Does

- Preserves your existing reporter configuration
- Injects a Playwright JSON reporter if one is missing
- Sets sensible artifact defaults:
  - trace: `retain-on-failure`
  - screenshot: `only-on-failure`
  - video: `retain-on-failure`
- Uploads the run to Sentinel at the end of the test run

## Options

```ts
withSentinel(config, {
  project: "my-app",
  playwrightJsonPath: "playwright-report/report.json",
  playwrightReportDir: "playwright-report",
  testResultsDir: "test-results",
  artifactDirs: ["tmp/extra-artifacts"],
  verbose: true,
});
```

## Workspace

If you want private run history, recurring issue tracking, and team access, sign up for a Sentinel workspace and set `SENTINEL_TOKEN`.

```bash
SENTINEL_TOKEN=your_project_ingest_token npx playwright test
```

Create a workspace at [sentinelqa.com/register](https://sentinelqa.com/register).