New here? docs/INSTALL.md gets you from download to your first run in a few commands:
dummyrun browsers install, set one API key, then dummyrun try https://your-site. The website is
dummyrun.dev.
How it works
A persona is a made-up user. It has a role and permissions, plus goals, habits and a device. You point one at your
app, usually a preview built for a pull request, and it tries to get its job done in Chrome or Firefox. If you give it a
test account, it signs in first.
When it's finished, you get a run record. It holds every step with a screenshot, what broke, what
confused the persona and anything its role shouldn't have been able to see. You then go through the
findings with dummyrun review and confirm or reject each one. dummyrun report turns the confirmed
findings into a report you can share.
flowchart LR
A[Cast of personas<br/>role, goals, device, permissions]:::step --> B[Run<br/>real browser, your preview URL]:::agent
B --> C[Run record<br/>steps, screenshots, findings]:::step
C --> D[Review<br/>a person confirms or rejects each finding]:::agent
D --> E[Report<br/>confirmed findings with their evidence]:::out
classDef step fill:#ffffff,stroke:#1d1d1b,color:#1d1d1b
classDef agent fill:#fbad18,stroke:#1d1d1b,color:#1d1d1b
classDef out fill:#f0fdf4,stroke:#15803d,color:#0c2030
You tell the engine where your app lives with a small JSON target file: the base URL, the hosts it may
visit and how to sign in. Examples are in examples/targets/.
The persona runs on a model provider you choose. That can be Azure OpenAI, Anthropic or Amazon Bedrock.
It can also be Gemini, directly or on Vertex AI, or any OpenAI-compatible service such as a server on
your own machine. To keep model calls in a market such as the UK
or the EU, choose an endpoint or region there. On Vertex AI and Bedrock, --region picks where calls go.
For the others, the endpoint you configure decides, and --region is only recorded.
docs/PROVIDERS.md covers each one.
If you turn on telemetry, it goes to your own OpenTelemetry backend. OpenTelemetry is the open standard for
traces, metrics and logs.
Nothing turns into a ticket on its own. You decide what goes in your tracker, either by copying a finding
across or by scripting against the run record JSON.
Does it replace a scripted regression suite?
No, keep your suite. A script checks the steps you wrote, the same way every time. A persona picks its own
actions as it goes, so it can find problems nobody thought to script. When it finds one you want guarded
for good, write a test for it.
What leaves your network
The persona is a model reading what the browser shows, so screenshots and page text go to the model
provider you choose. Telemetry is optional and holds no screenshots. It carries step URLs, step targets
and finding titles, which can quote a few words from the page. It goes only to the OpenTelemetry
backend you configure, plus Grafana annotations if you ask for them. docs/TELEMETRY.md lists every field.
Who it's for
| You are | What you get |
|---|
| A QA lead | Exploratory testing by role on every pull request, with no scripts to maintain |
| A developer | Your product used the way a customer uses it, on your laptop or in CI |
| An agency | One cast run against every client's preview, with each client's data kept in its market |
| Product and UX | Friction and confusion, each tied to the step and screenshot |
| Compliance and security | What each role can see or do beyond its rights, checked by a person before it's raised |
| An executive | A report of what's broken, who it affects and the evidence |
Install
Download a binary from GitHub Releases. Or pull the container
image, which comes with Chrome for Testing and Firefox, or build from source.
docker run --rm ghcr.io/dummy-run/dummyrun:VERSION a11y https://example.com
go install github.com/dummy-run/dummy-run/cmd/dummyrun@vVERSION
Replace VERSION with the newest release number from the releases page.
With a binary, your first run takes three commands:
dummyrun browsers install # fetches Chrome for Testing and the matching chromedriver
export ANTHROPIC_API_KEY=... # or OPENAI_API_KEY, or run Ollama
dummyrun try https://your-site # works out what your site is for, then a visitor tries it, read-only
Every release is signed with cosign and comes with SLSA build provenance. To check a download before you
run it, follow docs/INSTALL.md.
Documentation
| Document | What it covers |
|---|
| docs/INSTALL.md | Release binaries, the container image and how to verify a download |
| docs/ENGINE.md | Install the engine, run a persona, review findings, sign in, zoom and text size, the read-only policy, and the accessibility sweep with its layout checks |
| docs/MCP.md | Use Dummy Run from Claude Code, Cursor, VS Code or Codex through dummyrun mcp |
| docs/CLI.md | Every command and flag, from the built-in help |
| docs/PROVIDERS.md | The model providers, how to sign in to each and what each supports |
| docs/PERSONAS.md | Copy a persona from the library into your cast and adapt it |
| docs/COVERAGE.md | What dummyrun coverage counts and how to read each number |
| docs/REPORT.md | What goes in a dummyrun report audit report and how to read a finding |
| docs/BADGES.md | The report badge and how to publish it from GitHub Actions |
If you'd like to work on Dummy Run itself, start with CONTRIBUTING.md. The project
docs sit next to it in docs/: PLAN.md for what's next and
STYLE.md for how we write. TYPOGRAPHY.md has the type scale,
NAMING.md the name, and DECISIONS.md the reasons behind past choices.
RELEASING.md is the release checklist. The logo and mascot are in brand/, and the
website source is in site/.
Licence
Apache License 2.0. The name and logo are covered by the trademark policy.
