BugmoleDocs bugmole.com →

Roles

A role is who a test journey runs as: a guest who isn't signed in, a signed-in member, an admin. Every plan names one role as its actor, and a test case set can name one too. Roles aren't personas: a persona is how AI explores (curious, impatient), a role is who it is signed in as.

How roles are chosen

Bugmole suggests roles, and you decide which ones count.

  1. Bugmole suggests. Discovery and agents suggest a role when something concrete points at one. Each suggestion records that evidence:
    • a sign-in wall (a /login page, a route that needs a session, an auth blocker) suggests guest and member;
    • a role-gated route such as /admin or /staff suggests admin or staff;
    • a role-gated menu or action such as "Admin" or "Moderation" suggests admin or moderator;
    • an entry in spec/roles.yaml marked status: suggested;
    • the actor a discovered journey was walked as.
  2. You decide. Settings → Roles lists each suggestion marked Suggested, with where it came from and why. Confirm it, Rename it (which also confirms it), or Reject it. You can also add a role yourself; a role you add is confirmed.
  3. Only confirmed roles are used. Planning (bugmole_plan) and test case sets (bugmole_write_test_cases) refuse a role that is only suggested or was rejected, and say which roles are confirmed. The pipeline pauses with Waiting on you until you decide.

Only workspace owners and admins decide roles. An agent or API key can only suggest: it can't confirm a role, even its own suggestion. A rejected role stays rejected however often it's suggested again, until someone confirms it under Rejected. Every decision is in the audit log.

Where roles are kept

When both have an answer, the dashboard wins: a role rejected there isn't used even if roles.yaml lists it, and a role confirmed there is used even before it is added to roles.yaml.

From the CLI, bugmole roles lists roles and bugmole roles suggest suggests one. From MCP, use bugmole_roles_list and bugmole_role_propose. See the CLI reference and Bugmole MCP.

Why Bugmole suggests and you decide

We compared three ways of choosing roles.

Bugmole assigns roles automatically You select roles yourself Bugmole suggests, you confirm (what Bugmole does)
Getting started Fastest: roles appear as discovery runs Slowest: nothing is tested until someone writes the roles Fast: suggestions appear as discovery runs, one click each
Accuracy Guesses from routes and menus; a /admin link that 404s still becomes a role As accurate as the person who writes them Suggestions carry their evidence, and a person checks it
Missed roles Only finds roles the app shows to the explorer; roles behind invitations or paid plans stay hidden Only finds roles the person remembers Both: evidence-based suggestions, plus roles you add yourself
Wasted runs Runs and AI credits are spent on roles that don't exist None None: nothing runs until a role is confirmed
Naming Machine names (role_gated_route_1) Your team's words Suggested names you can rename before confirming
Accountability Nobody decided; hard to explain a test for a role no one asked for Clear Clear: the audit log records who confirmed or rejected each role
Upkeep New roles appear by themselves, including wrong ones Someone has to notice new roles New roles appear as suggestions waiting for you
Safety An agent can widen what is tested, and as whom, without anyone agreeing Safe An agent can suggest but never confirm

Automatic roles are quick but untrustworthy: a test plan written for a role that doesn't exist fails for the wrong reason, and a role only an agent believes in is hard to question later. Hand-picked roles are trustworthy but slow, and people forget roles the app plainly shows. Suggesting with evidence and confirming by hand keeps the speed of the first and the judgement of the second, at the cost of one decision per role.