Automate Browser QA Testing with MCP

qa-use

QA automation CLI for browser testing and E2E test management.

Quick Start

# Install globally
npm install -g @desplega.ai/qa-use

# Or use with npx
npx @desplega.ai/qa-use setup

Getting Started

1. Setup

qa-use setup                    # Configure your API key
qa-use test init                # Initialize test directory with example

2. Create Your First Test

Create qa-tests/login.yaml:

name: Login Test
app_config: your-app-config-id
steps:
  - action: goto
    url: /login
  - action: fill
    target: email input
    value: test@example.com
  - action: click
    target: login button
  - action: to_be_visible
    target: dashboard

3. Run Tests

qa-use test run login           # Run single test
qa-use test run --all           # Run all tests

CLI Reference

Test Commands

Run qa-use test --help for all options.

Filename suffix (≥ 2.17). pull writes one file per cloud test as ${safe-name}-${short-id}.yaml, where ${short-id} is the first 8 hex chars of the test UUID. Test names can collide within an org by design, so the suffix guarantees one local file per cloud row. If you upgrade from an earlier version, the next pull will write new suffixed files alongside any legacy un-suffixed file you had - qa-use prints a one-line Legacy file: … notice per orphan and never auto-deletes. Inspect the legacy file's id: field; remove it manually once you've confirmed it's not load-bearing.

Browser Commands

Interactive browser control for test development and debugging:

qa-use browser create                  # Start browser session
qa-use browser goto https://example.com
qa-use browser snapshot                # Get element refs like [ref=e3]
qa-use browser click e3                # Click by element ref
qa-use browser fill e5 "hello"         # Fill input field
qa-use browser run                     # Interactive REPL mode

Run qa-use browser --help for the full list of 29 browser commands.

Tunnel & Maintenance Commands

browser create auto-tunnels when your target is localhost and the API is remote. For standalone tunnels (or cross-process registry inspection) use qa-use tunnel:

qa-use tunnel start http://localhost:3000 --hold   # Hold a public tunnel
qa-use tunnel ls                                   # List active tunnels
qa-use tunnel status <target|hash>                 # Detail for one entry
qa-use tunnel close <target|hash>                  # Force-release a tunnel
qa-use doctor                                      # Reap stale sessions/tunnels
qa-use doctor --dry-run                            # Preview what would be reaped

Note: qa-use tunnel * is the CLI-side cross-process tunnel registry, distinct from qa-use mcp tunnel which is the MCP-mode persistent tunnel wrapper (see below).

API Commands

Dynamic API access powered by live OpenAPI (/api/v1/openapi.json) with local cache fallback.

qa-use api ls                             # List endpoints from live/cached OpenAPI
qa-use api /api/v1/tests                  # Call endpoint (method inferred)
qa-use api -X POST /api/v1/tests-actions/run --input body.json
qa-use api ls --refresh                   # Force refresh OpenAPI cache
qa-use api ls --offline                   # Use cached OpenAPI only

If live spec fetch fails, qa-use falls back to the last cached spec and prints a stale-cache warning.

Checks and Check Schedules

Remote API checks and schedules are first-class CLI resources. They call the desplega.ai API directly; schedule runs are fully remote and do not create browser sessions.

qa-use check list --app-config <app-config-id> --q login
qa-use check info <check-id>

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-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
qa-use check-schedule delete <schedule-id> --force
qa-use check delete <check-id> --force

There is no standalone qa-use check run <check-id> command yet because the public API currently exposes schedule runs, not individual check-run actions. Use qa-use docs checks for the full workflow and qa-use api info /api/v1/checks -X POST for the current check payload contract.

Setup Commands

Test Definition Format

Tests are YAML files with steps that describe user interactions:

name: Checkout Flow
app_config: your-app-id
variables:
  email: test@example.com
depends_on: login-test          # Optional dependency
steps:
  - action: goto
    url: /cart
  - action: click
    target: checkout button
  - action: fill
    target: email input
    value: $email
  - action: to_be_visible
    target: order confirmation

Supported actions:

See SETUP.md for the complete test definition guide.

Configuration

Environment Variables

QA_USE_API_KEY=xxx              # Required: Your desplega.ai API key
QA_USE_REGION=us                # Optional: "us" or "auto" (default)

Config File

Alternatively, create a .qa-use.json in your project root or ~/.qa-use.json in your home directory:

{
  "$schema": "https://qa-use.dev/cli-schema.json",
  "api_key": "your-api-key-here",
  "region": "us"
}

Precedence (first wins):

1. Environment variables
2. .qa-use.json in current directory
3. ~/.qa-use.json in home directory

CI/CD Integration

Basic GitHub Actions

# .github/workflows/e2e.yml
name: E2E Tests

on: [push, pull_request]

jobs:
  e2e:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Run E2E Tests
        env:
          QA_USE_API_KEY: ${{ secrets.QA_USE_API_KEY }}
        run: |
          npm install -g @desplega.ai/qa-use
          qa-use test run --all --download

      - name: Upload Results
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: e2e-results
          path: /tmp/qa-use/downloads/

PR Verification with Claude Code

Use the qa-use plugin with Claude Code to automatically verify PRs:

# Add from the marketplace
claude plugin marketplace add desplega-ai/qa-use

# Then install the plugin
claude plugin install qa-use@desplega.ai

# Verify a feature works
/qa-use:verify "the login form accepts valid credentials"

# Verify PR changes
/qa-use:verify-pr

See SETUP.md for advanced CI workflows including AI-assisted test generation.

Claude Code Plugin

qa-use includes a Claude Code plugin for AI-assisted testing workflows:

# Add from the marketplace
claude plugin marketplace add desplega-ai/qa-use

# Then install the plugin
claude plugin install qa-use@desplega.ai

# Install the skill
npx skills add https://github.com/desplega-ai/qa-use --skill qa-use

Available skills:

MCP Server

For AI assistant integration (Claude Desktop, VS Code Copilot, Cursor, etc.), qa-use includes an MCP server with full browser automation capabilities.

qa-use mcp                      # Start stdio server (default)
qa-use mcp --http               # Start HTTP/SSE server
qa-use mcp tunnel               # Start persistent tunnel mode

See MCP.md for complete MCP server documentation including:

• Client configurations for all major AI assistants
• HTTP transport mode for web integrations
• Tunnel mode for backend-initiated testing
• Full MCP tools reference

Development

git clone https://github.com/desplega-ai/qa-use.git
cd qa-use
bun install
bun run build
bun run dev

Note: This project uses bun as the package manager.

See CONTRIBUTING.md for development guidelines.

Documentation

• SETUP.md - Complete E2E test setup guide
• MCP.md - MCP server documentation
• CONTRIBUTING.md - Development guide
• CLAUDE.md - AI assistant onboarding