
qa-use
qa-use Claude Code plugin
- GitHub stars
- 29
Install
/plugin install qa-use@desplega.aiRun it inside Claude Code after adding the marketplace with /plugin marketplace add desplega-ai/qa-use.
Contents
Discovered from sourceSkills 1
qa-use
E2E testing and browser automation for AI-driven development workflows.
Critical Insight: Plugin Commands as Shortcuts
For AI Harnesses (codex, opencode, etc.):
Plugin commands (slash commands like /qa-use:verify) are convenience shortcuts that wrap CLI workflows. Harnesses with only the Bash tool can access ALL functionality via CLI commands documented below.
Pattern throughout this document:
- CLI Workflow: Step-by-step CLI commands (works for ALL harnesses)
- Plugin Shortcut: Optional slash command (convenience)
Setup & Configuration
Before using any qa-use commands, verify configuration is in place:
# Check current configuration (no-op if already configured)
qa-use setup
# Configure with API key (validates against server)
qa-use setup --api-key <key>
# View full configuration details
qa-use info
Environment Variables (alternative to config file):
| Variable | Description |
|---|---|
QA_USE_API_KEY | API key for authentication |
QA_USE_REGION | Region: us (default) or auto |
QA_USE_API_URL | Override API base URL |
Config file: .qa-use.json in the project directory or ~/.qa-use.json in the home directory. Precedence: env vars > project .qa-use.json > ~/.qa-use.json.
If you encounter "API key not configured", 401, or auth errors: Run qa-use setup to check config state. NEVER fabricate or guess API keys.
Core Workflow
1. Browser Control & Session Lifecycle
CLI Workflow:
# Create browser session (returns immediately — runs detached in the background)
qa-use browser create --viewport desktop
# For localhost testing — auto-tunnels when base URL is localhost and API is remote.
# No flag needed for the common case:
qa-use browser create --no-headless http://localhost:3000
# Force a tunnel even in dev mode:
qa-use browser create --tunnel on --no-headless
# Opt out of auto-tunnel (e.g. backend is also local):
qa-use browser create --no-tunnel
# Navigate
qa-use browser goto https://example.com
# Snapshot to get element refs (ALWAYS do this before interacting)
qa-use browser snapshot
# Interact by ref
qa-use browser click e3
qa-use browser fill e5 "text"
# Close
qa-use browser close
Background session management:
qa-use browser create returns immediately — the actual browser + tunnel run in a detached child process so your terminal stays free. Manage sessions with:
qa-use browser status --list # Show all active sessions across processes
qa-use browser status # Details for the auto-resolved session
qa-use browser close <id> # Close a specific session
qa-use doctor # Reap stale sessions/tunnels (dead PIDs)
qa-use doctor --dry-run # Preview what would be cleaned
Tunnel commands:
Cross-process tunnel registry — multiple commands share a single tunnel per target:
qa-use tunnel start <url> # Acquire a tunnel (released immediately unless --hold)
qa-use tunnel start <url> --hold # Keep the tunnel up until Ctrl+C
qa-use tunnel ls # List active tunnels (target, public URL, refcount)
qa-use tunnel status <target> # Detail for a single tunnel
qa-use tunnel close <target> # Force-release a tunnel (kills detached holders)
Plugin Shortcut:
/qa-use:explore https://example.com
(Wraps create + goto + snapshot with autonomous exploration)
Critical: Always run snapshot before your first interaction on a page. Never guess element refs.
Snapshot Diff Feature (use it to avoid unnecessary snapshots): After each action (goto, click, fill, etc.), the browser automatically shows DOM changes:
- Summary: "5 elements added, 1 element modified"
- Added elements:
+ [e54] generic "Thanks for agreeing!"(green) - Modified elements:
~ [e18] checkbox "I agree..."with+attrs: checked, active(yellow) - Removed elements:
- [e99] button "Submit"(red)
When you can skip a full snapshot: If the diff output from your last action already shows the element ref you need to interact with next, use it directly — no need for an intermediate snapshot. For example, if clicking a button shows + [e54] button "Submit" in the diff, you can click e54 immediately.
When you still need a full snapshot: Run snapshot when you need to find elements that weren't in the diff (e.g., pre-existing elements you haven't interacted with yet), or when the diff was truncated (shows "... and N more changes").
2. Understanding Blocks
What are blocks?
Blocks are atomic recorded interactions from a browser session. They are:
- Automatically captured during any browser interaction (click, fill, goto, scroll, etc.)
- Stored server-side with the session
- Retrieved via
qa-use browser get-blocks - The foundation for test generation
Why blocks matter:
- Record-once, replay-many: Interactive recording becomes automated test
- AI-friendly: Agents can analyze blocks to understand user intent
- Version control: Blocks stored with session enable test iteration
- Bridge CLI → Tests: Natural workflow from exploration to automation
How blocks work:
# 1. Create session and interact (auto-tunnels localhost)
qa-use browser create --no-headless
qa-use browser goto https://example.com
qa-use browser snapshot # Returns: [ref=e1] button
qa-use browser click e1 # Records as block
qa-use browser fill e5 "text" # Records as block
# 2. Retrieve blocks (JSON array)
qa-use browser get-blocks
# Returns:
# [
# {"type": "goto", "url": "...", "timestamp": "..."},
# {"type": "click", "ref": "e1", "timestamp": "..."},
# {"type": "fill", "ref": "e5", "value": "text", "timestamp": "..."}
# ]
# 3. Generate test YAML from blocks
qa-use browser generate-test -n "my_test" -o qa-tests/my_test.yaml
# 4. Run generated test
qa-use test run my_test
Plugin Shortcut:
/qa-use:record start my_test
# ... perform interactions ...
/qa-use:record stop
(Wraps the interactive workflow with AI-powered test generation)
3. Test Management
CLI Workflow:
# Run test by name
qa-use test run login
# Run and save the (non-synced) local test to cloud
qa-use test run login --persist
# Validate syntax
qa-use test validate login
# Show test details
qa-use test info login
# List test runs
qa-use test runs --status failed
Plugin Shortcut:
/qa-use:test-run login
(Convenience shortcut for common test execution)
4. Test Variables (Imperative Edit)
Quick set/unset for the typed variables: block on a single test —
useful when you don't want to round-trip the full YAML.
CLI Workflow:
# Local YAML file — Document API preserves comments + key order
qa-use test vars list qa-tests/login.yaml
qa-use test vars list qa-tests/login.yaml --json
qa-use test vars set qa-tests/login.yaml --key user --value alice
qa-use test vars set qa-tests/login.yaml --key url --value https://x \
--type url --lifetime all
qa-use test vars set qa-tests/login.yaml --key password --value hunter2 --sensitive
qa-use test vars set qa-tests/login.yaml --key password --sensitive # preserves stored value
qa-use test vars unset qa-tests/login.yaml --key user
# Remote --id fallback — exports YAML, mutates, re-imports (best-effort RMW)
qa-use test vars list --id <uuid>
qa-use test vars set --id <uuid> --key user --value alice
qa-use test vars unset --id <uuid> --key user
Rules:
- Mutual exclusion: pass either
<file>or--id, not both. Neither → exit 1. --idrequires a full UUID (useqa-use test list --query <name>to find one).- Form upgrade: passing only
--key/--valuewrites simple form (key: value). Any of--type/--lifetime/--context/--sensitiveupgrades to full form ({ value, type, lifetime, context, is_sensitive }). - Sensitive-preserve: on an existing sensitive var,
--sensitivewithout--valuekeeps the stored value. On a new key, that combination errors out. --jsonredaction: sensitive entries omit thevaluekey entirely; theis_sensitive: trueflag is the redaction signal.- Remote round-trip caveat: comment/key-order preservation only applies to the local-file path. The server normalizes formatting on import.
No Plugin Shortcut - Use CLI commands directly.
5. Test Sync Lifecycle
CLI Workflow:
# Pull tests from cloud
qa-use test sync pull
# Push all local tests to cloud
qa-use test sync push --all
# Push specific test
qa-use test sync push --id <uuid>
# Force push (overwrite conflicts)
qa-use test sync push --force
# Compare local vs cloud
qa-use test diff login.yaml
Persist vs Sync:
A local test is synced when its YAML has both an id: and a version_hash:
(these are written back by test sync push/pull). --persist on test run
and qa-use test sync are related but not the same:
| Local file state | persist | What happens at run time |
|---|---|---|
| Non-synced | false (default) | Runs locally; nothing saved to cloud. Re-run with --persist or use test sync push to persist. |
| Non-synced | true | Test is uploaded as a new cloud entry after the run. Re-running like this creates duplicates — prefer test sync push once the file tracks the cloud id. |
| Synced | false | Runs against the cloud-tracked definition; no extra write. |
| Synced | true | Cloud definition is upserted (may overwrite newer cloud edits). Use test sync push/pull for explicit version control. |
Rule of thumb: test sync push/pull is the deliberate path. Reserve --persist
(or defaults.persist: true in .qa-use.json) for one-off uploads of brand-new
local tests.
No Plugin Shortcut - Use CLI commands directly
Essential Commands
Browser Session Management
| Command | Description |
|---|---|
qa-use browser create | Create remote browser session |
qa-use browser create <url> | Create session and navigate to URL |
qa-use browser create --tunnel [auto|on|off] | Tunnel mode — default auto (localhost + remote API). --no-tunnel is sugar for off. |
qa-use browser create --no-headless | Show browser window (paired with a local/tunnel browser) |
qa-use browser create --viewport <size> | Set viewport: desktop, tablet, mobile |
qa-use browser create --ws-url <url> | Connect to existing WebSocket browser |
qa-use browser create --after-test-id <uuid> | Run a test first, then become interactive |
qa-use browser create --var <key=value> | Override app config variables (repeatable) |
qa-use browser list | List active sessions |
qa-use browser status | Show current session details (app_url, recording_url, etc.) |
qa-use browser status --list | Show all active sessions across processes |
qa-use browser close | Close active session |
qa-use browser close <id> | Close a specific session by id |
qa-use doctor | Reap stale sessions/tunnels (dead PIDs) |
qa-use tunnel ls | List active tunnels in the registry |
qa-use tunnel start <url> --hold | Hold a public tunnel for external consumers |
Sessions auto-persist in ~/.qa-use.json. One active session = no -s flag needed. browser create returns immediately — the browser + tunnel run in a detached child. Use qa-use doctor if stale state accumulates.
Navigation
| Command | Description |
|---|---|
qa-use browser goto <url> | Navigate to URL |
qa-use browser back | Go back |
qa-use browser forward | Go forward |
qa-use browser reload | Reload page |
Element Interaction
| Command | Description |
|---|---|
qa-use browser click <ref> | Click element by ref |
qa-use browser click --text "Button" | Click by semantic description |
qa-use browser fill <ref> "value" | Fill input field |
qa-use browser type <ref> "text" | Type with delays (for autocomplete) |
qa-use browser press <key> | Press key (e.g., Enter, Tab) |
qa-use browser check <ref> | Check checkbox |
qa-use browser uncheck <ref> | Uncheck checkbox |
qa-use browser select <ref> "option" | Select dropdown option |
qa-use browser hover <ref> | Hover over element |
qa-use browser scroll down 500 | Scroll by pixels |
qa-use browser scroll-into-view <ref> | Scroll element into view |
qa-use browser drag <ref> --target <ref> | Drag element to target |
qa-use browser mfa-totp [ref] <secret> | Generate TOTP code (optionally fill) |
qa-use browser upload <ref> <file>... | Upload file(s) to input (base64-encoded, works remote & tunnel) |
Inspection & Snapshot Diff
| Command | Description |
|---|---|
qa-use browser snapshot | Get full ARIA tree with element refs (use only when diff output is insufficient) |
qa-use browser url | Get current URL |
qa-use browser screenshot | Save screenshot.png |
qa-use browser screenshot file.png | Save to custom path |
qa-use browser screenshot --base64 | Output base64 to stdout |
qa-use browser evaluate <expression> | Execute JavaScript in browser context |
The snapshot-diff feature automatically displays DOM changes after each browser action:
- Added elements: Shown with
+prefix and green color — these refs are immediately usable - Modified elements: Shown with
~prefix and yellow color, including attribute changes (+attrs: checked) - Removed elements: Shown with
-prefix and red color — do NOT use these refs
Downloads: When an action triggers a file download (e.g., clicking a download link), the response includes download info: filename, size, and a presigned URL. Use qa-use browser downloads to list all downloads or --save <dir> to save them locally.
Use diff output to interact with newly appeared elements directly, without running a full snapshot first.
Test Operations
| Command | Description |
|---|---|
qa-use test run <name> | Run test by name |
qa-use test run --all | Run all tests |
qa-use test run <name> --tunnel [mode] | Override tunnel mode (auto, on, off). --no-tunnel is sugar for off. Bare --tunnel is sugar for on. |
qa-use test run <name> --download | Download assets to /tmp/qa-use/downloads/ |
qa-use test run <name> --var key=value | Override variable |
qa-use test validate <name> | Validate test syntax |
qa-use test list | List available tests |
qa-use test info <name> | Show test details (steps, tags, description) |
qa-use test info --id <uuid> | Show cloud test details by ID |
qa-use test runs [name] | List test run history |
qa-use test runs --id <uuid> | Filter runs by test ID |
qa-use test runs --status failed | Filter runs by status |
qa-use test init | Initialize test directory |
qa-use test sync pull | Pull tests from cloud |
qa-use test sync push --all | Push all local tests to cloud |
qa-use test sync push --id <uuid> | Push specific test |
qa-use test sync push --force | Push tests, overwriting conflicts |
qa-use test diff <file> | Compare local vs cloud test |
qa-use test schema [path] | View test definition schema |
API Operations (Dynamic OpenAPI)
qa-use api dynamically discovers operations from /api/v1/openapi.json and caches metadata locally for offline fallback.
| Command | Description |
|---|---|
qa-use api | Show help and available subcommands |
qa-use api ls | List available /api/v1/* routes from OpenAPI |
qa-use api ls --refresh | Force refresh OpenAPI cache |
qa-use api ls --offline | Use cached OpenAPI metadata only |
qa-use api info /api/v1/<route> | Show route details: parameters, request body, responses |
qa-use api info /api/v1/<route> -X POST | Show info for specific HTTP method |
qa-use api info /api/v1/<route> --json | Route info as JSON |
qa-use api examples | Show usage examples |
qa-use api openapi | Print OpenAPI spec URL |
qa-use api openapi --raw | Dump full OpenAPI spec as JSON |
qa-use api /api/v1/tests | Call endpoint (method inferred when possible) |
qa-use api -X GET /api/v1/test-runs -f limit=5 | GET with query fields |
qa-use api -X POST /api/v1/tests-actions/run --input body.json | POST with JSON body file |
qa-use api -X GET /api/v1/test-runs/<id> | Fetch detail endpoint by ID |
No Plugin Shortcut - Use CLI commands directly.
API Checks And Check Schedules
Remote API checks are managed through first-class commands. They call the desplega.ai API directly; they do not run checks locally or create browser sessions.
| Command | Description |
|---|---|
qa-use check list --app-config <id> | List remote API checks |
qa-use check info <check-id> | Inspect one check, including dependencies and captures |
qa-use check create --name <name> --app-config <id> --config check.json | Create a check |
qa-use check update <check-id> --depends-on <id> --alias <name> | Update dependency-chain metadata |
qa-use check delete <check-id> --force | Delete a check |
qa-use check-schedule list --app-config <id> | List remote check schedules |
qa-use check-schedule create --name <name> --app-config <id> --cron "*/15 * * * *" --check <id> | Create an ordered schedule |
qa-use check-schedule run <schedule-id> --var env=staging | Run a schedule as a remote variable-passing chain |
Common flow:
qa-use check create \
--name "Auth token" \
--app-config <app-config-id> \
--config auth-check.json \
--alias auth \
--capture token=$.access_token
qa-use check update <claim-check-id> \
--depends-on <auth-check-id> \
--alias claim
qa-use check-schedule create \
--name "Claims chain" \
--app-config <app-config-id> \
--cron "*/15 * * * *" \
--check <auth-check-id> \
--check <claim-check-id>
qa-use check-schedule run <schedule-id> --var env=staging --var claim_id=123
There is no standalone qa-use check run <check-id> command yet because the
public API currently documents schedule runs, not individual check-run actions.
Use qa-use api info /api/v1/checks -X POST for the current check payload
contract, and see references/checks.md for examples.
No Plugin Shortcut - Use CLI commands directly.
Logs & Debugging
| Command | Description |
|---|---|
qa-use browser logs console | View console logs from session |
qa-use browser logs console -s <id> | View logs from specific/closed session |
qa-use browser logs network | View network request logs |
qa-use browser logs network -s <id> | View network logs from specific session |
qa-use browser downloads | List downloaded files from session |
qa-use browser downloads --save <dir> | Save downloaded files to local directory |
qa-use browser downloads --json | Output download info as JSON |
Test Generation
| Command | Description |
|---|---|
qa-use browser generate-test | Generate test YAML from recorded session |
qa-use browser generate-test -s <id> | Generate from specific session |
qa-use browser generate-test -n <name> | Specify test name |
qa-use browser generate-test -o <path> | Specify output path |
qa-use browser get-blocks | Get recorded interaction blocks (JSON) |
Waiting
| Command | Description |
|---|---|
qa-use browser wait <ms> | Fixed wait |
qa-use browser wait-for-selector ".class" | Wait for selector |
qa-use browser wait-for-load | Wait for page load |
Variable Overrides
Use --var to override app config variables at runtime. Common variables:
| Variable | Description |
|---|---|
base_url | Base URL for the app (e.g., preview deployment URL) |
login_url | Login page URL |
login_username | Username/email for authentication |
login_password | Password for authentication |
Example with ephemeral preview URL:
qa-use browser create --after-test-id <login-test-uuid> \
--var base_url=https://preview-123.example.com \
--var login_url=https://preview-123.example.com/auth/login
Common Patterns
Pattern 1: Feature Verification
CLI Workflow:
# 1. Search for existing test
qa-use test list | grep "login"
# 2. Run test
qa-use test run login
# 3. Debug failures
qa-use browser logs console
Plugin Shortcut:
/qa-use:verify "login works with valid credentials"
(Wraps the above CLI workflow with AI-powered test discovery and analysis)
Pattern 2: Record & Generate Test
CLI Workflow:
# 1. Create session (auto-tunnels localhost targets)
qa-use browser create --no-headless
# 2. Navigate and interact
qa-use browser goto https://example.com
qa-use browser snapshot
qa-use browser click e1
qa-use browser fill e5 "test"
# 3. Generate test from blocks
qa-use browser get-blocks
qa-use browser generate-test -n "my_test"
# 4. Run test
qa-use test run my_test
Plugin Shortcut:
/qa-use:record start my_test
# ... perform interactions ...
/qa-use:record stop
Pattern 3: Authenticated Exploration
CLI Workflow:
# Create session that runs login test first
qa-use browser create --after-test-id <login-test-uuid>
# Session now authenticated, explore
qa-use browser goto /dashboard
qa-use browser snapshot
Plugin Shortcut:
/qa-use:explore /dashboard
(Automatically handles auth detection and session creation)
Pattern 4: Edit Existing Test
CLI Workflow:
# 1. Open test file in editor
vim qa-tests/login.yaml
# 2. Validate syntax
qa-use test validate login
# 3. Run to verify
qa-use test run login
Plugin Shortcut:
/qa-use:record edit login
(AI-assisted editing with validation)
Pattern 5: Using Snapshot Diff to Avoid Unnecessary Snapshots
CLI Workflow:
# Create session and navigate
qa-use browser create --no-headless
qa-use browser goto https://evals.desplega.ai/checkboxes
# goto shows diff — initial page load shows all elements:
# Changes: 45 elements added
# + [e18] checkbox "I agree to the terms and conditions"
# + [e19] generic "I agree to the terms and conditions"
# ✅ Use ref from diff directly — no snapshot needed!
qa-use browser click e18
# Diff shows what changed:
# Changes: 5 elements added, 1 element modified
# + [e54] generic "Thanks for agreeing!"
# + [e55] link "Terms and Conditions"
# ~ [e18] checkbox "I agree to the terms and conditions"
# +attrs: active, checked
# ✅ Can click e55 directly from diff output — no snapshot needed!
qa-use browser click e55
# ❌ Need to find an element NOT in the diff? Now run snapshot:
qa-use browser snapshot
Key principle: Use diff output as your primary source of element refs after actions. Only fall back to snapshot when you need to find elements that weren't in the diff.
Benefits:
- Fewer API calls = faster automation
- Diff refs are always fresh (just returned from the server)
- Instantly see what changed (new elements, attribute changes, removals)
No Plugin Shortcut - Automatic feature in all browser commands
CI/CD Integration
Running Tests in CI
Environment Variables:
export QA_USE_API_KEY="your-api-key"
export QA_USE_REGION="us" # Optional: "us" or "auto"
Basic Test Execution:
# Run all tests
qa-use test run --all
# Run specific tag
qa-use test run --tag smoke
# Exit codes: 0 = pass, 1 = fail
GitHub Actions Example
name: QA Tests
on: [push, pull_request]
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- uses: actions/setup-node@v3
with:
node-version: '20'
- name: Install qa-use
run: npm install -g @desplega.ai/qa-use
- name: Run tests
run: qa-use test run --all
env:
QA_USE_API_KEY: ${{ secrets.QA_USE_API_KEY }}
Test Artifacts
Screenshots:
- Automatically saved on failure
- Location:
/tmp/qa-use/downloads/(local) or cloud (remote)
Logs:
- Console logs:
qa-use browser logs console -s <session-id> - Network logs:
qa-use browser logs network -s <session-id>
Advanced Topics
Localhost Testing (Auto-Tunnel)
qa-use auto-tunnels localhost targets when the API is remote. No flag required for the common case:
qa-use browser create --no-headless http://localhost:3000
qa-use test run my_test # auto-tunnels if base_url is localhost
Tri-state --tunnel flag:
| Value | Behavior |
|---|---|
auto (default) | Tunnel iff base URL is localhost AND API URL is remote |
on (or bare --tunnel) | Force a tunnel even in dev mode |
off (or --no-tunnel) | Never tunnel |
Testing localhost (http://localhost:3000)?
├─ API remote (default) → auto-tunnels. No flag needed.
├─ API also local (dev) → no tunnel by default. Use --tunnel on to force.
└─ Public URL target → no tunnel (remote cloud browser)
Plugin shortcuts handle tunnel detection automatically:
/qa-use:explore http://localhost:3000
/qa-use:record start local_test
See references/localhost-testing.md for troubleshooting.
Session Persistence
Sessions are stored in ~/.qa-use.json and have:
- TTL: 30 minutes (default)
- Auto-resolve: One active session = no
-sflag needed - Cleanup: Automatic on timeout or explicit
browser close
Block Limitations
What's captured:
- goto, click, fill, type, check, uncheck, select, hover
- scroll, scroll-into-view, drag, upload, press
What's NOT captured:
- Assertions (must be added manually)
- Waits (inferred from timing, may need adjustment)
- Complex interactions (multi-drag, hover sequences)
Manual editing: Edit generated YAML to add assertions and refine selectors.
WebSocket Sessions
Sharing sessions across processes:
# Process 1: Create session (auto-tunnels if target is localhost + API remote)
qa-use browser create http://localhost:3000
# Output: ws://localhost:12345/browser/abc123
# Process 2: Connect to session
qa-use browser goto https://example.com --ws-url ws://localhost:12345/browser/abc123
Deep-Dive References
Access any reference at runtime via the CLI: qa-use docs <topic>
| Topic | CLI Command | Description |
|---|---|---|
| browser-commands.md | qa-use docs browser-commands | Complete browser CLI reference with all flags |
| checks.md | qa-use docs checks | API checks and check schedule workflows |
| test-format.md | qa-use docs test-format | Full test YAML specification |
| localhost-testing.md | qa-use docs localhost-testing | Tunnel setup for local development |
| failure-debugging.md | qa-use docs failure-debugging | Failure classification and diagnostics |
| ci.md | qa-use docs ci | CI/CD integration patterns and examples |
Use qa-use docs --list to discover all available topics and templates.
Templates
| Template | Description |
|---|---|
| basic-test.yaml | Simple navigation and assertion |
| auth-flow.yaml | Login flow with credentials |
| form-test.yaml | Form submission with validation |
Test Format Overview
name: Login Test
description: Validates login functionality with valid credentials
tags:
- smoke
- auth
app_config: <app-config-id>
variables:
email: test@example.com
password: secret123
depends_on: setup-test # Optional
steps:
- action: goto
url: /login
- action: fill
target: email input
value: $email
- action: click
target: login button
- action: to_be_visible
target: dashboard
See references/test-format.md for complete specification.
Common Mistakes
| ❌ Wrong | ✅ Correct |
|---|---|
browser navigate <url> | browser goto <url> |
browser destroy | browser close |
browser close <session-id> | browser close |
| Guessing element refs | Use refs from diff output or snapshot |
Running snapshot after every action | Use diff output; only snapshot when needed |
Forcing --tunnel in dev (both local) | Rely on auto-mode, or use --tunnel on explicitly |
test sync --pull | test sync pull (subcommand, not flag) |
test sync --push | test sync push (subcommand, not flag) |
Troubleshooting
When stuck or encountering unexpected errors, use the built-in documentation:
# Check configuration state
qa-use setup
# Browse main documentation
qa-use docs
# List all available topics
qa-use docs --list
# Access specific topic
qa-use docs <topic>
| Situation | Command |
|---|---|
| Auth / API key errors | qa-use setup then qa-use docs |
| Unknown browser command | qa-use docs browser-commands |
| Test failures | qa-use docs failure-debugging |
| Localhost / tunnel issues | qa-use docs localhost-testing |
| Test YAML syntax | qa-use docs test-format |
| API checks / schedules | qa-use docs checks |
| CI/CD setup | qa-use docs ci |
Key rules:
- ALWAYS consult
qa-use docsbefore improvising workarounds - NEVER fabricate API keys, tokens, URLs, or credentials
- If
qa-use setupshows no config, report it — don't guess
npx Alternative
All commands use qa-use assuming global install. For one-off use:
npx @desplega.ai/qa-use browser <command>
Commands 6
/qa-use:explore
Explore a web page or complete a navigation goal.
Invokes skill: qa-use
Arguments
| Argument | Description |
|---|---|
url | URL to explore (e.g., https://example.com) |
goal | Navigation goal (e.g., "find the pricing page") |
What Happens
- Creates browser session (or uses existing one)
- Navigates to the URL
- Analyzes page using accessibility snapshots
- Reports elements, navigation options, content found
Examples
/qa-use:explore https://example.com
/qa-use:explore "find the pricing page"
/qa-use:explore https://myapp.com/dashboard "find user settings"
Starting After Login
Many pages require authentication. Use --after-test-id when creating the browser session to start from a logged-in state:
# Create session that runs login test first
qa-use browser create --after-test-id <login-test-uuid>
# Then explore the authenticated area
/qa-use:explore https://myapp.com/dashboard
This is extremely useful for:
- Exploring authenticated pages - bypass login walls automatically
- Testing user-specific features - start as a logged-in user
- Complex setup flows - run a setup test, then explore manually
To get test UUIDs, use qa-use test run --list or check your tests in the desplega.ai dashboard.
/qa-use:record
Record browser interactions and generate test YAML, or edit existing tests with AI assistance.
Invokes skill: qa-use
Arguments
| Argument | Description |
|---|---|
start [name] | Start recording with optional test name |
edit <test-name> | AI-assisted editing of existing test |
stop | Stop recording and generate test YAML |
What Happens
Recording Mode (start/stop)
- start: Creates browser session, enters recording mode
- actions: You perform browser commands, they're tracked
- stop: Generates test YAML with variables and semantic descriptions
- save: Writes to
qa-tests/<name>.yaml
Edit Mode (edit)
- Loads existing test definition
- Understands your desired changes
- Applies modifications
- Validates and saves with confirmation
Examples
Recording a new test
/qa-use:record start login-test
# ... perform browser actions ...
/qa-use:record stop
Editing an existing test
/qa-use:record edit login-test
Recording from Logged-In State
To record a test that assumes the user is already logged in, first create a session with --after-test-id:
# Create session that runs login test first
qa-use browser create --after-test-id <login-test-uuid>
# Then start recording from the authenticated state
/qa-use:record start dashboard-test
This is useful for recording tests that depend on authentication without including login steps in every test.
/qa-use:test-init
Initialize the test directory with an example test file.
Invokes skill: qa-use
What Happens
- Creates
qa-tests/directory withexample.yaml - Optionally creates
.qa-use.jsonconfig file - Shows next steps for running your first test
Example
/qa-use:test-init
/qa-use:test-run
Execute E2E tests with real-time progress monitoring.
Invokes skill: qa-use
Arguments
| Argument | Description |
|---|---|
test-name | Test to run (omit to list available tests) |
--tunnel | Use local browser with tunnel (required for localhost) |
--headful | Show browser window |
--download | Download assets to /tmp/qa-use/downloads/ |
--var key=value | Override variable |
Examples
/qa-use:test-run login
/qa-use:test-run checkout --download
/qa-use:test-run --all
/qa-use:verify-pr
Verify a pull request's frontend changes through automated browser testing.
Invokes skill: qa-use
Arguments
| Argument | Description |
|---|---|
pr | PR number (e.g., #123), URL, or omit to infer from current branch |
--base-url <url> | Override base URL for ephemeral/preview deployments |
What Happens
- Spawns a single
pr-verifieragent in the background - Agent analyzes the PR, identifies changed routes
- Agent creates ONE browser session and verifies all features sequentially
- Agent generates a concise visual report with inline screenshots
- Report saved to
/tmp/pr-verify-report-<pr>.md
You can continue working while verification runs in the background.
Examples
/qa-use:verify-pr #123
/qa-use:verify-pr https://github.com/owner/repo/pull/123
/qa-use:verify-pr # infer from current branch
/qa-use:verify-pr #123 --base-url https://preview-123.example.com
Workflow
Step 1: Parse Arguments
Extract from arguments:
pr: PR number/URL or empty (agent will infer from branch)base_url: Optional URL override from--base-urlflag
Step 2: Detect Environment
Check if running in CI:
# CI environment detected if either is "true"
echo $CI
echo $GITHUB_ACTIONS
Step 3: Spawn PR-Verifier Agent
In CI (CI=true or GITHUB_ACTIONS=true): Run synchronously and wait for completion.
Task(
subagent_type: "qa-use:pr-verifier",
run_in_background: false, # MUST wait in CI
prompt: "Verify PR <pr> with base_url=<base_url>"
)
Locally (interactive): Run in background so user can continue working.
Task(
subagent_type: "qa-use:pr-verifier",
run_in_background: true,
prompt: "Verify PR <pr> with base_url=<base_url>"
)
Step 4: Output
In CI: Wait for agent to complete, then output the report path and suggest posting to PR.
Locally: Return immediately with:
🚀 PR verification started in background.
Report will be at: /tmp/pr-verify-report-<pr>.md
To post: gh pr comment <pr> --body-file /tmp/pr-verify-report-<pr>.md
Report Format
The agent generates a concise visual report:
## PR #123 Verification
**Branch**: `feature-branch` | **Verified**: 2024-01-25 14:30
### Summary
✅ 2 features verified | ⚠️ 1 issue found
---
### /autocomplete ✅
[Session](app_url) | [Recording](recording_url)

- Search returns results with debounce
- Multi-select chips work
---
### /home ⚠️
[Session](app_url) | [Recording](recording_url)

- Navigation link visible
- ⚠️ Slow load time (3s)
Prerequisites
- qa-use CLI configured: API key set via
QA_USE_API_KEYor~/.qa-use.json - GitHub CLI (
gh) available: For PR context - App accessible: Running locally or via preview URL
CI Integration
See references/ci.md for GitHub Actions setup.
/qa-use:verify
Verify a feature works through automated browser testing.
Invokes skill: qa-use
Arguments
| Argument | Description |
|---|---|
description | What to verify (e.g., "login works with valid credentials") |
What Happens
- Searches for existing tests matching your description
- If no test exists, offers to explore and create one
- Runs the test
- Reports results with specific fix recommendations
Examples
/qa-use:verify "login works with valid credentials"
/qa-use:verify "checkout flow completes successfully"
/qa-use:verify "form shows validation errors"
Agents 5
Browser Navigator
You are an autonomous browser agent that completes web navigation tasks.
Purpose
Execute multi-step browsing tasks by cycling through snapshot → analyze → action until goal is achieved.
When Spawned
- By
feature-verifyskill to explore a feature before testing - By user for "find X on this page" tasks
- For reconnaissance before test authoring
Input Format
{
"goal": "find the pricing page and identify plan options",
"start_url": "https://example.com",
"max_steps": 10
}
Methodology
-
Check prerequisites
- Run:
qa-use setup(no args) — if configured, prints current config and exits - If NOT configured: report "qa-use is not configured. Run
qa-use setup --api-key <key>to configure." and stop - NEVER fabricate or guess API keys
- Run:
-
Ensure browser session exists
- Check for active session:
qa-use browser list - If none exists, create one with the start URL:
qa-use browser create --viewport desktop <start_url>
- Check for active session:
-
Navigate to start_url (only if reusing an existing session)
- Run:
qa-use browser goto <start_url>
- Run:
-
Loop until goal achieved or max_steps a. Get page state:
- First iteration or after navigation: Run
qa-use browser snapshot --interactive --max-depth 5 - After an action with diff output: Use the diff output directly if it contains the refs you need. Only run
snapshotif you need to find elements not shown in the diff. b. Analyze: Am I at the goal? What actions could get me closer? c. Execute: Run best action (click, scroll, fill) d. Check diff: Review the snapshot diff output. Did the action succeed? Are target elements visible in the diff? If yes, proceed without a full snapshot.
- First iteration or after navigation: Run
-
Return structured findings
Output Format
{
"success": true,
"goal_achieved": true,
"final_url": "https://example.com/pricing",
"findings": {
"plans": ["Free", "Pro ($20/mo)", "Enterprise"],
"cta_buttons": ["Start Free Trial", "Contact Sales"]
},
"steps_taken": [
{"action": "click", "target": "Pricing link", "result": "navigated to /pricing"},
{"action": "scroll", "direction": "down", "result": "revealed plan cards"}
],
"page_summary": "Pricing page with 3 plan tiers and comparison table"
}
Navigation Log Format
When reporting progress, use this format:
## Navigation Log
**Goal**: Find the pricing page and extract plan names
**Step 1**: Navigate to homepage
- Command: `qa-use browser goto https://example.com`
- Result: ✓ Loaded
**Step 2**: Get page snapshot
- Found: navigation menu with [ref=e5] "Pricing" link
**Step 3**: Click pricing link
- Command: `qa-use browser click e5`
- Result: ✓ Navigated to /pricing
**Step 4**: Get pricing snapshot
- Found: 3 pricing cards with plan names
## Result
Found 3 plans: Free, Pro ($20/mo), Enterprise (Contact)
Error Handling
Stuck Detection
If the same page state persists for 3 consecutive actions:
- Try alternative approach (scroll, look for different element)
- Report partial findings and blockers
Login Walls
If navigation requires authentication:
- Report: "Login required. Unable to proceed without credentials."
- Provide: current URL, what was visible before login wall
- DO NOT attempt to guess or bypass credentials
- Suggest using --after-test-id: If a login test exists, recommend creating a new session with:
This runs the login test first, leaving the session in an authenticated state.qa-use browser create --after-test-id <login-test-uuid>
CAPTCHAs
If CAPTCHA is encountered:
- Report: "CAPTCHA detected. Cannot proceed automatically."
- Provide: screenshot if available
- DO NOT attempt to solve or bypass CAPTCHA
Configuration / Auth Errors
If any command fails with "API key not configured", "401", or "unauthorized":
- Run:
qa-use setupto check current configuration state - Run:
qa-use docsto review environment variable documentation - Report the error clearly — do NOT attempt to fix by guessing credentials
- NEVER fabricate API keys, tokens, or passwords
Page Load Failures
If page fails to load:
- Retry once after brief wait
- Report: "Page failed to load: "
- Suggest checking network/URL
Self-Help & Troubleshooting
When stuck or encountering unexpected errors, use the built-in documentation before guessing:
| Situation | Command | What it provides |
|---|---|---|
| Configuration issues | qa-use setup | Shows current config state (API key, test dir) |
| Environment variables | qa-use docs | Main docs with env var reference (QA_USE_API_KEY, etc.) |
| Unknown browser command | qa-use docs browser-commands | Complete browser CLI reference with all flags |
| Localhost/tunnel problems | qa-use docs localhost-testing | Tunnel setup and troubleshooting |
| Test failures | qa-use docs failure-debugging | Failure classification and diagnostics |
| Discover all topics | qa-use docs --list | Lists all available documentation topics |
Key rules:
- ALWAYS consult
qa-use docsbefore improvising workarounds - NEVER hallucinate API keys, tokens, URLs, or credentials
- If
qa-use setupshows no config, report it and stop — don't try to fix it yourself
Constraints
- ALWAYS create session first if none exists
- ALWAYS run
snapshotbefore your first interaction on a new page - After actions, use the diff output to find refs — only run
snapshotagain if the diff doesn't contain the element you need - NEVER click a ref that was shown as removed (
-) in a diff - NEVER guess refs — they must come from either a snapshot or a diff
- Report honestly when stuck (login required, CAPTCHA, etc.)
- Close session when task complete (unless parent skill will continue using it)
- Maximum 10 steps per navigation goal by default
- If goal cannot be achieved, return partial findings
Browser Recorder
Observes browser commands and generates qa-use test YAML definitions.
Purpose
Track browser interactions and generate test YAML with:
- Variable extraction for repeated values
- Secret detection for sensitive data
- Assertion inference from URL changes and element waits
- Cleanup of redundant steps
When Spawned
- By
feature-verifyskill after exploration to generate test YAML - By
test-authoringskill for assisted test creation - By user for "record this flow" requests
Input Format
{
"test_name": "login-flow",
"description": "Verify login with valid credentials",
"session_id": "abc123",
"record_mode": "capture"
}
Fields:
test_name: Name for the generated test (used as filename)description: Human-readable description of what the test verifiessession_id: Existing browser session to attach to (optional - create new if not provided)record_mode:capture(default) orreplay(to verify recording works)
Recording Process
-
Attach to browser session
- If session_id provided, verify it exists via
qa-use browser list - If no session, announce: "No active session. Please create one or I'll create one for you."
- If session_id provided, verify it exists via
-
Announce recording start
📹 Recording started for test: login-flow Perform the actions you want to test. I'll track: - Navigation (goto, back, forward) - Interactions (click, fill, type, press) - Assertions (wait commands, URL changes) Say "stop recording" when done. -
Track browser commands Monitor all browser commands executed and map to test steps:
Browser Command Test Step goto <url>action: goto, url: <url>click <ref>action: click, target: <element description>fill <ref> "value"action: fill, target: <element desc>, value: <value>type <ref> "text"action: type, target: <element desc>, value: <text>press <key>action: press, key: <key>check <ref>action: check, target: <element desc>select <ref> "opt"action: select, target: <element desc>, value: <opt>wait-for-selectoraction: wait_for_selector, selector: <selector>wait-for-loadaction: wait_for_load, state: <state> -
Get element descriptions from snapshots
- After each action, note the element's accessible name/role from snapshot
- Use semantic descriptions: "email input", "Submit button", "search field"
-
On "stop recording" or explicit end
- Compile all tracked steps
- Apply smart features (variables, secrets, assertions, cleanup)
- Generate and display YAML
- Ask user to confirm before saving
Output Format
Generated YAML:
name: login-flow
description: Verify login with valid credentials
variables:
email: test@example.com
password: "********" # marked as secret
steps:
- action: goto
url: /login
- action: fill
target: email input
value: $email
- action: fill
target: password input
value: $password
- action: click
target: Sign In button
- action: wait_for_url
url: /dashboard
- action: to_be_visible
target: Welcome message
Default save location: qa-tests/<test_name>.yaml
Smart Features
Variable Extraction
Extract repeated values into variables:
- Same value used in multiple steps → create variable
- Values matching patterns (emails, URLs) → create variable
- Variable names derived from context (target field name)
Secret Detection
Automatically mark sensitive values as secrets:
- Password fields → mask value, mark as secret
- Token/API key patterns → mask value, mark as secret
- Fields with
type="password"→ mask value
Assertion Inference
Automatically add assertions based on observed behavior:
- URL change after action → add
wait_for_url - Element appears after action → add
to_be_visible - Page title changes → can add title assertion
Cleanup
Remove redundant steps:
- Consecutive duplicate waits → keep last only
- Multiple small waits → consolidate into single wait
- Redundant scrolls → remove intermediate scrolls
Constraints
- ALWAYS get user confirmation before writing test file
- PRESERVE existing test structure if editing an existing test
- USE semantic element descriptions, not raw refs
- MARK sensitive data as secrets (passwords, tokens)
- SAVE tests to
qa-tests/directory by default - FOLLOW existing test format in the project (check for
qa-tests/*.yamlexamples)
Troubleshooting
If commands fail with configuration or auth errors ("API key not configured", 401, unauthorized):
- Run
qa-use setupto verify current configuration state - Run
qa-use docsfor environment variable and setup documentation - NEVER guess or fabricate API keys, tokens, or credentials
Example Session
User: /qa-use:record start login-test
Agent: 📹 Recording started for test: login-test
Perform the actions you want to test...
User: qa-use browser goto http://localhost:3000/login
Agent: ✓ Recorded: goto /login
User: qa-use browser snapshot
Agent: Available elements:
- textbox "Email" [ref=e3]
- textbox "Password" [ref=e4]
- button "Sign In" [ref=e5]
User: qa-use browser fill e3 "user@example.com"
Agent: ✓ Recorded: fill "email input" with "user@example.com"
User: qa-use browser fill e4 "secret123"
Agent: ✓ Recorded: fill "password input" with ******** (marked as secret)
User: qa-use browser click e5
Agent: ✓ Recorded: click "Sign In button"
✓ Detected URL change: /login → /dashboard (adding assertion)
User: stop recording
Agent: 📼 Recording complete! Generated test:
[shows YAML preview]
Save to qa-tests/login-test.yaml? [Y/n]
PR Verifier Agent
You are an autonomous PR verification agent that analyzes a PR's frontend changes, creates a browser session, verifies all features sequentially, and generates a concise visual report.
Input
You receive:
pr: PR number, URL, or empty (infer from branch)base_url: Optional override URL for preview deployments
Workflow
Phase 1: Context Gathering
1.1 Parse PR Context
# If pr argument provided, use it; otherwise infer from current branch
gh pr view <pr> --json number,title,headRefName,url
Store: PR_NUMBER, PR_TITLE, BRANCH, PR_URL
1.2 Get PR Diff
gh pr diff <PR_NUMBER> --name-only # List of changed files
gh pr diff <PR_NUMBER> # Full diff for analysis
1.3 Analyze Changes
Filter for frontend files (.tsx, .jsx, .ts, .js, .vue, .svelte, .css, .scss).
Map file paths to routes:
src/pages/checkout.tsx→/checkoutsrc/app/settings/page.tsx→/settingssrc/components/Button.tsx→ component (find usage)
Build feature list:
FEATURES = [
{ id: "checkout", route: "/checkout", description: "..." },
{ id: "settings", route: "/settings", description: "..." }
]
1.4 Discover Login Test
qa-use test list --cloud --limit 1000 | grep -i -E "login|auth"
Store: LOGIN_TEST_ID (first match, or empty if none)
Phase 2: Browser Session Setup
2.1 Create Single Session
# With login test (preferred)
qa-use browser create --after-test-id <LOGIN_TEST_ID> --viewport desktop \
--var base_url=<base_url> <base_url>
# Without login test (fallback)
qa-use browser create --viewport desktop <base_url>
Store: SESSION_ID
2.2 Get Session Info
qa-use browser status --json
Store: APP_URL
Phase 3: Sequential Feature Verification
For EACH feature in FEATURES:
3.1 Navigate to Route
qa-use browser goto <base_url><route>
Wait for page load.
3.2 Get Page State and Verify
After goto, the snapshot diff output already shows page elements. Use diff refs directly when possible:
# goto already returns diff — use those refs first
# Only run snapshot if you need elements not shown in the diff:
qa-use browser snapshot --interactive
Based on the feature description and diff context:
- Identify key interactive elements from diff output (or snapshot if needed)
- Perform verification actions (click, fill, scroll)
- Use diff output from each action to check for expected behavior — avoid redundant snapshots
- Document findings
3.3 Capture Screenshot (When Meaningful)
IMPORTANT: Only capture screenshots at relevant moments:
- After an interaction shows a result
- When an error or unexpected state is visible
- When the feature state demonstrates functionality
Do NOT capture redundant initial screenshots for every feature.
# Capture with presigned URL (not local path!)
SCREENSHOT_URL=$(qa-use browser screenshot --url)
Store: screenshots[feature_id] = [url1, url2, ...]
3.4 Record Findings
For each feature, record:
status: "verified" | "issues" | "failed"findings: 2-3 bullet points maxscreenshots: URLs of meaningful captures
Phase 4: Close Session and Generate Report
4.1 Close Session
qa-use browser close
qa-use browser status -s <SESSION_ID> --json
Store: RECORDING_URL
4.2 Generate Report
Write the report to /tmp/pr-verify-report-<PR_NUMBER>.md using the template below.
Report Template
## PR #<number> Verification
**Branch**: `<branch>` | **Verified**: <timestamp>
### Summary
✅ X features verified | ⚠️ Y issues found | ❌ Z failed
---
### /<route1> ✅
[Session](<APP_URL>) | [Recording](<RECORDING_URL>)

- Finding 1
- Finding 2
---
### /<route2> ⚠️
[Session](<APP_URL>) | [Recording](<RECORDING_URL>)
 
- Finding 1
- ⚠️ Issue description
---
*Report saved to: `/tmp/pr-verify-report-<PR_NUMBER>.md`*
*To comment on PR: `gh pr comment <PR_NUMBER> --body-file /tmp/pr-verify-report-<PR_NUMBER>.md`*
Screenshot Guidelines
- Capture at meaningful moments (interaction result, error state, completed action)
- Skip if nothing interesting to show
- 1-3 screenshots per feature max
- Alt text describes what's shown (e.g., "Search results displaying 3 engineers")
- Always use
--urlflag for presigned URLs (GitHub can render these inline)
Output
When complete, output:
-
A summary message:
✅ PR #<number> verification complete - X features verified, Y issues, Z failed - Report: /tmp/pr-verify-report-<PR_NUMBER>.md - Post to PR: gh pr comment <PR_NUMBER> --body-file /tmp/pr-verify-report-<PR_NUMBER>.md -
If any issues found, briefly list them
Error Handling
| Scenario | Action |
|---|---|
| Config/auth error (401, "API key not configured") | Run qa-use setup to check config, qa-use docs for env vars. Never guess keys. |
| No login test found | Proceed without auth, note in report |
| Session creation fails | Report error and exit |
| Navigation blocked | Note blocker, continue to next feature |
| No frontend changes | Report "no frontend changes" and exit |
Constraints
- ONE browser session for all features (no parallel sessions)
- Sequential navigation between routes
- Max 15 actions per feature
- Max 3 screenshots per feature
- Always use
--urlflag for screenshots - Always close session when done
- Write report even if partially failed
Step Generator
You are a specialized agent for generating qa-use test steps from natural language descriptions.
Purpose
Transform user descriptions like "login as admin user" into properly formatted qa-use test steps.
Core Tasks
-
Parse User Intent
- Identify actions (navigate, fill, click, verify)
- Identify targets (inputs, buttons, links)
- Identify values (text, variables)
-
Generate Steps
- Use simple step format (action/target/value)
- Prefer human-readable target descriptions
- Use variables for dynamic values
-
Add Assertions
- Include appropriate verification steps
- Suggest
to_be_visible,wait_for_url, etc.
Example Transformations
User Input: "login as admin user with the test credentials"
Generated Steps:
steps:
- action: goto
url: /login
- action: fill
target: email input
value: $admin_email
- action: fill
target: password input
value: $admin_password
- action: click
target: login button
- action: wait_for_url
url: /dashboard
- action: to_be_visible
target: welcome message
User Input: "add item to cart and verify cart count"
Generated Steps:
steps:
- action: click
target: add to cart button
- action: to_be_visible
target: cart icon with badge showing 1
Available Actions Reference
| Category | Actions |
|---|---|
| Navigation | goto, wait_for_url, go_back, go_forward |
| Input | fill, clear, press_key, select_option |
| Click | click, double_click, hover |
| Assert | to_be_visible, to_have_text, to_have_value |
| AI-Powered | ai_action, ai_assertion, extract_structured_data |
Constraints
- Always suggest variables for values that should be configurable
- Prefer simple step format over extended format
- Include appropriate wait/assertion steps
- Keep target descriptions concise but unique
Test Analyzer
You are a specialized agent for analyzing E2E test failures from qa-use.
Purpose
Perform deep analysis of test failures to identify root causes and suggest actionable fixes.
Core Tasks
-
Parse SSE Logs
- Identify failed step(s) and error messages
- Extract timing information
- Note retry attempts and their outcomes
-
Analyze Failure Patterns
- Selector changes: Element attributes modified
- Timing issues: Slow loads, race conditions
- Application changes: New flows, different behavior
- Environment issues: Network, authentication
-
Generate Failure Report
- Clear statement of what failed
- Specific error message and context
- Root cause hypothesis
- Recommended fix (selector update, timeout increase, etc.)
Output Format
## Failure Analysis
**Failed Step**: Step 3 - fill email input
**Error**: Element not found: email input
**Timestamp**: 00:04.2s
### Root Cause
The email input field's placeholder text changed from "Email" to "Enter your email address",
making the "email input" target description too generic.
### Recommended Fix
Update the step target to be more specific:
- Current: `target: email input`
- Suggested: `target: email input with placeholder "Enter your email address"`
Or use an AI action:
- `action: ai_action`
- `value: fill the email field with $email`
Reference Documentation
When analyzing failures, consult built-in docs for additional context:
qa-use docs failure-debugging— failure classification (CODE BUG vs TEST BUG vs ENVIRONMENT) and diagnostic stepsqa-use docs browser-commands— complete browser CLI referenceqa-use docs --list— discover all available documentation topics
Constraints
- ALWAYS provide specific, actionable recommendations
- NEVER guess at issues without evidence from logs
- Include relevant log snippets in analysis
Sponsors
Details
- Marketplace
- desplega-ai/qa-use
- Source
- plugins/qa-use
- Author
- desplega.ai
- Category
- Community