Qa Use

Free

QA automation tool for browser testing with MCP server support

by tarasyarema

GitHub

About

QA automation tool for browser testing with MCP server support

README

QA automation CLI for browser testing and E2E test management.

npm version License: MIT

QA-Use Demo

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: [email protected]
  - 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

Command	Description
`qa-use test init`	Initialize test directory with example
`qa-use test run <name>`	Run a test by name
`qa-use test run --all`	Run all tests in `qa-tests/`
`qa-use test list`	List local tests
`qa-use test list --cloud`	List cloud tests
`qa-use test validate <name>`	Validate test syntax
`qa-use test sync --push`	Push local tests to cloud
`qa-use test sync --pull`	Pull cloud tests to local
`qa-use test export <id>`	Export cloud test to local file

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

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

Command	Description
`qa-use browser create`	Start browser session
`qa-use browser goto <url>`	Navigate to URL
`qa-use browser snapshot`	Get page element refs
`qa-use browser click <ref>`	Click element by ref
`qa-use browser fill <ref> <value>`	Fill input field
`qa-use browser screenshot <path>`	Save screenshot
`qa-use browser run`	Interactive REPL mode
`qa-use browser close`	Close browser session
`qa-use browser status --list`	List active sessions across processes

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

Command	Description
`qa-use tunnel ls`	List active tunnels in the registry
`qa-use tunnel status <target>`	Show detail for a single tunnel
`qa-use tunnel close <target>`	Force-release a tunnel (kills detached holder)
`qa-use doctor`	Reap stale sessions/tunnels (dead PIDs)

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

Command	Description
`qa-use api ls`	List `/api/v1/*` endpoints from OpenAPI
`qa-use api <path>`	Send API request to endpoint
`qa-use api ... --refresh`	Force OpenAPI spec refresh
`qa-use api ... --offline`	Use cached spec without network

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

Setup Commands

Command	Description
`qa-use setup`	Interactive configuration (API key, base URL, etc.)
`qa-use info`	Show current configuration
`qa-use install-deps`	Install Playwright browsers

Test Definition Format

Tests are YAML files with steps that describe user interactions:

name: Checkout Flow
app_config: your-app-id
variables:
  email: [email protected]
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:

Category	Actions
Navigation	`goto`, `go_back`, `go_forward`, `reload`
Input	`fill`, `type`, `click`, `hover`, `press`, `check`, `uncheck`, `select_option`
Waiting	`wait_for_selector`, `wait_for_timeout`, `wait_for_load_state`
Assertions	`to_be_visible`, `to_have_text`, `to_have_url`, `to_contain_text`, `to_be_checked`
Advanced	`ai_action`, `ai_assertion`, `extract_structured_data`

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

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

Variable	Description	Default
`QA_USE_API_KEY`	API key for authentication	(required)
`QA_USE_API_URL`	API endpoint	`https://api.desplega.ai`
`QA_USE_APP_URL`	App URL	`https://app.desplega.ai`
`QA_USE_REGION`	Region (`us` or `auto`)	`auto`
`QA_USE_DEFAULT_APP_CONFIG_ID`	Default app config	(from API key)

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 [email protected]

# 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 [email protected]

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

Available skills:

Skill	Description
`/qa-use:verify <description>`	Verify a feature works through browser automation
`/qa-use:verify-pr`	Verify PR changes with automated browser testing
`/qa-use:explore`	Explore a web page interactively
`/qa-use:record`	Record browser actions into a test definition
`/qa-use:test-run`	Run E2E tests
`/qa-use:test-validate`	Validate test syntax

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

License

MIT

How to install

Add this to claude_desktop_config.json and restart Claude Desktop.

{
  "mcpServers": {
    "qa-use": {
      "command": "npx",
      "args": [
        "-y",
        "@desplega.ai/qa-use"
      ]
    }
  }
}

Qa Use

About

README

Quick Start

Getting Started

1. Setup

2. Create Your First Test

3. Run Tests

CLI Reference

Test Commands

Browser Commands

Tunnel & Maintenance Commands

API Commands

Setup Commands

Test Definition Format

Configuration

Environment Variables

Config File

CI/CD Integration

Basic GitHub Actions

PR Verification with Claude Code

Claude Code Plugin

MCP Server

Development

Documentation

License

How to install

Related MCPs

Playwright

Puppeteer

opentabs-dev/opentabs

robhunter/agentdeals

Command Palette

Qa Use

About

README

Quick Start

Getting Started

1. Setup

2. Create Your First Test

3. Run Tests

CLI Reference

Test Commands

Browser Commands

Tunnel & Maintenance Commands

API Commands

Setup Commands

Test Definition Format

Configuration

Environment Variables

Config File

CI/CD Integration

Basic GitHub Actions

PR Verification with Claude Code

Claude Code Plugin

MCP Server

Development

Documentation

License

How to install

Related MCPs

Playwright

Puppeteer

opentabs-dev/opentabs

robhunter/agentdeals