qa-use Claude Code plugin

GitHub stars
29

Install

/plugin install qa-use@desplega.ai

Run it inside Claude Code after adding the marketplace with /plugin marketplace add desplega-ai/qa-use.

Contents

Discovered from source

Skills 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):

VariableDescription
QA_USE_API_KEYAPI key for authentication
QA_USE_REGIONRegion: us (default) or auto
QA_USE_API_URLOverride 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.
  • --id requires a full UUID (use qa-use test list --query <name> to find one).
  • Form upgrade: passing only --key/--value writes simple form (key: value). Any of --type/--lifetime/--context/--sensitive upgrades to full form ({ value, type, lifetime, context, is_sensitive }).
  • Sensitive-preserve: on an existing sensitive var, --sensitive without --value keeps the stored value. On a new key, that combination errors out.
  • --json redaction: sensitive entries omit the value key entirely; the is_sensitive: true flag 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 statepersistWhat happens at run time
Non-syncedfalse (default)Runs locally; nothing saved to cloud. Re-run with --persist or use test sync push to persist.
Non-syncedtrueTest 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.
SyncedfalseRuns against the cloud-tracked definition; no extra write.
SyncedtrueCloud 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

CommandDescription
qa-use browser createCreate 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-headlessShow 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 listList active sessions
qa-use browser statusShow current session details (app_url, recording_url, etc.)
qa-use browser status --listShow all active sessions across processes
qa-use browser closeClose active session
qa-use browser close <id>Close a specific session by id
qa-use doctorReap stale sessions/tunnels (dead PIDs)
qa-use tunnel lsList active tunnels in the registry
qa-use tunnel start <url> --holdHold 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

CommandDescription
qa-use browser goto <url>Navigate to URL
qa-use browser backGo back
qa-use browser forwardGo forward
qa-use browser reloadReload page

Element Interaction

CommandDescription
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 500Scroll 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

CommandDescription
qa-use browser snapshotGet full ARIA tree with element refs (use only when diff output is insufficient)
qa-use browser urlGet current URL
qa-use browser screenshotSave screenshot.png
qa-use browser screenshot file.pngSave to custom path
qa-use browser screenshot --base64Output 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

CommandDescription
qa-use test run <name>Run test by name
qa-use test run --allRun 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> --downloadDownload assets to /tmp/qa-use/downloads/
qa-use test run <name> --var key=valueOverride variable
qa-use test validate <name>Validate test syntax
qa-use test listList 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 failedFilter runs by status
qa-use test initInitialize test directory
qa-use test sync pullPull tests from cloud
qa-use test sync push --allPush all local tests to cloud
qa-use test sync push --id <uuid>Push specific test
qa-use test sync push --forcePush 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.

CommandDescription
qa-use apiShow help and available subcommands
qa-use api lsList available /api/v1/* routes from OpenAPI
qa-use api ls --refreshForce refresh OpenAPI cache
qa-use api ls --offlineUse 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 POSTShow info for specific HTTP method
qa-use api info /api/v1/<route> --jsonRoute info as JSON
qa-use api examplesShow usage examples
qa-use api openapiPrint OpenAPI spec URL
qa-use api openapi --rawDump full OpenAPI spec as JSON
qa-use api /api/v1/testsCall endpoint (method inferred when possible)
qa-use api -X GET /api/v1/test-runs -f limit=5GET with query fields
qa-use api -X POST /api/v1/tests-actions/run --input body.jsonPOST 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.

CommandDescription
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.jsonCreate a check
qa-use check update <check-id> --depends-on <id> --alias <name>Update dependency-chain metadata
qa-use check delete <check-id> --forceDelete 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=stagingRun 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

CommandDescription
qa-use browser logs consoleView console logs from session
qa-use browser logs console -s <id>View logs from specific/closed session
qa-use browser logs networkView network request logs
qa-use browser logs network -s <id>View network logs from specific session
qa-use browser downloadsList downloaded files from session
qa-use browser downloads --save <dir>Save downloaded files to local directory
qa-use browser downloads --jsonOutput download info as JSON

Test Generation

CommandDescription
qa-use browser generate-testGenerate 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-blocksGet recorded interaction blocks (JSON)

Waiting

CommandDescription
qa-use browser wait <ms>Fixed wait
qa-use browser wait-for-selector ".class"Wait for selector
qa-use browser wait-for-loadWait for page load

Variable Overrides

Use --var to override app config variables at runtime. Common variables:

VariableDescription
base_urlBase URL for the app (e.g., preview deployment URL)
login_urlLogin page URL
login_usernameUsername/email for authentication
login_passwordPassword 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:

ValueBehavior
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 -s flag 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>

TopicCLI CommandDescription
browser-commands.mdqa-use docs browser-commandsComplete browser CLI reference with all flags
checks.mdqa-use docs checksAPI checks and check schedule workflows
test-format.mdqa-use docs test-formatFull test YAML specification
localhost-testing.mdqa-use docs localhost-testingTunnel setup for local development
failure-debugging.mdqa-use docs failure-debuggingFailure classification and diagnostics
ci.mdqa-use docs ciCI/CD integration patterns and examples

Use qa-use docs --list to discover all available topics and templates.

Templates

TemplateDescription
basic-test.yamlSimple navigation and assertion
auth-flow.yamlLogin flow with credentials
form-test.yamlForm 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 destroybrowser close
browser close <session-id>browser close
Guessing element refsUse refs from diff output or snapshot
Running snapshot after every actionUse diff output; only snapshot when needed
Forcing --tunnel in dev (both local)Rely on auto-mode, or use --tunnel on explicitly
test sync --pulltest sync pull (subcommand, not flag)
test sync --pushtest 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>
SituationCommand
Auth / API key errorsqa-use setup then qa-use docs
Unknown browser commandqa-use docs browser-commands
Test failuresqa-use docs failure-debugging
Localhost / tunnel issuesqa-use docs localhost-testing
Test YAML syntaxqa-use docs test-format
API checks / schedulesqa-use docs checks
CI/CD setupqa-use docs ci

Key rules:

  • ALWAYS consult qa-use docs before improvising workarounds
  • NEVER fabricate API keys, tokens, URLs, or credentials
  • If qa-use setup shows 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

ArgumentDescription
urlURL to explore (e.g., https://example.com)
goalNavigation goal (e.g., "find the pricing page")

What Happens

  1. Creates browser session (or uses existing one)
  2. Navigates to the URL
  3. Analyzes page using accessibility snapshots
  4. 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

ArgumentDescription
start [name]Start recording with optional test name
edit <test-name>AI-assisted editing of existing test
stopStop recording and generate test YAML

What Happens

Recording Mode (start/stop)

  1. start: Creates browser session, enters recording mode
  2. actions: You perform browser commands, they're tracked
  3. stop: Generates test YAML with variables and semantic descriptions
  4. save: Writes to qa-tests/<name>.yaml

Edit Mode (edit)

  1. Loads existing test definition
  2. Understands your desired changes
  3. Applies modifications
  4. 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

  1. Creates qa-tests/ directory with example.yaml
  2. Optionally creates .qa-use.json config file
  3. 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

ArgumentDescription
test-nameTest to run (omit to list available tests)
--tunnelUse local browser with tunnel (required for localhost)
--headfulShow browser window
--downloadDownload assets to /tmp/qa-use/downloads/
--var key=valueOverride 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

ArgumentDescription
prPR number (e.g., #123), URL, or omit to infer from current branch
--base-url <url>Override base URL for ephemeral/preview deployments

What Happens

  1. Spawns a single pr-verifier agent in the background
  2. Agent analyzes the PR, identifies changed routes
  3. Agent creates ONE browser session and verifies all features sequentially
  4. Agent generates a concise visual report with inline screenshots
  5. 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-url flag

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 results showing engineers](screenshot_url)

- Search returns results with debounce
- Multi-select chips work

---

### /home ⚠️
[Session](app_url) | [Recording](recording_url)

![Slow load visible](screenshot_url)

- Navigation link visible
- ⚠️ Slow load time (3s)

Prerequisites

  1. qa-use CLI configured: API key set via QA_USE_API_KEY or ~/.qa-use.json
  2. GitHub CLI (gh) available: For PR context
  3. 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

ArgumentDescription
descriptionWhat to verify (e.g., "login works with valid credentials")

What Happens

  1. Searches for existing tests matching your description
  2. If no test exists, offers to explore and create one
  3. Runs the test
  4. 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-verify skill 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

  1. 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
  2. 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>
  3. Navigate to start_url (only if reusing an existing session)

    • Run: qa-use browser goto <start_url>
  4. 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 snapshot if 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.
  5. 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:
    qa-use browser create --after-test-id <login-test-uuid>
    
    This runs the login test first, leaving the session in an authenticated state.

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 setup to check current configuration state
  • Run: qa-use docs to 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:

SituationCommandWhat it provides
Configuration issuesqa-use setupShows current config state (API key, test dir)
Environment variablesqa-use docsMain docs with env var reference (QA_USE_API_KEY, etc.)
Unknown browser commandqa-use docs browser-commandsComplete browser CLI reference with all flags
Localhost/tunnel problemsqa-use docs localhost-testingTunnel setup and troubleshooting
Test failuresqa-use docs failure-debuggingFailure classification and diagnostics
Discover all topicsqa-use docs --listLists all available documentation topics

Key rules:

  • ALWAYS consult qa-use docs before improvising workarounds
  • NEVER hallucinate API keys, tokens, URLs, or credentials
  • If qa-use setup shows no config, report it and stop — don't try to fix it yourself

Constraints

  • ALWAYS create session first if none exists
  • ALWAYS run snapshot before your first interaction on a new page
  • After actions, use the diff output to find refs — only run snapshot again 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-verify skill after exploration to generate test YAML
  • By test-authoring skill 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 verifies
  • session_id: Existing browser session to attach to (optional - create new if not provided)
  • record_mode: capture (default) or replay (to verify recording works)

Recording Process

  1. 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."
  2. 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.
    
  3. Track browser commands Monitor all browser commands executed and map to test steps:

    Browser CommandTest 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>
  4. 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"
  5. 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/*.yaml examples)

Troubleshooting

If commands fail with configuration or auth errors ("API key not configured", 401, unauthorized):

  • Run qa-use setup to verify current configuration state
  • Run qa-use docs for 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 → /checkout
  • src/app/settings/page.tsx → /settings
  • src/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:

  1. Identify key interactive elements from diff output (or snapshot if needed)
  2. Perform verification actions (click, fill, scroll)
  3. Use diff output from each action to check for expected behavior — avoid redundant snapshots
  4. 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 max
  • screenshots: 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>)

![Alt text describing what's shown](<screenshot_url>)

- Finding 1
- Finding 2

---

### /<route2> ⚠️
[Session](<APP_URL>) | [Recording](<RECORDING_URL>)

![Error state visible](<screenshot_url1>) ![After fix attempt](<screenshot_url2>)

- 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 --url flag for presigned URLs (GitHub can render these inline)

Output

When complete, output:

  1. 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
    
  2. If any issues found, briefly list them

Error Handling

ScenarioAction
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 foundProceed without auth, note in report
Session creation failsReport error and exit
Navigation blockedNote blocker, continue to next feature
No frontend changesReport "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 --url flag 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

  1. Parse User Intent

    • Identify actions (navigate, fill, click, verify)
    • Identify targets (inputs, buttons, links)
    • Identify values (text, variables)
  2. Generate Steps

    • Use simple step format (action/target/value)
    • Prefer human-readable target descriptions
    • Use variables for dynamic values
  3. 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

CategoryActions
Navigationgoto, wait_for_url, go_back, go_forward
Inputfill, clear, press_key, select_option
Clickclick, double_click, hover
Assertto_be_visible, to_have_text, to_have_value
AI-Poweredai_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

  1. Parse SSE Logs

    • Identify failed step(s) and error messages
    • Extract timing information
    • Note retry attempts and their outcomes
  2. Analyze Failure Patterns

    • Selector changes: Element attributes modified
    • Timing issues: Slow loads, race conditions
    • Application changes: New flows, different behavior
    • Environment issues: Network, authentication
  3. 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 steps
  • qa-use docs browser-commands — complete browser CLI reference
  • qa-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