GhostQA

GhostQA envía personas de IA a través de tu aplicación: miran la pantalla, deciden qué hacer e interactúan como humanos reales. Sin scripts de prueba. Sin selectores. Describes las personas y los recorridos en YAML, y GhostQA se encarga del resto.

GitHubPrueba este MCPPatrocinado

Documentación

SpecterQA

Las personas de IA recorren tu aplicación para que los usuarios reales no tropiecen.

SpecterQA envía personas de IA a través de tu aplicación: miran la pantalla, deciden qué hacer e interactúan como humanos reales. Sin scripts de prueba. Sin selectores. Describes personas y recorridos en YAML, y SpecterQA se encarga del resto.

$ specterqa run -p myapp

┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ SpecterQA Run                                                    ┃
┃ Product: myapp   Budget: $5.00   Viewport: 1280x720            ┃
┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛

  ✓ Step 1/4: Navigate to homepage       PASS   3.2s   $0.0081
  ✓ Step 2/4: Click signup link          PASS   2.1s   $0.0043
  ✓ Step 3/4: Fill registration form     PASS   8.7s   $0.0312
  ✓ Step 4/4: Verify dashboard loads     PASS   4.5s   $0.0127

┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ ALL TESTS PASSED                                                ┃
┃ Steps: 4/4   Findings: 0   Duration: 18.5s   Cost: $0.0563     ┃
┃ Run ID: GQA-RUN-20260222-143052-a1b2                            ┃
┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛

¿Qué es esto?

Las pruebas E2E tradicionales son frágiles. Escribes selectores, se rompen. Mantienes scripts, se pudren. SpecterQA adopta un enfoque diferente: los modelos de visión por IA miran tu interfaz real y la navegan como lo haría una persona.

Defines personas (quién usa tu aplicación) y recorridos (qué intentan hacer). El motor de SpecterQA toma una captura de pantalla, la envía a un modelo de visión de Claude, recibe una decisión ("haz clic en este botón", "rellena este campo"), la ejecuta mediante Playwright, toma otra captura y repite hasta que se logra el objetivo o algo sale mal.

Cuando algo sale mal, obtienes evidencia: capturas de pantalla, observaciones de UX, desgloses de costos y hallazgos categorizados por severidad.

Instalación

SpecterQA se distribuye a través de PyPI y requiere Python 3.10 o posterior.

pip install specterqa

Después de instalar, descarga los binarios del navegador Playwright:

specterqa install

Para pruebas de aplicaciones nativas de macOS y soporte del Simulador de iOS, instala el extra opcional native:

pip install specterqa[native]

Para soporte del servidor MCP (integrando SpecterQA como herramienta en Claude Desktop, Cursor u otros clientes MCP):

pip install specterqa[mcp]

También necesitarás una clave de API de Anthropic para ejecutar pruebas:

export ANTHROPIC_API_KEY=sk-ant-...

Para verificar la instalación:

specterqa --version
specterqa init       # scaffold a sample project
specterqa run -p demo

Inicio rápido

pip install specterqa
specterqa install          # downloads Playwright browsers
specterqa init             # scaffolds .specterqa/ with sample configs
specterqa run -p demo      # runs the sample journey

Necesitarás una clave de API de Anthropic:

export ANTHROPIC_API_KEY=sk-ant-...

Eso es todo. Tres comandos y una clave de API.

Cómo funciona

El bucle principal es simple:

screenshot --> vision model --> action decision --> execute --> repeat

Captura de pantalla -- Playwright captura el estado actual de la página como PNG
Decidir -- Un modelo de visión de Claude recibe la captura + contexto de persona + objetivo, devuelve una acción JSON estructurada (click, fill, navigate, scroll, keyboard, wait, done o stuck)
Ejecutar -- Playwright realiza la acción (clic en coordenadas, escribir texto, navegar a URL, etc.)
Repetir -- Bucle hasta que se logre el objetivo, el agente se atasque o se agote el presupuesto

El perfil de la persona moldea cómo se comporta la IA. Un "desarrollador experto en tecnología" explora de manera diferente a un "usuario novato frustrado". La paciencia de la persona, su comodidad con la tecnología y sus frustraciones influyen en el prompt del sistema.

Enrutamiento de modelos mantiene los costos bajos. Las acciones simples (clic, desplazamiento) usan Haiku. Las acciones complejas (rellenar formularios, evaluación inicial) usan Sonnet. También puedes enrutar acciones simples a un modelo local de Ollama (llava:13b) para costo cero de API en navegación sencilla.

Características

Pruebas basadas en personas -- Define usuarios de IA con antecedentes, objetivos, frustraciones y niveles de comodidad tecnológica. No solo siguen scripts; reaccionan a lo que ven.
Impulsado por visión -- Sin selectores, sin consultas al DOM. La IA interpreta capturas de pantalla como lo haría un humano. Detecta problemas visuales/de diseño que las pruebas basadas en selectores pasan por alto por completo.
Configurado con YAML -- Productos, personas y recorridos son archivos YAML. Los PMs pueden leerlos. Sin código que mantener.
Control de presupuesto -- Límites de costo por ejecución, por día y por mes. El motor se detiene en seco si alcanzas el límite. Sin facturas sorpresa.
Salida JUnit XML -- Coloca --junit-xml results.xml y conéctalo a cualquier sistema de CI.
Enrutamiento de modelos por niveles -- Haiku para navegación económica, Sonnet para razonamiento complejo, Ollama local opcional para acciones simples sin costo.
Multiplataforma -- Aplicaciones web (mediante Playwright), aplicaciones nativas de macOS (mediante API de Accesibilidad + pyobjc), Simulador de iOS (mediante simctl). Mismo formato YAML, diferentes ejecutores.
Recopilación de evidencia -- Cada ejecución produce capturas de pantalla, un informe de hallazgos, desglose de costos y un resultado JSON estructurado. Todo se guarda en un directorio de evidencia.
Detección de atascos -- Si la IA repite la misma acción o la interfaz deja de cambiar, el motor escala a un modelo más potente y luego aborta si nada funciona. Sin bucles infinitos.
Variables de plantilla -- Usa {{persona.credentials.email}} en los pasos de tu recorrido. Las variables se resuelven desde las configuraciones de persona en tiempo de ejecución.
Comprobaciones de requisitos previos -- Verifica que los servicios estén activos antes de ejecutar pruebas. Falla rápido con errores claros en lugar de desperdiciar llamadas a la API.

Configuración

SpecterQA utiliza tres tipos de archivos de configuración YAML, todos ubicados en .specterqa/:

Producto (`products/myapp.yaml`)

product:
  name: myapp
  display_name: "My Application"
  base_url: "http://localhost:3000"

  services:
    frontend:
      url: "http://localhost:3000"
      health_endpoint: /

  viewports:
    desktop:
      width: 1280
      height: 720
    mobile:
      width: 375
      height: 812

  cost_limits:
    per_run_usd: 5.00

Persona (`personas/alex-developer.yaml`)

persona:
  name: alex_developer
  display_name: "Alex Chen"
  role: "Full-Stack Developer"
  age: 28
  tech_comfort: high
  patience: medium
  preferred_device: desktop

  goals:
    - "Evaluate the app from a developer's perspective"
    - "Check for common UX anti-patterns"

  frustrations:
    - "Unclear error messages"
    - "Missing loading indicators"

  credentials:
    email: "alex@example.com"
    password: "TestPass123!"

Recorrido (`journeys/onboarding.yaml`)

scenario:
  id: onboarding-happy-path
  name: "Onboarding Happy Path"
  description: "New user signs up, completes onboarding, reaches dashboard."
  tags: [onboarding, critical_path, smoke]

  personas:
    - ref: alex_developer
      role: primary

  preconditions:
    - service: frontend
      check: /
      expected_status: 200

  steps:
    - id: visit_homepage
      mode: browser
      goal: "Navigate to the homepage and verify it loads"
      checkpoints:
        - type: text_present
          value: "Welcome"

    - id: navigate_signup
      mode: browser
      goal: "Find and click the signup link"

    - id: fill_signup_form
      mode: browser
      goal: "Complete the signup form with test credentials"

    - id: verify_dashboard
      mode: browser
      goal: "Verify signup succeeded and the dashboard loads"

Consulta docs/configuration.md para la referencia completa.

Soporte de esquema YAML

SpecterQA incluye un JSON Schema para archivos YAML de producto en schemas/product.schema.json.

# yaml-language-server: $schema=../../schemas/product.schema.json

Integración con CI

SpecterQA está diseñado para CI. Se ejecuta sin interfaz gráfica por defecto y devuelve códigos de salida adecuados.

# Basic CI run
specterqa run -p myapp --junit-xml results.xml

# Smoke test (runs first scenario only, fast)
specterqa run -p myapp --level smoke --budget 2.00

# JSON output for programmatic consumption
specterqa run -p myapp --output json > results.json

Códigos de salida:

0 -- todas las pruebas pasaron
1 -- una o más pruebas fallaron
2 -- error de configuración
3 -- error de infraestructura (dependencias faltantes, API inaccesible)

Consulta docs/ci-integration.md para ejemplos de GitHub Actions, GitLab CI y CircleCI.

Costo

SpecterQA utiliza la API de Claude de Anthropic. Cada ejecución cuesta dinero. Esto es lo que puedes esperar:

Modelo	Rol	Entrada (por 1M tokens)	Salida (por 1M tokens)
Claude Haiku 4.5	Navegación simple	$0.80	$4.00
Claude Sonnet 4	Razonamiento complejo	$3.00	$15.00
Ollama llava:13b	Respaldo local	Gratis	Gratis

Costos típicos por ejecución:

Prueba de humo de 3 pasos: ~$0.30-0.60
Recorrido estándar de 5 pasos: ~$0.50-1.50
Recorrido complejo de 10 pasos con formularios: ~$1.00-3.00

El presupuesto predeterminado es $5.00 por ejecución. El motor se detiene en seco si se excede el presupuesto -- sin excesos silenciosos. También puedes establecer límites por día y por mes.

También puedes establecer un presupuesto predeterminado mediante una variable de entorno para evitar pasar --budget cada vez:

export SPECTERQA_BUDGET=2.00
specterqa run -p myapp          # uses $2.00 budget
specterqa run -p myapp --budget 5.00  # uses $5.00 budget (CLI flag wins)

El enrutamiento de modelos ayuda: los clics y desplazamientos simples usan Haiku (~~$0.01 por acción), mientras que el llenado de formularios y las evaluaciones iniciales usan Sonnet (~~$0.03-0.05 por acción). Si tienes una instancia local de Ollama, las acciones simples pueden enrutarse allí sin costo de API.

Consulta docs/cost-guide.md para desgloses de costos detallados y estrategias de presupuesto.

Multiplataforma

SpecterQA no es solo para web. El mismo formato YAML de persona/recorrido funciona en todas las plataformas:

Aplicaciones web (predeterminado) -- Utiliza Playwright para la automatización del navegador.

Aplicaciones nativas de macOS -- Utiliza la API de Accesibilidad de macOS mediante pyobjc. La IA lee el árbol de accesibilidad y las capturas de pantalla, luego ejecuta clics y pulsaciones de teclas a través de acciones AX.

product:
  name: my-mac-app
  app_type: native_macos
  app_path: /Applications/MyApp.app
  bundle_id: com.example.myapp

Simulador de iOS -- Utiliza simctl para capturas de pantalla y simulación táctil. Útil para probar aplicaciones iOS sin un dispositivo físico.

product:
  name: my-ios-app
  app_type: ios_simulator
  bundle_id: com.example.myiosapp
  simulator_device: "iPhone 15 Pro"
  simulator_os: "17.2"

El soporte nativo y de simulador requiere la dependencia opcional native:

pip install specterqa[native]

Para agentes de IA

Si eres un agente de IA o estás construyendo herramientas para agentes, SpecterQA proporciona interfaces estructuradas para uso programático.

CLI con salida JSON

specterqa run -p myapp --output json

Devuelve JSON estructurado a stdout:

{
  "passed": true,
  "run_id": "GQA-RUN-20260222-143052-a1b2",
  "step_reports": [
    {
      "step_id": "visit_homepage",
      "passed": true,
      "duration_seconds": 12.3
    }
  ],
  "findings": [],
  "cost_usd": 0.4521
}

API de Python

from specterqa.config import SpecterQAConfig
from specterqa.engine.orchestrator import SpecterQAOrchestrator

config = SpecterQAConfig()
config.project_dir = Path(".specterqa")
config.products_dir = Path(".specterqa/products")
config.personas_dir = Path(".specterqa/personas")
config.journeys_dir = Path(".specterqa/journeys")
config.evidence_dir = Path(".specterqa/evidence")
config.anthropic_api_key = "sk-ant-..."
config.budget = 5.00
config.headless = True

orchestrator = SpecterQAOrchestrator(config)
report_md, all_passed = orchestrator.run(product="myapp", level="smoke")

Protocolo federado

SpecterQA expone un módulo protocols.py con clases de Protocol de Python (AIDecider, ActionExecutor) que te permiten intercambiar tu propio modelo de IA o backend de acciones:

from specterqa.engine.protocols import AIDecider, Decision

class MyCustomDecider:
    def decide(self, goal, screenshot_base64, **kwargs) -> Decision:
        # Your logic here
        ...

Servidor MCP

SpecterQA incluye un servidor MCP (Model Context Protocol). Cualquier agente compatible con MCP (Claude Desktop, Cursor, Cline, herramientas personalizadas para agentes) puede descubrir e invocar SpecterQA como herramienta -- ejecutar pruebas, leer resultados, gestionar configuraciones -- sin recurrir a la CLI.

Añade a tu configuración de cliente MCP (claude_desktop_config.json o equivalente):

{
  "specterqa": {
    "command": "specterqa-mcp",
    "args": []
  }
}

Herramientas disponibles:

Herramienta	Descripción
`specterqa_run`	Ejecuta pruebas de comportamiento contra un producto. Síncrono — puede tardar 45-300s. Incurre en costos de API (presupuesto predeterminado: $5.00).
`specterqa_list_products`	Lista los productos configurados y sus recorridos disponibles
`specterqa_get_results`	Recupera los resultados estructurados completos de una ejecución anterior por ID de ejecución
`specterqa_init`	Inicializa un nuevo directorio de proyecto SpecterQA

Consulta docs/for-agents.md para la referencia completa de la API programática y los detalles de integración con MCP.

Referencia de API

La referencia completa de la API está disponible en specterqa.synctek.io/docs.

Clases clave

Clase	Módulo	Descripción
`SpecterQAConfig`	`specterqa.config`	Objeto de configuración raíz. Establece directorios de proyecto, clave de API, presupuesto y preferencias de enrutamiento de modelos.
`SpecterQAOrchestrator`	`specterqa.engine.orchestrator`	Punto de entrada principal para ejecuciones programáticas. Llama a `orchestrator.run(product, level)` para ejecutar un recorrido.
`AIDecider`	`specterqa.engine.protocols`	Clase de Protocol. Implementa para intercambiar un modelo de visión personalizado o backend de decisiones.
`ActionExecutor`	`specterqa.engine.protocols`	Clase de Protocol. Implementa para intercambiar un backend de ejecución de acciones personalizado (por ejemplo, reemplazar Playwright).
`RunReport`	`specterqa.models`	Resultado estructurado devuelto por `orchestrator.run()`. Contiene informes de pasos, hallazgos y desglose de costos.
`Finding`	`specterqa.models`	Problema de UX individual capturado durante una ejecución. Incluye severidad, ID de paso, referencia de captura de pantalla y descripción.

Referencia de CLI

Comando	Descripción
`specterqa run -p PRODUCT`	Ejecuta todos los recorridos de un producto
`specterqa run -p PRODUCT --level smoke`	Ejecuta solo los recorridos etiquetados como smoke
`specterqa run -p PRODUCT --junit-xml results.xml`	Emite JUnit XML para CI
`specterqa run -p PRODUCT --output json`	Emite JSON estructurado a stdout
`specterqa init`	Crea un directorio de proyecto `.specterqa/` con configuraciones de ejemplo
`specterqa install`	Descarga los binarios del navegador Playwright
`specterqa list`	Lista los productos y recorridos configurados
`specterqa results RUN_ID`	Imprime el informe completo de una ejecución anterior
`specterqa-mcp`	Inicia el servidor MCP

Herramientas MCP

Herramienta	Descripción
`specterqa_run`	Ejecuta pruebas de comportamiento. Parámetros: `product` (str), `level` (str, opcional), `directory` (str, opcional). Devuelve un objeto JSON `RunReport`.
`specterqa_list_products`	Lista todos los productos y sus recorridos configurados. No requiere parámetros.
`specterqa_get_results`	Recupera un informe de ejecución anterior por `run_id`.
`specterqa_init`	Inicializa un nuevo proyecto SpecterQA en un `directory` dado.

Para definiciones de esquema, stubs de tipos y detalles del protocolo federado, consulta docs/for-agents.md.

Seguridad

Acceso a directorios: Cuando la variable de entorno SPECTERQA_ALLOWED_DIRS no está definida, el servidor MCP de SpecterQA permite que el parámetro directory de specterqa_run apunte a cualquier ruta del sistema de archivos accesible para el proceso. En entornos compartidos o multiusuario — o en cualquier lugar donde el servidor MCP esté expuesto a agentes no confiables — debes establecer esta variable en una lista de permitidos explícita:

export SPECTERQA_ALLOWED_DIRS="/home/user/projects:/ci/workspaces"

Cuando se establece, el servidor MCP rechaza cualquier valor de directory que no esté bajo uno de los prefijos listados. Esto mitiga el vector de traversal de directorios de MCP descrito en SECURITY_ADVISORY.md (GHSA-SPECTERQA-001).

Corrección de inyección de comandos (v0.2.1): El campo check_command en las definiciones de servicio YAML de producto ha sido eliminado. Era la fuente de una vulnerabilidad crítica de inyección de comandos. Las comprobaciones de requisitos previos ahora se limitan a la conectividad TCP y a las comprobaciones de endpoints de salud HTTP, que son seguras. Consulta SECURITY_ADVISORY.md para obtener todos los detalles. Limpieza de credenciales: Los artefactos de ejecución (archivos de resultados JSON, salida de registros) eliminan automáticamente patrones de credenciales conocidos — claves de API, tokens, contraseñas — del contenido capturado antes de escribirlo en disco.

Reporte de vulnerabilidades: No abras issues públicos para errores de seguridad. Envía un correo a info@synctek.io o consulta SECURITY.md para la política completa de divulgación.

Limitaciones

Sé honesto contigo mismo sobre lo que esto es y no es:

Requiere una clave de API de Anthropic. Sin clave de API, no hay pruebas. No hay un nivel gratuito integrado en SpecterQA en sí.
Cuesta dinero. Cada ejecución realiza llamadas a la API. Un recorrido típico de 3 pasos cuesta $0.30-0.60. El control de presupuesto evita sorpresas, pero el contador siempre está en marcha.
Los modelos de visión no son perfectos. La IA a veces lee mal texto pequeño, hace clic en el elemento equivocado o se confunde con diseños complejos. Es buena, no infalible. Ocasionalmente verás falsos positivos y falsos negativos.
No es un reemplazo para las pruebas unitarias. SpecterQA prueba flujos de UX conductuales. No prueba tu lógica de negocio, integridad de datos o manejo de casos límite. Úsalo junto con tu suite de pruebas existente, no en lugar de ella.
Las pruebas nativas de macOS requieren pyobjc. El extra specterqa[native] incorpora paquetes pyobjc (~200MB). Solo se necesita para pruebas nativas de macOS y del Simulador de iOS.
Software alfa. Versión 0.4.0. Las APIs pueden cambiar. La estructura de archivos puede cambiar. Espera imperfecciones.
Persona única por recorrido (por ahora). Las pruebas concurrentes de múltiples personas (por ejemplo, simular un chat entre dos usuarios) están en la hoja de ruta pero aún no son compatibles.
La reproducción determinista es difícil. Debido a que la IA toma decisiones en tiempo de ejecución, la secuencia exacta de acciones varía entre ejecuciones. Mismo recorrido, misma persona, clics ligeramente diferentes. Esto es por diseño (detecta más problemas) pero hace que la reproducción exacta sea complicada.

Contribuciones

Las contribuciones son bienvenidas. El repositorio está en github.com/SyncTek-LLC/specterqa.

git clone https://github.com/SyncTek-LLC/specterqa.git
cd specterqa
pip install -e ".[dev]"
pytest

Abre un issue antes de comenzar PRs grandes. Preferimos discutir el enfoque primero.

Licencia

MIT -- consulta LICENSE para más detalles.

Construido por SyncTek LLC.