qa-persona

qa-persona

/qa-persona:init running against listmonk — value-loop summary and persona table from the 2026-05-12 dogfood run. Run vhs scripts/demo.tape to regenerate.

End-to-end testing for multi-user SaaS apps, driven by AI-generated personas with goals, scope, and a point of view. Catches the bugs unit tests can't.

The problem

You ship a feature. Pytest passes. CI is green. You demo it internally and everything looks fine.

A real customer opens it the next morning and gets stuck on step three.

This happens because unit tests answer "does this function return the right value." They don't answer "did the right person see the right thing at the right time, and could they actually do something useful with it." That second question is where SaaS apps with more than one type of user — buyers and sellers, admins and managers and contributors, requesters and approvers — go wrong.

The gap is bigger than people think. On the B2B connectivity marketplace this methodology was extracted from, three persona walkthroughs surfaced six bugs that 200+ pytest tests had missed: a 500 in the accept-proposal path, two status-machine bugs that only triggered on the second idempotent call, three UX bugs that were technically "working" but unusable in practice.

If your tests live in tests/test_*.py and your bugs live in customer support tickets, the gap between them is what qa-persona is for.

What it does

qa-persona tests your app the way real users would use it.

You don't write test_create_request_returns_201. You write a persona — Sarah, the network engineer at Acme Networks, who has $8k/month to spend and needs network capacity provisioned to a new site — and an AI agent drives Sarah through your system end to end. First through the API (fast, deterministic, proves the business loop closes). Then through the browser (catches the "works but unusable" UX gaps the API tests can't see).

Each persona is a real character, not a credential:

• An intent. Sarah is trying to get connectivity provisioned under budget. She's not trying to "POST a JSON body."
• A fixed identity. [email protected] is the same Sarah in every test run. The product evolves; she stays — so coverage compounds across releases instead of starting over.
• A scope. Sarah can't see what BigCorp's account is doing. If she can, that's a bug. The persona-isolation rules catch it.
• A point of view. When Sarah gets stuck, that's the test signal. "I couldn't tell which supplier won my deal" is a finding. Pytest can't tell you that. A persona walking the flow can.

Three to five personas usually cover the value loop. The catalog grows with the product: every new feature ship triggers an iterative re-run that revisits affected personas, appends a new run to the walkthrough log, and updates the bug tracker. The catalog never shrinks.

How the two layers fit together

Tests run in two layers, in this order:

1. API automation first. Fast bash scenarios, ~10–30 seconds each, that prove the business loop actually closes. Curl the API, query the DB, assert the lifecycle truth table. If a Layer 1 fails, it's a backend bug — full stop.

2. Browser walkthrough second. Once Layer 1 is green, drive the same scenario through the real UI in a headless browser. Anything that fails here is a UX bug — the data is right, the human can't get to it.

Mixing the two layers conflates failure modes. API-first separates correctness from usability so each layer's feedback is pure.

Install (Claude Code)

qa-persona is shipped as a Claude Code plugin. Three install paths, in order of how often they're the right answer:

User-level (recommended — works across every project):

git clone https://github.com/andreykuzin/qa-persona.git \
  ~/.claude/plugins/cache/local/qa-persona

Then add ~/.claude/plugins/cache/local/qa-persona to pluginPaths in ~/.claude/settings.json.

Per-project:

git clone https://github.com/andreykuzin/qa-persona.git .claude/plugins/qa-persona

Marketplace (self-hosted, today):

In an active Claude Code session, run these two slash commands:

/plugin marketplace add andreykuzin/qa-persona
/plugin install qa-persona@qa-persona-marketplace

The repo is registered as its own single-plugin marketplace via .claude-plugin/marketplace.json — works today, before any Anthropic Plugin Directory listing.