About Playrunner
Playrunner organizes Playwright tests into repeatable workflows for development teams, CI, and coding agents. It supports workflow discovery and execution, with inspectable test results, logs, reports, and browser artifacts.
Key features
- 01Organize Playwright tests as workflows
- 02Discover projects and create workflows
- 03Start runs and follow execution
- 04Inspect reports, logs, and browser artifacts
- 05Shard suites and merge reports
- 06Run locally, in managed cloud, or self-hosted
Use cases
- 01Have a coding agent run and inspect a smoke test
- 02Rerun saved workflows in CI
- 03Review logs, traces, and video for failed tests
- 04Shard execution of a larger test suite
MCP support
Compatible MCP clients can connect to Playrunner Cloud to discover projects, create workflows, start runs, and inspect returned evidence.
Configuration
Remote servers need no local install. Pick your client, then copy the config or install in one click.
https://playrunner.cloud/mcpclaude mcp add --transport http dev-playrunner https://playrunner.cloud/mcp{"mcpServers":{"dev-playrunner":{"type":"http","url":"https://playrunner.cloud/mcp"}}}Open in Cursor{"servers":{"dev-playrunner":{"type":"http","url":"https://playrunner.cloud/mcp"}}}Open in VS Code{"mcpServers":{"dev-playrunner":{"type":"http","url":"https://playrunner.cloud/mcp"}}}{"mcpServers":{"dev-playrunner":{"serverUrl":"https://playrunner.cloud/mcp"}}}Run commands in a terminal; paste JSON into the client’s MCP config and restart. Servers that need sign-in will prompt on first connect.
Tools
Details
From the project README
Build with AI. Ship with evidence.
Playrunner turns your Playwright tests into reusable workflows
your team, your CI, and your coding agent can run.
Go from “the code is done” to “here is what passed”.
Run real browser checks. Follow the execution. Open the report, trace, or video.
Try Playrunner Cloud → · Run locally · Connect your agent · Read the docs
See Playrunner in a minute
| Product overview · 61 seconds | Workflow & evidence · 51 seconds |
|---|---|
 |  |
| A narrated tour of reusable workflows, agent connections, and sharding. | A fresh local workflow: two passing checks, the report, and screenshot evidence. |
Recorded with OBS and narrated with AI on 19 October 2026. The overview shows product examples; the workflow video tours a real local run’s saved configuration, passing report, and screenshot evidence. Video notes and transcripts →
Your agent wrote it. Now check it.
A working-looking screen is a good start. A repeatable test with an inspectable result is something your team can build on.
Playrunner gives AI-assisted developers and test teams a shared place to run Playwright, reuse environments and browser sign-ins, and investigate failures. Keep your existing tests. Give them a workflow you can run again after the next change.
For vibe coders and their favourite agents
Connect a compatible MCP client to Playrunner Cloud, then ask:
Run my checkout smoke workflow once. Wait for it to finish, tell me which tests passed or failed, and include the report links.
The agent can discover projects, create workflows, start runs, and inspect the returned evidence from the same conversation. Your saved workflows remain available to your teammates and CI.
Codex · Claude · Cursor · Gemini CLI · Antigravity · Grok
Connection steps and capabilities vary by client. Use a client with remote Streamable HTTP and OAuth support, or the CLI from a shell-capable agent. Choose your connection → Read the MCP guide →
From a test suite to a repeatable check
- Bring a test. Use your existing Playwright repository or start with an inline script.
- Give it a home. Choose an environment, an optional Authentication Profile, and where the workflow runs.
- Run it your way. Use the visual editor, your agent, the CLI, or a schedule.
- Follow the evidence. Inspect test results, logs, and the report and artefacts produced by the run. A started job is not a passing test.
Your agent / CI / schedule
↓
Environment → Playwright → Pass or fail → Your next action
↓
Report · traces · screenshots · video
Your tests, environments, runners, and next steps. One visible workflow.
Less test infrastructure. More useful feedback.
| What you need | What Playrunner brings |
|---|---|
| A workflow the team can understand | A visual canvas for tests, conditions, branches, and follow-up actions. |
| Faster feedback from larger suites | Automatic sharding with capacity-aware planning and one merged report. |
| A choice of where tests run | Local Docker, managed cloud runners, and self-hosted execution. |
| A way to investigate a failure | Live node state and logs, plus Playwright reports and captured artefacts. |
| Tests that start signed in | Reusable Authentication Profiles, isolated by environment. |
| Less secret copying | Managed environments and credentials, referenced by your workflows. |
| A useful next step | Integrations for GitHub, Slack, Jira, AI analysis, webhooks, and more. |
Four shards. One merged report. Failed tests stay visible.
Give your CI the same workflow
Start a saved workflow, stream its progress, and return a failing exit code when the workflow fails, is cancelled, or times out:
export PLAYRUNNER_URL='https://playrunner.cloud'
export PLAYRUNNER_API_KEY='<your-api-token>'
npx playrunner WORKFLOW_ID
Prefer workflows as code? Keep the definition alongside your application:
npx playrunner workflow create --file playrunner-workflow.json
CLI run guide → · Workflow definitions →
Need a signed-in browser? Reuse an Authentication Profile.
Capture a browser session interactively, then select the profile on your Playwright node. Playrunner restores the stored session for the execution without storing your identity-provider password.
For Playrunner Cloud, pair your computer with the authentication companion:
npm install --global playrunner@latest
playrunner login
playrunner auth connect
Keep the companion open while capturing or refreshing the session. Hosted workflow runs can restore the encrypted stored state without the companion remaining connected.
Quick start
Prerequisites
- Docker Desktop
- Node.js 20+
- npm
Start the full local stack
git clone https://github.com/playrunner/playrunner.git
cd playrunner
./install-local.sh
./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.
Reopen setup or change the local defaults
To reopen the setup wizard:
./start-local.sh --setup
Remove .env.local as well if you want Playrunner to regenerate the local port
and PostgreSQL defaults.
Run only the documentation site
cd docs
npm run start -- --port 3104
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 |
Contributing? Run the 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:
npm exec --prefix apps/frontend -- playwright install chromium
Run the deterministic mock-provider suite:
npm run test:e2e:mock
Run one integration package by its Playwright tag:
npm run test:e2e:mock -- --grep @github
npm run test:e2e -- --grep @github
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:
npm run test:e2e:live
npm run test:e2e:live -- --grep @github
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.
Help shape Playrunner
Try it on one workflow that matters to you. Tell us what worked, what failed, and what would make it useful every day.
Join the Discord · Report an issue · Star the project
License
Playrunner is source-available under the Playrunner Sustainable Use License, copyright © 2026 Concept AI PTY LTD.
Comments
New to MCP?
From what the protocol is to installing your first server, these answers cover most first questions.
An open protocol that defines how AI applications connect to external tools and data in a uniform way. Clients talk to the model; MCP servers provide tools, resources and prompt templates. They exchange standard messages, so one server can be reused by many clients.