qa-use

Proporciona automatización integral del navegador para capacidades de pruebas de QA.

Documentación

qa-use

CLI de automatización de QA para pruebas de navegador y gestión de pruebas E2E.

Inicio rápido

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

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

Primeros pasos

1. Configuración

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

2. Crea tu primera prueba

Crea 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. Ejecuta pruebas

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

Referencia de CLI

Comandos de prueba

Comando	Descripción
`qa-use test init`	Inicializa el directorio de pruebas con un ejemplo
`qa-use test run <name>`	Ejecuta una prueba por nombre
`qa-use test run --all`	Ejecuta todas las pruebas en `qa-tests/`
`qa-use test list`	Lista las pruebas locales
`qa-use test list --cloud`	Lista las pruebas en la nube
`qa-use test validate <name>`	Valida la sintaxis de las pruebas
`qa-use test sync --push`	Envía las pruebas locales a la nube
`qa-use test sync --pull`	Descarga las pruebas de la nube a local
`qa-use test export <id>`	Exporta una prueba de la nube a un archivo local

Ejecuta qa-use test --help para ver todas las opciones.

Sufijo de nombre de archivo (≥ 2.17). pull escribe un archivo por prueba en la nube como ${safe-name}-${short-id}.yaml, donde ${short-id} son los primeros 8 caracteres hexadecimales del UUID de la prueba. Los nombres de prueba pueden colisionar dentro de una organización por diseño, por lo que el sufijo garantiza un archivo local por fila en la nube. Si actualizas desde una versión anterior, el próximo pull escribirá nuevos archivos con sufijo junto a cualquier archivo heredado sin sufijo que tuvieras — qa-use imprime un aviso de una línea Legacy file: … por cada archivo huérfano y nunca elimina automáticamente. Inspecciona el campo id: del archivo heredado; elimínalo manualmente una vez que hayas confirmado que no es esencial.

Comandos de navegador

Control interactivo del navegador para desarrollo y depuración de pruebas:

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	Descripción
`qa-use browser create`	Inicia una sesión de navegador
`qa-use browser goto <url>`	Navega a una URL
`qa-use browser snapshot`	Obtiene referencias de elementos de la página
`qa-use browser click <ref>`	Haz clic en un elemento por referencia
`qa-use browser fill <ref> <value>`	Rellena un campo de entrada
`qa-use browser screenshot <path>`	Guarda una captura de pantalla
`qa-use browser run`	Modo REPL interactivo
`qa-use browser close`	Cierra la sesión de navegador
`qa-use browser status --list`	Lista las sesiones activas entre procesos

Ejecuta qa-use browser --help para ver la lista completa de 29 comandos de navegador.

Comandos de túnel y mantenimiento

browser create crea túneles automáticamente cuando tu destino es localhost y la API es remota. Para túneles independientes (o inspección del registro entre procesos) usa 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	Descripción
`qa-use tunnel ls`	Lista los túneles activos en el registro
`qa-use tunnel status <target>`	Muestra el detalle de un solo túnel
`qa-use tunnel close <target>`	Fuerza la liberación de un túnel (mata al titular separado)
`qa-use doctor`	Elimina sesiones/túneles obsoletos (PIDs muertos)

Nota: qa-use tunnel * es el registro de túneles entre procesos del lado CLI, distinto de qa-use mcp tunnel, que es el envoltorio de túnel persistente en modo MCP (ver más abajo).

Comandos de API

Acceso dinámico a la API impulsado por OpenAPI en vivo (/api/v1/openapi.json) con respaldo de caché 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	Descripción
`qa-use api ls`	Lista los endpoints `/api/v1/*` de OpenAPI
`qa-use api <path>`	Envía una solicitud de API al endpoint
`qa-use api ... --refresh`	Fuerza la actualización de la especificación OpenAPI
`qa-use api ... --offline`	Usa la especificación en caché sin red

Si la obtención de la especificación en vivo falla, qa-use recurre a la última especificación en caché y muestra una advertencia de caché obsoleta.

Comprobaciones y programaciones de comprobaciones

Las comprobaciones y programaciones de API remota son recursos CLI de primera clase. Llaman directamente a la API de desplega.ai; las ejecuciones programadas son completamente remotas y no crean sesiones 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

Todavía no existe un comando independiente qa-use check run <check-id> porque la API pública actualmente expone ejecuciones programadas, no acciones individuales de ejecución de comprobaciones. Usa qa-use docs checks para el flujo de trabajo completo y qa-use api info /api/v1/checks -X POST para el contrato actual de payload de comprobación.

Comandos de configuración

Comando	Descripción
`qa-use setup`	Configuración interactiva (clave de API, URL base, etc.)
`qa-use info`	Muestra la configuración actual
`qa-use install-deps`	Instala los navegadores de Playwright

Formato de definición de pruebas

Las pruebas son archivos YAML con pasos que describen interacciones de usuario:

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

Acciones compatibles:

Categoría	Acciones
Navegación	`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`
Aserciones	`to_be_visible`, `to_have_text`, `to_have_url`, `to_contain_text`, `to_be_checked`
Avanzado	`ai_action`, `ai_assertion`, `extract_structured_data`

Consulta SETUP.md para la guía completa de definición de pruebas.

Configuración

Variables de entorno

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

Archivo de configuración

Alternativamente, crea un .qa-use.json en la raíz de tu proyecto o un ~/.qa-use.json en tu directorio personal:

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

Precedencia (gana el primero):

Variables de entorno
.qa-use.json en el directorio actual
~/.qa-use.json en el directorio personal

Variable	Descripción	Predeterminado
`QA_USE_API_KEY`	Clave de API para autenticación	(obligatoria)
`QA_USE_API_URL`	Endpoint de API	`https://api.desplega.ai`
`QA_USE_APP_URL`	URL de la aplicación	`https://app.desplega.ai`
`QA_USE_REGION`	Región (`us` o `auto`)	`auto`
`QA_USE_DEFAULT_APP_CONFIG_ID`	Configuración de aplicación predeterminada	(de la clave de API)
`QA_USE_FORCE_HEADLESS`	Cuando es verdadero (`1`/`true`/`yes`/`on`), fuerza `headless=true` en cada lanzamiento de navegador y da error ante cualquier solicitud explícita con ventana (`--no-headless`, `--headful`, `defaults.headless: false`).	(sin establecer)

Integración CI/CD

Acciones básicas de GitHub

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

Verificación de PR con Claude Code

Usa el plugin qa-use con Claude Code para verificar PRs automáticamente:

# 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

Consulta SETUP.md para flujos de trabajo CI avanzados, incluida la generación de pruebas asistida por IA.

Plugin de Claude Code

qa-use incluye un plugin de Claude Code para flujos de trabajo de pruebas asistidos 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 disponibles:

Habilidad	Descripción
`/qa-use:verify <description>`	Verifica que una función funciona mediante automatización de navegador
`/qa-use:verify-pr`	Verifica los cambios de un PR con pruebas de navegador automatizadas
`/qa-use:explore`	Explora una página web de forma interactiva
`/qa-use:record`	Graba acciones del navegador en una definición de prueba
`/qa-use:test-run`	Ejecuta pruebas E2E
`/qa-use:test-validate`	Valida la sintaxis de las pruebas

Servidor MCP

Para la integración con asistentes de IA (Claude Desktop, VS Code Copilot, Cursor, etc.), qa-use incluye un servidor MCP con capacidades completas de automatización 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

Consulta MCP.md para la documentación completa del servidor MCP, incluido:

Configuraciones de cliente para todos los asistentes de IA principales
Modo de transporte HTTP para integraciones web
Modo de túnel para pruebas iniciadas desde el backend
Referencia completa de herramientas MCP

Desarrollo

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

Nota: Este proyecto usa bun como gestor de paquetes.

Consulta CONTRIBUTING.md para las pautas de desarrollo.

Documentación

SETUP.md - Guía completa de configuración de pruebas E2E
MCP.md - Documentación del servidor MCP
CONTRIBUTING.md - Guía de desarrollo
CLAUDE.md - Incorporación de asistentes de IA

Licencia

MIT