تشغيل أي مهارة في Manus بنقرة واحدة

qa-use

النجوم٢٥

التفرعات٦

آخر تحديث٢٦ مايو ٢٠٢٦ في ١٥:٢٣

E2E testing and browser automation with qa-use CLI. Use when the user needs to run tests, verify features, automate browser interactions, or debug test failures.

التثبيت

التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.

تشغيل في Manus

المصدر

desplega-ai

desplega-ai/qa-use

فتح مستودع GitHub عرض مستودعات المنشئ

تنزيل

تشغيل في Manus

المهن ذات الصلةSOC

استنادا إلى تصنيف SOC المهني

محللو ضمان جودة البرمجيات والمختبرونمهن الحاسوب والرياضيات·SOC 15-1253

مستكشف الملفات

10 ملفات

SKILL.md

readonly

تشغيل أي مهارة بنقرة واحدة

name	qa-use
description	E2E testing and browser automation with qa-use CLI. Use when the user needs to run tests, verify features, automate browser interactions, or debug test failures.
allowed-tools	Bash(qa-use *)

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.
--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 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 -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>

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 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>

name	qa-use
description	E2E testing and browser automation with qa-use CLI. Use when the user needs to run tests, verify features, automate browser interactions, or debug test failures.
allowed-tools	Bash(qa-use *)

qa-use

E2E testing and browser automation for AI-driven development workflows.

Critical Insight: Plugin Commands as Shortcuts

For AI Harnesses (codex, opencode, etc.):

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)

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:

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

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

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

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 -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>

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 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>