Playrunner README
The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the Playrunner listing page.
Playrunner
Run Playwright at scale—without building the platform around it.
Keep the tests and CI you already use. Bring runners, environments, credentials, reports, integrations, and automatic sharding into one visual workflow.
Please ⭐ star Playrunner if you find it useful
Try Playrunner Cloud → · Run it locally · Read the docs
One Playwright node. Four concurrent shards. One merged report—even when a shard fails.
Your tests stay. The platform glue goes.
Playwright runs your tests brilliantly. The hard part is everything around the command: compute, environments, credentials, schedules, conditions, artefacts, reporting, and the CI scripts that connect them.
Playrunner turns those moving parts into a workflow your whole team can see, run, and evolve.
| 🎨 Build visually | Connect tests, triggers, conditions, branches, and downstream systems on a live workflow canvas. |
| 🤖 Code with confidence | Ask AI to generate a Playrunner workflow alongside your app, then create or update it from the CLI in your development pipeline. |
| ⚡ Shard automatically | Discover the real suite, fit useful parallelism to runner capacity, and merge every shard into one report. |
| 🏃 Run where you want | Use local Docker, managed cloud runners, or your own infrastructure without changing the suite. |
| 🔎 See the complete run | Follow node state and logs live, with Playwright reports, screenshots, videos, and traces attached to the run. |
| 🔐 Keep secrets out of workflows | Reuse managed environments and credentials instead of copying sensitive values into scripts. |
| 🪪 Reuse browser sign-ins | Capture authenticated browser sessions interactively and attach them to Playwright nodes without storing identity-provider passwords. |
| 🧩 Extend with integrations | Wire source control, schedules, messaging, AI analysis, issue tracking, webhooks, and more into the same DAG. |
From suite to signal
- Bring your existing tests. Your repository, Playwright configuration, and CI can stay as they are.
- Choose where they run. Start with local Docker, then move execution to managed or self-hosted runners when you are ready.
- Draw the workflow. Add schedules, branches, notifications, failure analysis, tickets, and downstream actions without another CI matrix.
- Inspect one complete result. Follow execution live and keep every log, report, and artefact attached to the run that produced it.
Reuse authenticated browser sessions
Authentication Profiles let tests start from a real signed-in browser session without storing identity-provider passwords in Playrunner. Create a profile for an Environment and authenticate manually in a visible browser. Local Playrunner opens the browser through its API; Playrunner Cloud uses a paired computer running the outbound-only CLI authentication companion.
Keep the companion terminal open, select the online device under Authentication Profiles, and start authentication. After signing in to the Chrome window, return to the terminal and press Enter to encrypt and upload the captured session state.
Select the profile on any Playwright node that needs it. Playrunner restores the session for that execution while keeping profiles isolated by Environment. The CLI is needed only while capturing or refreshing the profile. Cloud Test session checks and Hosted Runner workflows restore the encrypted stored state remotely and do not require the companion to remain connected. Each profile records its application, role, authentication status, last sign-in, and known expiry, and can be reauthenticated, revoked, or removed when access changes. Follow the Authentication Profiles tutorial and CLI companion guide for pairing, capture, hosted testing, and security.
Playrunner from the command line
The Playrunner CLI brings the same workflows to your terminal and CI/CD pipeline—without a global install. Use a revocable machine token to start a saved workflow, stream its progress, and turn its final status into a quality gate:
By default, the command waits for completion and exits non-zero when the
workflow fails, is cancelled, or times out. Pass inputs and acceptance criteria
to a run, attach pull-request context, emit newline-delimited JSON, or use
--no-wait when another system will monitor the result.
The CLI also supports workflow as code. Keep a project and workflow definition in source control, then create or update it idempotently from JSON:
Use npx playrunner --help for every option. See the
CLI overview, run guide,
and workflow creation guide for token scopes,
CI examples, inputs, source-change context, and the complete definition format.
Quick start
Prerequisites
- Docker Desktop
- Node.js 20+
- npm
Start the full local stack
On the first run, Playrunner opens the setup app. Follow the printed URL to confirm PostgreSQL and create the first admin account. With the default ports:
- Playrunner:
http://127.0.0.1:3100 - Setup:
http://127.0.0.1:3100/setup - Documentation:
http://127.0.0.1:3104/playrunner/
The .env.local file is optional unless you want to change ports before the
first run. If it is missing, ./start-local.sh creates it from the example. For
the complete walkthrough, see the
Getting Started guide.
Reopen setup or change the local defaults
To reopen the setup wizard:
Remove .env.local as well if you want Playrunner to regenerate the local port
and PostgreSQL defaults.
Run only the documentation site
Then open http://127.0.0.1:3104/playrunner/.
Explore
| Start here | What you will find |
|---|---|
| Automatic sharding | Suite discovery, capacity-aware planning, and report merging |
| Integration reference | Available nodes, providers, and configuration |
| Runner architecture | Local, managed, and self-hosted execution |
| Workflow execution | How the API, orchestrator, and ephemeral runners coordinate |
| Contributing | Ways to extend runners, integrations, reporting, and the product |
Package end-to-end tests
Package E2E tests run the real Vite frontend and Playrunner API against the
isolated playrunner_e2e PostgreSQL schema. Complete local setup first so
apps/api/.env contains a working DATABASE_URL, and keep PostgreSQL running.
Install Chromium once on a new development machine:
Run the deterministic mock-provider suite:
Run one integration package by its Playwright tag:
Mock mode still uses the real frontend, authentication, API, credential encryption, and database; only outbound provider boundaries may be faked. Live-provider scenarios are opt-in and require protected credentials:
Set PLAYRUNNER_E2E_DATABASE_URL to use another PostgreSQL server. Open the
latest report with npx playwright show-report, or read the
Testing guide for architecture and package
authoring details.
License
Playrunner is source-available under the Playrunner Sustainable Use License, copyright © 2026 Concept AI PTY LTD.