Docs

See it in 2 minutes

A real run of EveryRole on rendrio.io, from pasting the address to watching a test’s replay. Waiting is sped up; nothing else is changed.

Getting started

1. Paste your app’s address. EveryRole explores it signed out first, so you see suggested tests without giving it any account.
2. Add the suggestions you want. Each one is a plain sentence (“A visitor can open the pricing page”) that EveryRole already tried twice for real. Add them one by one (“Add as test”), or select several and press “Add selected as tests”. Reword or dismiss the rest. Nothing runs as a test until you add it.
3. Add test logins for the kinds of user you have, then explore again to get tests for what they can do.
4. Turn on daily runs and a deploy hook in the app’s Settings tab.

Kinds of user and test logins

A kind of user is a group of people who see your app the same way: visitor (signed out), member, paying customer, admin… Give EveryRole one test login per kind, plus the address of your sign-in page. It signs in once per run for each kind, and every test runs in its own private browser session.

Invite EveryRole, the easiest way: each kind of user’s card shows an email address. Invite it into your app like a new teammate, with that role. EveryRole receives the invitation, accepts it and makes its own account, with a password nobody sees; you can remove it from your app like any teammate.

Or give EveryRole a test login. Use accounts made for testing, never a real customer’s. EveryRole can’t get past two-factor codes or CAPTCHAs, so a test login must sign in with email and password.

Starts at tells EveryRole where a kind of user’s own area begins when it isn’t linked from the rest of the site (for example /admin). Never click lists words EveryRole refuses before every click, while exploring and in every test: add anything that spends money, deletes data or sends email. The one exception is clean-up of test accounts EveryRole created itself.

What results mean

Passed

The page showed what the test expects.

Broken

Your app didn’t do what the test expects. This is the only red result, and the only one that can fail a pull request. You get an alert when a test breaks, and again when it works.

Couldn’t check

A problem on our side, not in your app: our browser stopped answering, the network failed, a machine was restarted. It costs no credits, never alerts you, and the test runs again next time.

Passed on 2nd try

It failed once, then passed. Nothing is broken, but the test may be unstable.

Not run

Something it needs failed first, usually signing in as its kind of user.

Pass or fail comes from checks on the loaded page: the text it shows, the address it reached, a control that is there. Every test that doesn’t pass is tried once more before you see it.

The three kinds of test

While exploring, every request that would save is blocked in the browser. Each suggested test is one of three kinds, and you see which before you add it:

Never-click words (“Delete”, “Pay”…) are refused before every click, in every kind of test.

Daily runs

In an app’s Settings tab, turn on “Run every day” and pick an hour and time zone. All your tests run once a day at that hour. A day with nothing to test is skipped, and a run that is already going isn’t started twice.

Deploy hooks

Each app can have a secret link that starts a run of all its tests. Make it in the app’s Settings tab (on Indie and Pro and Team), and call it when a deploy finishes. Anyone with the link can start a run, so keep it in your CI secrets; you can replace it at any time.

The body is optional. JSON or form fields:

base_url

Test another address than the app’s own, like a preview deploy (Pro and Team). Only its scheme and host are used.

environment

production (the default for the app’s own address), preview (the default for another address) or staging. Tests that change data run only in the environments you allowed when you added them.

commit, ref, url

Shown with the run so you know which deploy it tested.

The answer is 202 with the queued job. Two deploys in a row while a run is still waiting don’t start two runs: the waiting run tests the newest deploy.

The snippets

The first tab tests production after each successful deploy; Vercel and Netlify report their deploys to GitHub, so it works with them too. Testing every preview deploy at its own address is part of Pro and Team.

Copy# .github/workflows/everyrole.yml
# tests production after each successful deploy (Vercel and Netlify report theirs to GitHub)
name: EveryRole
on: deployment_status
jobs:
  test:
    if: >-
      github.event.deployment_status.state == 'success' &&
      github.event.deployment_status.environment == 'Production'
    runs-on: ubuntu-latest
    steps:
      - run: >-
          curl -fsS -X POST
          "${{ secrets.EVERYROLE_DEPLOY_HOOK }}"
          -d "commit=${{ github.sha }}"

Copy# Pro, Team: also test each preview deploy at its own address
# (on other plans an address other than your app's is refused: use the first tab)
name: EveryRole
on: deployment_status
jobs:
  test:
    if: github.event.deployment_status.state == 'success'
    runs-on: ubuntu-latest
    steps:
      - run: >-
          curl -fsS -X POST
          "${{ secrets.EVERYROLE_DEPLOY_HOOK }}"
          -d "base_url=${{ github.event.deployment_status.environment_url }}"
          -d "commit=${{ github.sha }}"

Copy# Site settings, Deploy notifications: add an outgoing webhook
# for "Deploy succeeded" with your deploy link as the URL
https://everyrole.dev/hooks/deploy/YOUR-SECRET

Copy# the last step of your deploy
curl -X POST \
  https://everyrole.dev/hooks/deploy/YOUR-SECRET

Use EveryRole from your coding agent

Your coding agent (Claude Code, Cursor, Codex) can check its own work before it says it’s done: it runs the tests you added to your app, as every kind of user, and reads what broke, where, and the replay. It uses your workspace’s apps, tests and credits, with the same plan limits as the app.

1. Make a key

In Settings → API keys, the workspace owner makes a key and copies it (it’s shown once). Give each agent or machine its own key: you see what each one used, and can set a monthly credit cap per key or revoke it at any time.

2. Call the API

Send the key as a bearer token. Answers are JSON.

# your apps, their kinds of user and tests
curl -H "Authorization: Bearer $EVERYROLE_API_KEY" https://everyrole.dev/api/v1/apps

# run an app's tests on a preview deploy (both fields optional) -> {"job": 42, ...}
curl -X POST -H "Authorization: Bearer $EVERYROLE_API_KEY" -H "Content-Type: application/json"   -d '{"base_url": "https://my-app-git-branch.vercel.app", "environment": "preview"}'   https://everyrole.dev/api/v1/apps/YOUR-APP/runs

# wait for it: status, progress, and the run's id when done
curl -H "Authorization: Bearer $EVERYROLE_API_KEY" https://everyrole.dev/api/v1/jobs/42

# the results: per test its verdict, the failing step and a link to its replay
curl -H "Authorization: Bearer $EVERYROLE_API_KEY" https://everyrole.dev/api/v1/runs/7

POST /api/v1/apps/YOUR-APP/explore explores the app again, so new pages get suggested tests. A preview address must be on the public internet; for localhost, use the open-source runner.

What your plan allows

Each plan tests a number of environments per app. Production counts as one, each saved environment (staging, qa…) as one, and every preview deploy together as one: Free 1 (production); Indie 2: production + staging; Pro 3: production, staging and previews; Team unlimited. A run sent to an environment beyond that is refused with a 402 that names the plan that allows it. The staging → production release check (a change validated on staging waits for the production release, the agent’s release tool, then is checked there) is part of Pro and Team; on the other plans, staging and production each run their own tests. GET /api/v1/apps/YOUR-APP and the setup tools say what your workspace’s plan allows.

401

No key, a wrong one, or a revoked one.

402

Not enough credits, or the key’s monthly limit is reached.

402

An environment beyond your plan’s environments per app, or the release check on a plan without it: the message names the plan that allows it.

403

Your plan doesn’t include it (more explorations this month).

409

A job of that kind is already waiting or running for the app (its id is in the answer), or the app has no tests yet.

422 · 429

A bad address or environment · too many requests from this key in a minute: wait and try again.

3. Or connect it as an MCP server

EveryRole is an MCP server at https://everyrole.dev/mcp: nothing to install, your key as a bearer token. Its tools: setup_guide, list_apps, get_app, create_app, set_test_accounts, set_environments, explore, list_suggestions, add_suggestions, dismiss_suggestion, reword_suggestion, run_tests, job_status, run_results, get_deploy_link, setup_pipeline, and for testing a change test_change, change_status, answer_change, run_change, change_pictures (the agent sees each step's page itself) and keep_change. In Claude Code:

claude mcp add --transport http everyrole https://everyrole.dev/mcp --header "Authorization: Bearer er_live_..."

In Cursor (.cursor/mcp.json) and other agents that read the same format:

{
  "mcpServers": {
    "everyrole": {
      "url": "https://everyrole.dev/mcp",
      "headers": {"Authorization": "Bearer er_live_..."}
    }
  }
}

An agent that only runs local servers can use the same tools from the package: pip install everyrole, then claude mcp add everyrole -e EVERYROLE_API_URL=https://everyrole.dev -e EVERYROLE_API_KEY=er_live_... -- everyrole mcp.

Keep the key out of your repository: put it in your agent’s settings or environment, not in a file you commit. Each call counts toward the key’s requests a minute and shows in its usage, like the API.

Ask Claude to set it up

With EveryRole connected, say to your agent: “Add EveryRole to this project.” It follows EveryRole’s setup guide (the setup_guide tool, also the set_up_everyrole prompt):

1. Add the app from its public address (create_app). A first look finds its sign-in page and other addresses.
2. Test accounts: it asks you for one account per kind of user (free, paid, admin…) and saves them (set_test_accounts). They’re encrypted like in the app and never shown again, not even to the agent.
3. Explore the app as every kind of user (explore). Each suggested test is run twice for real first.
4. Add the suggestions you want (add_suggestions). “All that worked twice” never includes a test that changes data; those are added only by name, and run on preview deploys only. Nothing becomes a test unless it’s added.
5. Run the tests (run_tests, then run_results). A broken test says its step, what was expected and what the page showed, so the agent can fix the code without watching the replay.
6. Put it in your pipeline (setup_pipeline): it writes a GitHub Actions workflow into your repository and asks you for the secret to set. From then on, every deploy runs the tests and the result shows on the pull request. EveryRole never touches your repository itself.

As the app grows, new pages are explored after deploys and suggested; your agent (or you) adds the right ones. Before it says a change is done, it runs the tests on the change’s preview deploy.

Test this change

When a change alters a flow (a sign-up wall that moves, a new onboarding, a checkout step), your agent describes it to EveryRole in plain words, the way it would in a pull request: what a user can now do, and what each page shows. EveryRole:

1. Plans the journeys that prove it, every path and the variants that usually break (a refresh right after logging in, a button pressed twice, an optional step skipped), and asks what the description leaves open (test_change, then change_status and answer_change). Planning is free.
2. Runs them where the change is deployed (run_change): at the address your agent sends, a preview URL for example, or on production. A login wall is passed with your app’s test logins. Each step is judged on its own, with a picture of the page as proof; “once and only once” is checked after a reload. One credit per step.
3. Reports each step: the agent reads why a journey failed as text and fixes it; you see the same plan, questions, verdicts and pictures in the app’s Changes tab.
4. Keeps the journeys as critical tests after the merge (keep_change), so the next change can’t break the flow silently.

A change’s runs stay out of your app’s run history and alerts. Part of Indie, Pro, Team; automatic runs on every preview deploy are Pro and Team; exploring and suggested tests stay free. Without an agent, describe the change yourself in the Changes tab.

The main journey

Every app has one journey that matters most: a visitor arrives, uses the home page’s main button, meets the sign-up wall, gets through it, comes back to what they were doing, and gets the first real result your app promises. Test the main journey (the Changes tab, or test_change with main_journey: true) plans and runs it with no description: EveryRole finds each stage on your live site. When a journey stops, it says where, in one sentence: “Steps 1–3 passed; stopped at step 4 (Press Make it and sign up): Keeps what was typed earlier: missing “cal.com”.”

New accounts. To test signing up itself, allow EveryRole to create new accounts (the checkbox, or new_accounts: true). Each run then signs up with an address of its own and a new password, opens the confirmation email itself, and checks nothing was lost after the wall. Each run of such a test makes a real account in your app, so it’s off unless you turn it on, and you choose when those tests run: once, after each release, once a week or every run (Settings → Sign-up and payments). Every other test signs in with your existing test accounts. Signing up with Google needs a person, and EveryRole never pays.

Alerts

EveryRole tells you when something changes: a test that worked stopped working (“stopped working since run #12”), or a broken test works again. A run where everything stays the same sends nothing. “Couldn’t check” on its own never sends anything either: it isn’t your problem.

You always see alerts on the Alerts page. Email and Slack alerts (Indie, Pro, Team) are set in Settings, Alerts, and in each app’s Settings tab. The first full run of an app is its starting point, so it only shows up in the app.

The check-up email is the calm one: proof your apps are watched, even on a day when all is well. When each app was checked (date and time), how each kind of user did, what stopped working or works again, and what waits for you; never your credits. It comes every week on every plan; every day or only when something changes is Indie, Pro, Team. Choose the hour, the time zone and which kinds of user in Settings, Alerts.

Credits

One test run as one kind of user uses 1 credit, one page opened for page access 0.25, and one exploration 1 credit per page it explores, as each kind of user. Sign-ins are free, and so is everything that couldn’t be checked because of a problem on our side.

When a job starts, the most it can use is set aside; when it ends, you pay only for what was really checked. Your plan’s credits start fresh every month and don’t carry over; bought credits never expire. See pricing.

Security

• Passwords are encrypted at rest. Test logins’ emails and passwords are stored encrypted (Fernet: AES with an HMAC) with a key only the server holds. They are decrypted only to hand them to the test run that signs in, as environment variables of that one process, and are never written to disk in clear.
• AI models never see them. Passwords are typed by EveryRole itself; models only ever see the name of a value (“password”), and every request to a model passes a filter that replaces any secret with a placeholder.
• Exploring can’t change your app. While exploring, every request that would save (POST, PUT, PATCH, DELETE, form submissions, beacons) is blocked in the browser and recorded.
• Tests only do what their kind allows. Of the three kinds of test, only a “changes data” test really saves, and only in the environments you allow. Never-click words are refused before every click, while exploring and in every test.
• Clean-up, the one exception to never-click. After a change about new accounts, EveryRole deletes the test accounts it created itself, through your app’s own settings. Never your test logins or real users.
• Your account. Passwords are hashed with Argon2id, sessions use HttpOnly cookies, every form is protected against cross-site requests, and each workspace can only see its own apps.
• Known limits. The save-blocker works inside the page: it doesn’t see service-worker traffic, websockets, or apps that change data on a plain page load. Keep risky words in the never-click list and run data-changing tests on preview deploys.