Organizing Suites & Personas
Read the field note below to see how we apply this pattern in real QA Agent projects.
Organizing Suites & Personas
A flat folder of 30 test cases becomes unmanageable fast. Suites and personas are how you keep it structured.
What you'll learn
- How to structure test suites for a real product
- How personas handle authenticated flows without login steps in every spec
- How to use tags for targeted runs
Suite structure
A suite is a directory under tests/. The directory name is the suite name:
tests/
smoke/ # 10-15 critical-path tests, runs on every deploy
auth/ # sign-in, sign-up, password reset, session expiry
billing/ # subscription upgrade, downgrade, payment failure
dashboard/ # core feature flows for logged-in users
onboarding/ # new-user first-session flows
Design principles
smoke should run in under 5 minutes. Include only tests that would block a deploy if they fail.
Feature suites (auth, billing, etc.) should be cohesive: a developer owns the feature and can own the suite. When a feature changes, one person knows which suite needs updating.
Don't duplicate tests across suites. If a checkout test needs a logged-in user, it belongs in checkout with persona: free-user, not duplicated in both auth and checkout.
Personas
A persona represents a user state. Their authentication level and saved credentials. The three built-in personas:
| persona | auth state | credential file |
|---|---|---|
unauthenticated | no session | none |
free-user | signed in as a free account | personas/free-user.json |
pro-user | signed in as a paid account | personas/pro-user.json |
Setting up a persona
Run the auth command once per persona to capture a session:
python cli.py auth --persona free-user --email testuser@example.com --password secret123
This opens a browser, signs in with the given credentials, and saves the session cookies to personas/free-user.json. QA Agent loads this file at the start of every test that uses the free-user persona, so the agent starts the test already logged in.
Regenerate persona files whenever sessions expire (typically every 30 days or after a password change).
Using personas in test cases
Set persona in the test metadata:
- **persona**: free-user
The agent starts the browser with the saved session. Steps can assume the user is already authenticated. No need to write "Navigate to /login, enter credentials, click sign in" in every test.
Tags for targeted runs
Tags let you run a subset of tests across suites:
python cli.py run --tag critical # run all critical-priority tests
python cli.py run --tag billing # run all billing-tagged tests
python cli.py run --tag smoke,critical # run tests tagged smoke OR critical
Tag conventions that work well in practice:
smoke. Safe to include in CIcritical. Must pass before any production deployrelease. Full coverage run before a release<feature-name>. Scoped to one product area for targeted runs after a feature change
What's next
Quick answers
What do I get from this cable?
You get a dated field note that explains how we handle this test-organization workflow in real QA Agent projects.
How much time should I budget?
Typical effort is 25 min. The cable is marked intermediate.
How do I install the artifact?
This cable is guidance-only and does not ship an installable artifact.
How fresh is the guidance?
The cable is explicitly last verified on 2026-04-17, and includes source links for traceability.
Work with FRE|Nxt
We build the production AI systems we write about.
Cables are the field notes. The playbooks come from client engagements — multi-agent systems, RAG pipelines, and LLM cost cuts that ship and hold up in production. If something here maps to a problem on your roadmap, two ways in:
Audit capacity: 5 slots/month · No pitch deck · NDA on request
Use auto mode, not --dangerously-skip-permissions
Two flags promise to stop Claude Code from pausing at every tool call. One of them reads your settings, honours your allowlist, and refuses to run anything g…
Publish your stack to Cables (automated)
A skill that walks Claude Code through publishing your Claude stack to the Cables community in one conversation. No manual repo setup, no hand-written `stack…
Replicate Ragav's stack (skills + plugins + scripts)
Pick the stack that matches what you're building. Each one is a single `npx` command. Plugins installed, skills synced, marketplaces configured, no bash scri…