Your Playwright results, kept and explained.
CI throws away every report it makes. Piwi keeps them — every run, trace, and HTML report — then groups the failures by root cause, scores the flaky tests, and tells you which locator to use instead of the one that just broke. Self-hosted, MIT, zero telemetry.

Live demo · Documentation · Roadmap · Discussions

_{A run streaming in live. The demo is the real app on seeded data — it runs entirely in your browser, no install and no backend.}

The problem it solves

Playwright's HTML report is excellent, and it lasts exactly until the next build. So the questions that actually matter get hard to answer: Has this test always been flaky? Did my fix work? Which of these forty red tests are the same bug? What did we change the day the suite started failing?

Piwi keeps the runs so you can answer them.

• Permanent history — every run, trace, and report, browsable long after CI deleted its artifacts.
• Failures grouped by cause — an error fingerprint collapses forty red tests into the three root causes behind them, each triaged once.
• Flaky tests, scored and costed — a composite score, a root-cause class, and the CI minutes each flake wastes, so you fix the expensive ones rather than the annoying ones.
• Locator healing — when a selector breaks, ranked replacements captured from the last passing run, with a recommended fix.
• Evidence in one place — the trace viewer, screenshots, console, network calls, Web Vitals, and the failing call stack with real source, all served by your own instance.
• AI diagnosis, if you want it — an LLM you configure explains a cluster against your actual git diff, and its suggested patch is checked against your source before you see it. Off by default.

Also in the box: cross-project analytics, live run streaming, notifications (email, Slack, webhook, browser), a REST API with in-app OpenAPI docs, and an MCP server so your coding agent can ask about test health.

Quick start

Five ways in, depending on what you already have:

Path	Start here if	What it costs
Live demo	You just want to look around first	Nothing — seeded data, runs entirely in your browser
Desktop app	You run Playwright locally and don't want to run a server	Download an installer — no Docker, no Node
Docker (below)	You have Docker, or you're setting up a shared instance	One command
npx @piwitests/server	You have Node.js 24+ and would rather skip Docker	One command
One-click deploy	You want a shared instance and no server to run it on	A button, plus whatever your host charges

Hosting templates for Railway, Render, Fly.io, Koyeb, Coolify and Dokploy live in render.yaml, fly.toml and deploy/, generated from the same variable registry as the configuration reference so they can't drift from what the app reads. Each provisions one container with a persistent volume, authentication on, and its secrets generated by the platform — the per-provider caveats (Render needs a paid instance for its disk; Koyeb attaches volumes after the fact) are in the deployment guide.

The desktop app is the shortest path from "curious" to "looking at my own test history" — it bundles the same server in a native window. Two caveats worth knowing before you download: the installers are not yet code-signed, so the first launch needs a click-through (macOS: right-click → Open; Windows: SmartScreen → More info → Run anyway), and builds exist for Windows x64 and Apple-silicon macOS only — on Linux or an Intel Mac, use Docker or npx.

The rest of this section sets up the server; the desktop app replaces step 1 only.

1. Start the dashboard

# Linux / macOS
mkdir -p .data && chown -R 1001:1001 .data # the container runs as non-root UID 1001
docker run -p 3000:3000 -v $(pwd)/.data:/app/.data phenx/piwitests-server:latest

# Windows (PowerShell)
docker run -p 3000:3000 -v ${PWD}/.data:/app/.data phenx/piwitests-server:latest

Visit http://localhost:3000. A docker-compose.yml is included, and with Node.js 24+ you can skip Docker entirely — npx @piwitests/server creates its .data/ in the current directory. There's also a desktop build (Windows .msi, macOS .dmg) that bundles the server for a single machine.

It's one Node process: ~300 MB RAM idle (1 GB comfortable), 1 vCPU, linux/amd64 or linux/arm64. Disk is the variable — traces and reports dominate, so budget roughly 50–200 MB per run and set a retention window. Your test project only needs a Node version Playwright supports; Node 24 is the dashboard's requirement.

Linux hosts: the container runs as non-root UID 1001, so without the chown above, Docker auto-creates .data owned by root and the container can't write to it. Docker Desktop on Windows and macOS handles this for you. See Troubleshooting.

Before you expose it: authentication is off by default — the command above gives you an open dashboard, which is fine on localhost and not fine on a network. Set PIWI_AUTH_ENABLED=true (guide) and set PIWI_SECRET_KEY to a long random string so stored credentials (AI keys, SCM tokens) are actually encrypted — generate one with node -e "console.log(require('node:crypto').randomBytes(32).toString('hex'))". Put it behind HTTPS; see the deployment guide. Found a vulnerability? Please report it privately via the security policy.

2. Add the reporter to your test project

npm install --save-dev @piwitests/reporter

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

export default defineConfig({
  reporter: [
    ['list'],
    ['@piwitests/reporter', {
      serverUrl: 'http://localhost:3000',
      projectName: 'my-project',
    }],
  ],
  use: { trace: 'retain-on-failure' },
})

3. Run your tests — npx playwright test. Results appear as they finish; the project is created on first submission.

4. Add the capture fixtures (recommended) — one file, and the deeper features light up: locator healing, slow-endpoint analysis, Web Vitals, console capture, failure-time ARIA snapshots.

// tests/fixtures.ts
import { test as base, expect } from '@playwright/test'
import { piwiFixtures } from '@piwitests/reporter'

export const test = base.extend(piwiFixtures)
export { expect }

Import test from this file in your specs instead of @playwright/test — that's the whole change. Details in the capture fixtures guide; a runnable project lives in examples/playwright-fixtures.

In CI, set PIWI_DASHBOARD_URL (and PIWI_API_KEY if auth is on) and you're done — branch, commit, CI metadata and --shard merging are detected automatically. See CI & sharding.

A quick tour

Failure clusters — forty red tests, three root causes	AI diagnosis — read against your actual git diff
Flaky tests — scored, classified, ranked by wasted CI time	Run detail — cases, worker timeline, traces, retry command
Locator healing — replacements from the last passing run	Performance — P90 trends and slowest-test tracking

Where this fits

Playwright's own HTML report is the right tool for debugging a run on your machine; Piwi is for the runs you can't open anymore. It's deliberately Playwright-only — that's what makes traces, step timing, and locator healing first-class rather than lowest-common-denominator. If you need one place for JUnit, pytest and Cypress results too, ReportPortal or Allure fit that better. If you'd rather someone else ran the server, Currents is the managed option. And if you only ever debug locally and never look back, you don't need any of this.

The longer version, including where Piwi loses, is in Why Piwi?.

Published artifacts

Everything below is built and published from this repository on each release.

Artifact	Registry	What it is
@piwitests/reporter	npm	The Playwright reporter — add it to playwright.config.ts
@piwitests/server	npm	The dashboard server, runnable with npx @piwitests/server
phenx/piwitests-server	Docker Hub	The server container (linux/amd64, linux/arm64)
ghcr.io/piwitests/platform	GHCR	The same container, mirrored — plus an edge tag built from main
@piwitests/instrumentation-nitro	npm	Optional: sends your Nitro/Nuxt backend's logs into a test run
PiwiTests.Instrumentation.AspNetCore	NuGet	Optional: the same for an ASP.NET Core backend
Desktop app (.msi, .dmg)	GitHub Releases	The server bundled in a native window — no Docker or Node

The two instrumentation packages are optional and only needed for backend log capture. Both container registries carry the same images; use whichever your organization prefers.

Project status

Pre-1.0 and under active development: expect occasional breaking changes between minor versions, pin a version tag, and keep backups of .data/. Every commit runs a CI matrix across SQLite/PostgreSQL and local/S3 storage with a full Playwright E2E suite.

Upgrades apply database migrations automatically on startup — and those migrations are forward-only, so rolling back means restoring a backup, not pulling the old tag. Read Upgrading before your first version bump. Direction and non-goals live in the roadmap.

Documentation

Full docs at piwitests.github.io. The usual entry points:

• Getting started — install, reporter, first run
• Core concepts — runs, test cases, executions, clusters
• Reporter and CI & sharding — getting results in
• Deployment and Configuration — running your instance
• Upgrading — what a version bump does, and why downgrading isn't a thing
• Privacy & data flow — exactly what leaves your server (nothing you didn't configure)
• Browser extension — pick ranked locators from the live page (standalone, not yet store-published)

A running dashboard also serves interactive API docs at /docs, rendered in-app from its own OpenAPI spec — no external CDN, so they work offline.

Community & support

• 💬 Discussions — questions, ideas, show & tell
• 🐛 Issues — bugs and feature requests
• 🔐 Security policy — how to report a vulnerability

Contributing

Contributions are welcome — CONTRIBUTING.md covers dev setup, tests, and commit conventions; AGENTS.md has the architecture tour.

cd application && npm install && npm run app:dev   # http://localhost:3000

License

MIT

---

_{Disclaimer: Piwi Dashboard is not affiliated with, endorsed by, or connected to Microsoft Corporation in any way. "Piwi" is a playful, unrelated name with no connection to any existing product or brand. Playwright is a trademark of Microsoft Corporation.}