New here? docs/INSTALL.md gets you from download to your first run in a few commands:
dummyrun browsers install, set one API key, thendummyrun try https://your-site. The website is dummyrun.dev.
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.
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.
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.
| 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 |
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@vVERSIONReplace 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 # a first-time visitor, read-onlyEvery release is signed with cosign and comes with SLSA build provenance. To check a download before you run it, follow docs/INSTALL.md.
| 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 |
| docs/INKWELL.md | Inkwell, a small app with planted defects to try personas on |
| docs/ARCHITECTURE.md | How a run is put together and where data lives |
| docs/TELEMETRY.md | How runs map to OpenTelemetry traces, metrics, logs and Grafana annotations |
| docs/integrations/grafana.md | Send runs to Grafana, link them to your app's traces and set up alerts |
| docs/THREAT-MODEL.md | What a hostile page could try and what stops it |
| docs/ETHICS.md | What a persona can and can't tell you |
| schema/run-record.schema.json | The run record format, with examples in examples/runs/ |
| schema/report.schema.json | The JSON report format, with an example in examples/report/ |
| SECURITY.md | Report a vulnerability, and what to do about findings in apps you don't own |
| docs/LICENSING.md | What the licence lets you do |
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/.
Apache License 2.0. The name and logo are covered by the trademark policy.