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.

From suite to signal

Trigger → Environment → Playwright → Condition → Slack / Jira / AI / Webhook
                              │
                              └── reports · traces · screenshots · video

1. Bring your existing tests. Your repository, Playwright configuration, and CI can stay as they are.
2. Choose where they run. Start with local Docker, then move execution to managed or self-hosted runners when you are ready.
3. Draw the workflow. Add schedules, branches, notifications, failure analysis, tickets, and downstream actions without another CI matrix.
4. 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.

npm install --global playrunner@latest
playrunner login
playrunner auth connect

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:

export PLAYRUNNER_URL='https://playrunner.cloud'
export PLAYRUNNER_API_KEY='<your-api-token>'

npx playrunner WORKFLOW_ID

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:

npx playrunner workflow create --file playrunner-workflow.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

./install-local.sh
cp .env.local.example .env.local
./start-local.sh

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.

rm apps/api/.env
./start-local.sh

cd docs
npm run start -- --port 3104

Explore