QA Testing

Autonomously test and verify the application using browser automation with the QA auth bypass system.

Before You Begin

REQUIRED: Read the agent-browser skill first to learn browser automation commands:

./agent-browser/SKILL.md

Do not proceed until you have read and understood the agent-browser skill. It contains essential commands for navigating pages, taking snapshots, interacting with elements, and capturing screenshots.

Warning: Subagent type: Use generalPurpose, NOT browser-use. The QA workflow uses the agent-browser CLI via Shell commands. The browser-use subagent has its own built-in browser that is completely separate from agent-browser and does NOT follow this skill's patterns. Always delegate QA tasks to a generalPurpose subagent, which has Shell access to run agent-browser commands.

Prerequisites

You have read the agent-browser skill (see above)
Dev server is running

Authentication

The app uses a QA bypass system that allows automated testing without email verification.

QA Test Emails

The QA email whitelist is defined in the project's config package. Look for the QA config at:

packages/config/src/qa.ts

Read that file to find the whitelisted emails and the isQaEmail() helper.

Each email creates a distinct auth user with its own session and data. Use different emails when testing multi-user flows (invitations, member management, role changes, etc.).

How QA Auth Works

Enter a whitelisted QA email in the email field on the login page
Click the submit button
The frontend detects this is a QA email (via isQaEmail() from the config package) and calls the QA bypass API endpoint
The server validates the email is whitelisted and generates a session without sending email
You're logged in immediately

No env vars needed

The QA email whitelist is hardcoded in the config package. No QA-specific env vars are required.

CRITICAL: Never Skip Steps Due to Missing State

Never assume QA accounts have pre-existing data. QA accounts are ephemeral — they may have no prior data or state. Never skip a verification step because the required data doesn't exist. Create the state you need.

Create state through the UI. Use browser automation to perform the actions a real user would — fill out forms, click buttons, and let the app create the data naturally. This tests the full stack (UI -> API -> DB -> side effects) and catches more bugs than testing views in isolation.

Last resort: Seed via database only when no UI or API path exists at all. Write a temporary seed script, run it before browser tests, then clean up after and delete the script.

QA Workflow

Step 1: Start dev server (if not running)

Check if the server is already running by listing the terminals folder. If not running, start the app's dev server (e.g., bun run dev in the appropriate app directory).

Step 2: Navigate to the app

agent-browser open http://localhost:<PORT>

Step 3: Authenticate

agent-browser snapshot -i
# Find the email input
agent-browser fill @e1 "qa@test.local"
# Find and click the submit button
agent-browser click @e2
# Wait for auth to complete and redirect
agent-browser wait 2000
agent-browser snapshot -i

After login, you should see the authenticated view (dashboard, home page, etc.).

Step 4: Verify the feature/change

Navigate to the relevant part of the app and verify the expected behavior. Take screenshots and read them to document the verification:

agent-browser screenshot --full
# The command prints the saved file path — you MUST read that file
# using the Read tool to actually see the screenshot contents.
# A screenshot you don't read tells you nothing.

Step 5: Clean up

agent-browser close

Multi-User Testing

For flows that require multiple authenticated users, use separate browser sessions with --session:

# Session 1: Primary user
agent-browser --session user1 open http://localhost:<PORT>
agent-browser --session user1 snapshot -i
agent-browser --session user1 fill @e1 "qa@test.local"
agent-browser --session user1 click @e2
agent-browser --session user1 wait 3000

# Session 2: Secondary user (separate browser, separate auth)
agent-browser --session user2 open http://localhost:<PORT>
agent-browser --session user2 snapshot -i
agent-browser --session user2 fill @e1 "qa2@test.local"
agent-browser --session user2 click @e2
agent-browser --session user2 wait 3000

# Now you have two authenticated users to test multi-user flows

# Clean up both sessions
agent-browser --session user1 close
agent-browser --session user2 close

Each --session name creates an isolated browser context with its own cookies, localStorage, and auth state.

Common Verification Patterns

Reminder: Every agent-browser screenshot call saves a file and prints its path. You MUST read that file with the Read tool to see the image. If you skip the read, the screenshot is wasted.

Verify login works

agent-browser open http://localhost:<PORT>
agent-browser snapshot -i
agent-browser fill @e1 "qa@test.local"
agent-browser click @e2
agent-browser wait 3000
agent-browser snapshot -i
# Should show the authenticated view
agent-browser screenshot
# Now READ the screenshot file to verify what's on screen
agent-browser close

Verify a specific page/route

agent-browser open http://localhost:<PORT>
# Authenticate first...
agent-browser fill @e1 "qa@test.local"
agent-browser click @e2
agent-browser wait 3000
# Navigate to the specific route
agent-browser open http://localhost:<PORT>/some-route
agent-browser snapshot -i
agent-browser screenshot

Verify UI component changes

agent-browser open http://localhost:<PORT>
agent-browser snapshot -i
# Look for the specific element
agent-browser get text @eN  # Get text content
agent-browser get styles @eN  # Check styling
agent-browser screenshot

Verify form behavior

agent-browser snapshot -i
agent-browser fill @input1 "test value"
agent-browser fill @input2 "another value"
agent-browser click @submit
agent-browser wait --load networkidle
agent-browser snapshot -i
# Check for success/error states

Troubleshooting

Auth fails with "QA bypass not allowed"

Ensure NODE_ENV is not set to "production"
Make sure you're using one of the whitelisted emails from packages/config/src/qa.ts

Server not responding

Check if dev server is running: list the terminals folder
Start the dev server from the appropriate app directory
Check the app's package.json for the correct dev command and port

Element refs invalidate

Re-run agent-browser snapshot -i after any navigation or DOM changes
Refs like @e1 are only valid until the page changes

Environment Variables Required

In apps/app/.env:

SUPABASE_SERVICE_ROLE_KEY=<your-service-role-key>

No QA-specific env vars are needed — the email whitelist is hardcoded in packages/config/src/qa.ts.

qa-testing