qa-use

Fornece automação completa de navegador para capacidades de teste de QA.

Documentação

qa-use

CLI de automação de QA para testes de navegador e gerenciamento de testes E2E.

Início Rápido

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

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

Começando

1. Configuração

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

2. Crie Seu Primeiro Teste

Crie 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. Execute Testes

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

Referência da CLI

Comandos de Teste

Comando	Descrição
`qa-use test init`	Inicializa o diretório de teste com exemplo
`qa-use test run <name>`	Executa um teste pelo nome
`qa-use test run --all`	Executa todos os testes em `qa-tests/`
`qa-use test list`	Lista testes locais
`qa-use test list --cloud`	Lista testes na nuvem
`qa-use test validate <name>`	Valida a sintaxe do teste
`qa-use test sync --push`	Envia testes locais para a nuvem
`qa-use test sync --pull`	Baixa testes da nuvem para o ambiente local
`qa-use test export <id>`	Exporta teste da nuvem para arquivo local

Execute qa-use test --help para todas as opções.

Sufixo do nome de arquivo (≥ 2.17). pull grava um arquivo por teste na nuvem como ${safe-name}-${short-id}.yaml, onde ${short-id} são os primeiros 8 caracteres hexadecimais do UUID do teste. Nomes de teste podem colidir dentro de uma organização por design, então o sufixo garante um arquivo local por linha na nuvem. Se você atualizar de uma versão anterior, o próximo pull gravará novos arquivos com sufixo junto com qualquer arquivo legado sem sufixo que você tiver — o qa-use imprime um aviso de uma linha Legacy file: … por arquivo órfão e nunca exclui automaticamente. Inspecione o campo id: do arquivo legado; remova-o manualmente depois de confirmar que ele não é essencial.

Comandos do Navegador

Controle interativo do navegador para desenvolvimento e depuração de testes:

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

Comando	Descrição
`qa-use browser create`	Inicia a sessão do navegador
`qa-use browser goto <url>`	Navega para uma URL
`qa-use browser snapshot`	Obtém referências de elementos da página
`qa-use browser click <ref>`	Clica em elemento por referência
`qa-use browser fill <ref> <value>`	Preenche campo de entrada
`qa-use browser screenshot <path>`	Salva captura de tela
`qa-use browser run`	Modo REPL interativo
`qa-use browser close`	Fecha a sessão do navegador
`qa-use browser status --list`	Lista sessões ativas entre processos

Execute qa-use browser --help para a lista completa dos 29 comandos do navegador.

Comandos de Túnel e Manutenção

browser create cria túnel automático quando seu destino é localhost e a API é remota. Para túneis independentes (ou inspeção do registro entre processos), 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

Comando	Descrição
`qa-use tunnel ls`	Lista túneis ativos no registro
`qa-use tunnel status <target>`	Mostra detalhes de um único túnel
`qa-use tunnel close <target>`	Força a liberação de um túnel (mata o detentor destacado)
`qa-use doctor`	Remove sessões/túneis obsoletos (PIDs mortos)

Nota: qa-use tunnel * é o registro de túneis entre processos do lado da CLI, distinto de qa-use mcp tunnel, que é o wrapper de túnel persistente do modo MCP (veja abaixo).

Comandos de API

Acesso dinâmico à API alimentado por OpenAPI ao vivo (/api/v1/openapi.json) com fallback de cache local.

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

Comando	Descrição
`qa-use api ls`	Lista endpoints `/api/v1/*` do OpenAPI
`qa-use api <path>`	Envia requisição de API para o endpoint
`qa-use api ... --refresh`	Força a atualização da especificação OpenAPI
`qa-use api ... --offline`	Usa a especificação em cache sem rede

Se a busca da especificação ao vivo falhar, o qa-use usa a última especificação em cache e imprime um aviso de cache desatualizado.

Verificações e Agendamentos de Verificação

Verificações e agendamentos de API remota são recursos de primeira classe da CLI. Eles chamam a API da desplega.ai diretamente; as execuções agendadas são totalmente remotas e não criam sessões de navegador.

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

Ainda não existe um comando qa-use check run <check-id> independente porque a API pública atualmente expõe execuções agendadas, não ações individuais de execução de verificação. Use qa-use docs checks para o fluxo de trabalho completo e qa-use api info /api/v1/checks -X POST para o contrato atual de payload de verificação.

Comandos de Configuração

Comando	Descrição
`qa-use setup`	Configuração interativa (chave de API, URL base, etc.)
`qa-use info`	Mostra a configuração atual
`qa-use install-deps`	Instala navegadores Playwright

Formato de Definição de Teste

Testes são arquivos YAML com etapas que descrevem interações do usuário:

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

Ações suportadas:

Categoria	Ações
Navegação	`goto`, `go_back`, `go_forward`, `reload`
Entrada	`fill`, `type`, `click`, `hover`, `press`, `check`, `uncheck`, `select_option`
Espera	`wait_for_selector`, `wait_for_timeout`, `wait_for_load_state`
Asserções	`to_be_visible`, `to_have_text`, `to_have_url`, `to_contain_text`, `to_be_checked`
Avançado	`ai_action`, `ai_assertion`, `extract_structured_data`

Veja SETUP.md para o guia completo de definição de testes.

Configuração

Variáveis de Ambiente

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

Arquivo de Configuração

Alternativamente, crie um .qa-use.json na raiz do seu projeto ou ~/.qa-use.json no seu diretório pessoal:

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

Precedência (o primeiro vence):

Variáveis de ambiente
.qa-use.json no diretório atual
~/.qa-use.json no diretório pessoal

Variável	Descrição	Padrão
`QA_USE_API_KEY`	Chave de API para autenticação	(obrigatório)
`QA_USE_API_URL`	Endpoint da API	`https://api.desplega.ai`
`QA_USE_APP_URL`	URL do aplicativo	`https://app.desplega.ai`
`QA_USE_REGION`	Região (`us` ou `auto`)	`auto`
`QA_USE_DEFAULT_APP_CONFIG_ID`	Configuração padrão do aplicativo	(da chave de API)
`QA_USE_FORCE_HEADLESS`	Quando verdadeiro (`1`/`true`/`yes`/`on`), força `headless=true` em cada inicialização do navegador e gera erro em qualquer solicitação explícita de modo com janela (`--no-headless`, `--headful`, `defaults.headless: false`).	(não definido)

Integração CI/CD

GitHub Actions Básico

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

Verificação de PR com Claude Code

Use o plugin qa-use com Claude Code para verificar PRs automaticamente:

# 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

Veja SETUP.md para fluxos de trabalho avançados de CI, incluindo geração de testes assistida por IA.

Plugin Claude Code

O qa-use inclui um plugin Claude Code para fluxos de trabalho de teste assistidos por IA:

# 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

Habilidades disponíveis:

Habilidade	Descrição
`/qa-use:verify <description>`	Verifica se um recurso funciona por meio de automação de navegador
`/qa-use:verify-pr`	Verifica alterações de PR com testes automatizados de navegador
`/qa-use:explore`	Explora uma página da web interativamente
`/qa-use:record`	Grava ações do navegador em uma definição de teste
`/qa-use:test-run`	Executa testes E2E
`/qa-use:test-validate`	Valida a sintaxe do teste

Servidor MCP

Para integração com assistentes de IA (Claude Desktop, VS Code Copilot, Cursor, etc.), o qa-use inclui um servidor MCP com capacidades completas de automação de navegador.

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

Veja MCP.md para documentação completa do servidor MCP, incluindo:

Configurações de cliente para todos os principais assistentes de IA
Modo de transporte HTTP para integrações web
Modo de túnel para testes iniciados pelo backend
Referência completa de ferramentas MCP

Desenvolvimento

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

Nota: Este projeto usa bun como gerenciador de pacotes.

Veja CONTRIBUTING.md para diretrizes de desenvolvimento.

Documentação

SETUP.md - Guia completo de configuração de testes E2E
MCP.md - Documentação do servidor MCP
CONTRIBUTING.md - Guia de desenvolvimento
CLAUDE.md - Integração de assistente de IA

Licença

MIT