Feature map

Everything Piwi does, in one place — what each feature is, what it needs beyond a running reporter, where it lives in the dashboard, and the page that explains it. Features are grouped by the three jobs the product serves: keep the history, explain the failures, and hand back a fix — plus how you reach them from elsewhere and what an operator runs.

New here? Start with What Piwi does and Getting started; this map is the "where next" once a first run has landed.

Keep the history

CI deletes every report it makes. Piwi keeps every run, trace and report, so "has this always been flaky?" and "did my fix hold?" are answerable at all.

Feature	What it does	Needs	Where
Run history & dashboard map	Every run, trace and HTML report kept and browsable, live-updating as runs start and finish.	reporter	Home; Project → Runs
Branches & per-branch baselines	Branch as a first-class dimension: filter by it, and compare against a baseline computed per branch.	reporter	Project → filter bar
What changed in a run	Compare two runs — newly failing, newly passing, still red — against a chosen baseline.	reporter	Test run → Changes
Import past runs	Backfill history from existing Playwright JSON/blob reports so trends start with a past, not empty.	admin	Setup; ingest API
Analytics & insights	Cross-project trends — portfolio health, wasted CI time, pass-rate heatmap, browser matrix, insights feed.	reporter	Analytics
Timeline markers	Your deploys and infra changes overlaid on the trend charts, so a step change has a cause.	admin	Project → Timeline
Notifications & alerts	Email, Slack, webhook and browser channels with per-project subscriptions, digests and mute.	reporter	Settings → Notifications
Offline export	A run or execution exported as a self-contained bundle (and a Perfetto trace) that outlives retention.	reporter	Run / execution → Export
Share links	A signed, read-only link to one failure for someone without an account.	reporter	Execution → Share

Explain the failures

Group forty red tests into the three problems behind them, score the flaky ones by the CI minutes they waste, and — optionally — have an LLM explain a cluster against your real git diff.

Feature	What it does	Needs	Where
Failure evidence	One failing execution, diagnosis-first: error, clues, attempts, trace-powered views and (with fixtures) console, network and ARIA.	reporter	Test case → execution
Failure clusters & the inbox	Failures sharing an error fingerprint collapsed into one cluster, triaged once with an owner and known-issue link.	reporter	Test run → Failures; Home
Flaky tests & quarantine	Flaky detection and cost scoring, with quarantine that keeps a known-bad test running but off the merge gate.	reporter	Project → Flaky
Slow tests & wasted time	Slowest tests, timeout headroom, stale test.slow(), slow endpoints and Web Vitals — the time your suite costs.	capture fixtures	Project → Performance; Analytics
AI diagnosis	An LLM explains a cluster against your actual diff, with a suggested patch validated against your source first.	an AI key	Cluster → Diagnosis
Backend logs	Server-side warnings, errors and spans captured per test and shown next to the request that triggered them.	a backend integration	Execution → network

Hand back a fix

The point is to leave with something to do, not just something to read: a ranked replacement locator, a validated patch, an owner, and the command that verifies the work.

Feature	What it does	Needs	Where
Locator healing	When a selector breaks, ranked replacement locators captured from the last passing run, with a recommended fix.	capture fixtures	Execution → Locator fix
Fix plans, reproduce & bisect	A plan to reproduce a failure locally and bisect to the commit that introduced it.	the desktop app	Cluster / execution → Fix plan
Auto-heal PRs	A pull request opened for you with a validated locator or patch — you review and merge, Piwi never does.	an SCM token, an AI key	Settings → AI diagnosis
Pull-request feedback & re-run	A summary of the failures on the branch posted to the PR, and a re-run triggered from the dashboard.	an SCM token	Settings → Pull requests
CI merge gate	A piwi gate command that blocks a merge on new failures or flakiness, with the run URL in the CI log.	reporter	CI (piwi gate)
Test selections & impact	Run only the tests that matter — changed files, a subset, balanced shards — from the CLI or the dashboard.	reporter	Project → Selections; CLI
AI steps	Author and replay natural-language test steps an LLM turns into Playwright actions.	an AI key	Reporter config

Use it from elsewhere

Reach your results and act on them from wherever you already work.

Feature	What it does	Needs	Where
MCP server	A Model Context Protocol server that gives coding agents read access to your runs, failures and diagnoses.	reporter	MCP server (/mcp)
Agent skills	Installable skills that teach a coding agent the Piwi failure-fixing workflow end to end.	reporter	reporter CLI (piwi skills)
Desktop app	A local instance in a desktop shell — run tests, reproduce and bisect, with one-click MCP wiring.	the desktop app	Desktop app
Browser extension	Record actions, build and lint locators, and copy context for an agent, straight from the page.	the browser extension	Browser extension
Test functions catalog	The reusable helpers and page-object methods your suite calls, catalogued with their parameters.	reporter	Project → Test functions
Open in IDE	Every source path in the dashboard jumps to that file and line in VS Code or JetBrains.	reporter	any source path

Run your instance

Operate a shared, self-hosted instance for a team.

Feature	What it does	Needs	Where
Authentication & roles	Optional sign-in with roles (admin, reporter, viewer), API keys for CI, and Google/GitHub OAuth.	admin	Settings → Users
Project access	Scope who can see and act on each project, for multi-team instances.	admin	Settings → Users
Data retention & cleanup	Cap how much run history you keep, with a nightly sweep and manual bulk cleanup.	admin	Settings → Storage
Backup & restore	What to copy for a safe backup of the database and file storage, and how to restore it.	admin	operator (filesystem)