@sentinelqa/playwright-reporter 0.1.53 → 0.1.54

package/README.md

@@ -1,92 +1,53 @@
 # Playwright Reporter
 
-After every failed run, reporter prints a shareable debugging link:
+After every failed Playwright run, Sentinel gives you:
 
-Sample run: https://app.sentinelqa.com/share/1f343d91-be17-4c14-b1b9-2d4e8ef448d2
+- a clear CLI diagnosis
+- a shareable debugging link
+- grouped failures by likely root cause
 
-Open it to inspect failures instantly or share it in Slack, PRs, or GitHub issues.
+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 → root cause in seconds.
-Get a shareable Playwright debugging link with traces, screenshots, and failure context — no setup required.
+From failed CI run to root cause in seconds.
 
-Works with no account or API key required.
-
-Use it to get a shareable hosted run link from CI or local development, then upgrade to Sentinel Cloud for richer history and intelligence.
+Works with no account and no API key.
 
 ![Sentinel Report Example](./docs/screenshot2.png)
-![CLI Quick Diagnosis](./docs/CLI1.png)
-
-## Features
-
-- Free hosted debugging links by default, with no account or API key required
-- Public run page that opens on unified failures across the run
-- Within-run failure grouping so repeated failures collapse into one issue
-- Public failure pages with screenshots, evidence, parsed errors and light summaries
-- Copyable share actions for Slack, PRs, and debugging handoff
-- Deterministic quick diagnosis in the terminal after failed runs
-- Playwright traces, screenshots, videos and logs uploaded automatically
-- 48-hour public share links on the free hosted flow
-- Works with existing Playwright reporter setup
-- Optional live failure capture for richer Sentinel Cloud analysis
-- CI run history, retention, and deeper AI debugging in Sentinel Cloud
-
-## Why this exists
-
-Debugging Playwright failures usually means downloading traces, screenshots, and logs separately from CI.
-
-Reporter uploads those artifacts into a single hosted Sentinel run page so you can open one link, inspect failures fast, and share that link with the rest of the team.
-
-## CLI diagnosis
-
-Sentinel is not just a report link.
-
-On failed runs, it prints a compact terminal diagnosis that answers:
+![CLI Quick Diagnosis](./docs/CLI2.png)
 
-1. what broke
-2. why it broke
-3. where to look
-4. what changed
-5. what to do next
+## What It Does
 
-The goal is simple:
+Sentinel explains Playwright failures locally, groups them into real root causes, and gives you a shareable link to inspect the run.
 
-you should not need to open logs first.
+The open-source reporter is focused on one job:
 
-Typical CLI output:
+- tell you what broke
+- show why it failed
+- point to the likely root cause
+- tell you what to check next
 
-```text
-Sentinel diagnosis
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-NEW FAILURE after 8 passing runs
-
-What broke: 10 tests failed
-Why: collapsed into 2 real issues
-
-Issue 1: UI assertion mismatch (6 tests)
-  Why: getByTestId('metric-pass-rate') showed "82%" instead of "88%"
-  Where: app.spec.ts:43, app.spec.ts:69
-  Expected: 88%
-  Received: 82%
-  What changed: "update analytics cards"
-  Next: verify getByTestId('metric-pass-rate')
-  Impact: 6 tests failing with same root cause
-  Clears: fixing this likely clears 6 of 10 failures
-```
+## Features
 
-On passed runs, Sentinel stays short and only prints a warning if there is a strong risk signal worth caring about.
+- 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 the free version
+## Why Teams Use It
 
-- Drop one wrapper into `playwright.config.ts` and keep running `npx playwright test`
-- Get a hosted Sentinel debugging link automatically on failed runs
-- Share one public URL in Slack, PRs, or GitHub issues instead of passing around raw CI artifacts
-- See unified failures, grouped failure patterns, screenshots, and evidence in one place
-- Let teammates inspect the failure without needing your CI system or local machine
+- 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
 
@@ -95,14 +56,6 @@ On passed runs, Sentinel stays short and only prints a warning if there is a str
 
 ## Quick Start
 
-`withSentinel()` is the default setup for everyone:
-
-- best for free and local users
-- zero-friction setup
-- hosted Sentinel report link is generated automatically
-- no `SENTINEL_TOKEN` required
-- AI summaries use trace and reporter evidence, but are less precise than live page capture
-
 Install:
 
 ```bash
@@ -131,80 +84,91 @@ export default withSentinel(
 );
 ```
 
-## Example
-
-Run your Playwright tests:
+Run your tests:
 
 ```bash
 npx playwright test
 ```
 
-If tests fail, Sentinel uploads a hosted debugging report and prints the shareable link in the terminal.
+If tests fail, Sentinel uploads the run and prints a shareable link in the terminal.
 
-Open the hosted report to inspect:
+## CLI Output
 
-- failed tests across jobs
-- within-run grouped failures
-- screenshots and videos
-- trace links
-- parsed failure details
-- light summaries
-- shareable public debugging page
+On failed runs, Sentinel prints a compact diagnosis that answers:
 
-The free hosted public flow is designed for distribution:
+1. What failed?
+2. What caused it?
+3. Where is it?
+4. What should I check next?
 
-- one shareable debugging link per run
-- public read-only pages
-- fast enough to use in CI comments and Slack threads
-- clear upgrade path into a full Sentinel workspace when teams want history, retention, and deeper analysis
+Typical output:
 
-## Modes
+```text
+Sentinel diagnosis
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
-### Free hosted mode
+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
+```
 
-If `SENTINEL_TOKEN` is not set, the reporter uploads the run to a hosted public Sentinel report and prints the shareable URL.
+On passed runs, Sentinel stays quiet unless there is a strong risk signal worth surfacing.
 
-This free public flow includes:
+## What The Shared Report Shows
 
-- hosted run page
-- hosted failure pages
-- grouped failures inside the run
-- light summaries
-- copy/share actions
-- 48-hour share links
+The hosted report is simple on purpose.
 
-### Workspace mode
+It focuses on:
 
-If `SENTINEL_TOKEN` is set, the reporter uploads into your Sentinel workspace instead of the free hosted public flow.
+- grouped failures
+- explanation of why each issue failed
+- affected tests
+- artifacts
+- recent history
 
-```bash
-SENTINEL_TOKEN=your_project_ingest_token npx playwright test
-```
+Open the link to inspect:
 
-For local runs outside CI, Sentinel will use your local git metadata automatically when available.
+- 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
 
-## What `withSentinel()` does
+## Free Hosted Mode
 
-- 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 hosted Sentinel at the end of the test run
+If `SENTINEL_TOKEN` is not set, the reporter uploads the run to a free hosted Sentinel report and prints the public share URL.
 
-## Recommended Cloud Setup
+This free flow includes:
 
-If you use Sentinel Cloud and want the best AI summaries and fix suggestions, keep `withSentinel()` in your Playwright config and add the live capture fixture.
+- CLI diagnosis
+- hosted run page
+- grouped failures
+- failure explanation
+- public share links
 
-Why:
+## Optional Richer Capture
 
-- `withSentinel()` alone works from reporter and trace data
-- a Playwright reporter does not get the live `page` fixture
-- the live capture fixture lets Sentinel collect richer DOM and code context at the exact failure moment
-- this is required for the highest-quality DOM-aware patches
+`withSentinel()` works on its own and is the simplest setup.
 
-Create one shared test wrapper:
+If you want richer failure evidence, you can also attach the failure capture fixture:
 
 ```ts
 // tests/test.ts
@@ -215,20 +179,28 @@ export const test = attachSentinelFailureCapture(base);
 export { expect };
 ```
 
-Then import from that file in your specs instead of `@playwright/test`:
+Then import from that file in your specs:
 
 ```ts
 import { test, expect } from "./test";
 ```
 
-Use this cloud setup when you want:
+This improves the quality of:
+
+- blocked action diagnosis
+- assertion mismatch diagnosis
+- timeout explanations
+- DOM and state evidence in the report
 
-- best AI summaries
-- best fix suggestions
-- richer DOM-aware diagnosis
-- more reliable code patches grounded in real page state
+## What `withSentinel()` Does
 
-Free and local-only users do not need this. The standard `withSentinel()` setup remains the simplest path and will upload a hosted Sentinel report automatically.
+- 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
 
@@ -243,19 +215,12 @@ withSentinel(config, {
 });
 ```
 
-## Sentinel Cloud (optional)
+## Workspace
 
-Sentinel Cloud adds:
+If you want private run history, recurring issue tracking, and team access, sign up for a Sentinel workspace and set `SENTINEL_TOKEN`.
 
-- hosted debugging dashboards
-- CI run history
-- AI-generated failure summaries
-- flaky test detection
-- shareable run links
-- longer retention
-- compare against previous runs
-- recurring failure history
-- richer fix suggestions and team workflows
+```bash
+SENTINEL_TOKEN=your_project_ingest_token npx playwright test
+```
 
-Free for up to 100 CI runs per month.
-Create an account at [sentinelqa.com](https://sentinelqa.com).
+Create a workspace at [sentinelqa.com/register](https://sentinelqa.com/register).