GhostQA

O GhostQA envia personas de IA pelo seu aplicativo — elas olham para a tela, decidem o que fazer e interagem como humanos reais. Sem scripts de teste. Sem seletores. Você descreve personas e jornadas em YAML, e o GhostQA cuida do resto.

GitHubExperimente este MCPPatrocinado

Documentação

SpecterQA

Personas de IA percorrem seu aplicativo para que usuários reais não tropecem.

O SpecterQA envia personas de IA pelo seu aplicativo — elas olham a tela, decidem o que fazer e interagem como humanos reais. Sem scripts de teste. Sem seletores. Você descreve personas e jornadas em YAML, e o SpecterQA cuida do 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                            ┃
┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛

O que é isso?

Testes E2E tradicionais são frágeis. Você escreve seletores, eles quebram. Você mantém scripts, eles apodrecem. O SpecterQA adota uma abordagem diferente: modelos de visão de IA olham para sua interface real e navegam por ela como uma pessoa faria.

Você define personas (quem está usando seu aplicativo) e jornadas (o que elas estão tentando fazer). O mecanismo do SpecterQA tira uma captura de tela, envia para um modelo de visão Claude, recebe uma decisão ("clique neste botão", "preencha este campo"), executa via Playwright, tira outra captura de tela e repete até que o objetivo seja alcançado ou algo dê errado.

Quando algo dá errado, você obtém evidências: capturas de tela, observações de UX, detalhamentos de custo e descobertas categorizadas por severidade.

Instalação

O SpecterQA é distribuído via PyPI e requer Python 3.10 ou posterior.

pip install specterqa

Após a instalação, baixe os binários do navegador Playwright:

specterqa install

Para testes de aplicativos nativos macOS e suporte ao Simulador iOS, instale o extra opcional native:

pip install specterqa[native]

Para suporte ao servidor MCP (integrando o SpecterQA como ferramenta no Claude Desktop, Cursor ou outros clientes MCP):

pip install specterqa[mcp]

Você também precisará de uma chave de API da Anthropic para executar testes:

export ANTHROPIC_API_KEY=sk-ant-...

Para verificar a instalação:

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

Início 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

Você precisará de uma chave de API da Anthropic:

export ANTHROPIC_API_KEY=sk-ant-...

É isso. Três comandos e uma chave de API.

Como Funciona

O ciclo principal é simples:

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

Captura de tela -- O Playwright captura o estado atual da página como PNG
Decisão -- Um modelo de visão Claude recebe a captura de tela + contexto da persona + objetivo, retorna uma ação JSON estruturada (click, fill, navigate, scroll, keyboard, wait, done ou stuck)
Execução -- O Playwright executa a ação (clique em coordenadas, digitar texto, navegar para URL, etc.)
Repetição -- Loop até que o objetivo seja alcançado, o agente fique preso ou o orçamento acabe

O perfil da persona molda como a IA se comporta. Um "desenvolvedor experiente em tecnologia" explora de forma diferente de um "usuário de primeira viagem frustrado". A paciência da persona, o conforto com tecnologia e as frustrações influenciam o prompt do sistema.

Roteamento de modelos mantém os custos baixos. Ações simples (clique, rolagem) usam Haiku. Ações complexas (preenchimento de formulários, avaliação inicial) usam Sonnet. Você também pode rotear ações simples para um modelo Ollama local (llava:13b) para custo zero de API em navegação direta.

Recursos

Testes baseados em persona -- Defina usuários de IA com históricos, objetivos, frustrações e níveis de conforto com tecnologia. Eles não apenas seguem scripts; eles reagem ao que veem.
Baseado em visão -- Sem seletores, sem consultas ao DOM. A IA interpreta capturas de tela como um humano faria. Detecta problemas visuais/layout que testes baseados em seletores perdem completamente.
Configurado via YAML -- Produtos, personas e jornadas são todos arquivos YAML. Gerentes de produto podem lê-los. Sem código para manter.
Controle de orçamento -- Limites de custo por execução, por dia e por mês. O mecanismo para imediatamente se você atingir o limite. Sem contas surpresa.
Saída JUnit XML -- Solte o --junit-xml results.xml e conecte-o a qualquer sistema de CI.
Roteamento de modelos em camadas -- Haiku para navegação barata, Sonnet para raciocínio complexo, Ollama local opcional para ações simples com custo zero.
Multiplataforma -- Aplicativos web (via Playwright), aplicativos nativos macOS (via API de Acessibilidade + pyobjc), Simulador iOS (via simctl). Mesmo formato YAML, executores diferentes.
Coleta de evidências -- Cada execução produz capturas de tela, um relatório de descobertas, detalhamento de custos e um resultado JSON estruturado. Tudo é salvo em um diretório de evidências.
Detecção de travamento -- Se a IA repete a mesma ação ou a interface para de mudar, o mecanismo escala para um modelo mais forte e, em seguida, aborta se nada funcionar. Sem loops infinitos.
Variáveis de modelo -- Use {{persona.credentials.email}} nas etapas da sua jornada. As variáveis são resolvidas a partir das configurações da persona em tempo de execução.
Verificações de pré-condição -- Verifique se os serviços estão ativos antes de executar os testes. Falhe rapidamente com erros claros em vez de desperdiçar chamadas de API.

Configuração

O SpecterQA usa três tipos de arquivos de configuração YAML, todos localizados em .specterqa/:

Produto (`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!"

Jornada (`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"

Consulte docs/configuration.md para a referência completa.

Suporte a esquema YAML

O SpecterQA inclui um JSON Schema para arquivos YAML de produto em schemas/product.schema.json.

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

Integração com CI

O SpecterQA é feito para CI. Ele roda em modo headless por padrão e retorna códigos de saída adequados.

# 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 saída:

0 -- todos os testes passaram
1 -- um ou mais testes falharam
2 -- erro de configuração
3 -- erro de infraestrutura (dependências ausentes, API inacessível)

Consulte docs/ci-integration.md para exemplos de GitHub Actions, GitLab CI e CircleCI.

Custo

O SpecterQA usa a API Claude da Anthropic. Cada execução custa dinheiro. Aqui está o que esperar:

Model	Função	Entrada (por 1M tokens)	Saída (por 1M tokens)
Claude Haiku 4.5	Navegação simples	$0.80	$4.00
Claude Sonnet 4	Raciocínio complexo	$3.00	$15.00
Ollama llava:13b	Fallback local	Grátis	Grátis

Custos típicos por execução:

Teste de fumaça de 3 etapas: ~$0.30-0.60
Jornada padrão de 5 etapas: ~$0.50-1.50
Jornada complexa de 10 etapas com formulários: ~$1.00-3.00

O orçamento padrão é $5.00 por execução. O mecanismo para imediatamente se o orçamento for excedido -- sem estouros silenciosos. Você também pode definir limites por dia e por mês.

Você também pode definir um orçamento padrão via variável de ambiente para evitar passar --budget toda 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)

O roteamento de modelos ajuda: cliques e rolagens simples usam Haiku (~~$0.01 por ação), enquanto preenchimentos de formulários e avaliações iniciais usam Sonnet (~~$0.03-0.05 por ação). Se você tiver uma instância local do Ollama, ações simples podem ser roteadas para lá com custo zero de API.

Consulte docs/cost-guide.md para detalhamentos de custo e estratégias de orçamento.

Multiplataforma

O SpecterQA não é apenas para web. O mesmo formato YAML de persona/jornada funciona em várias plataformas:

Aplicativos web (padrão) -- Usa Playwright para automação de navegador.

Aplicativos nativos macOS -- Usa a API de Acessibilidade do macOS via pyobjc. A IA lê a árvore de acessibilidade e capturas de tela, depois executa cliques e teclas através de ações AX.

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

Simulador iOS -- Usa simctl para capturas de tela e simulação de toque. Útil para testar aplicativos iOS sem um 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"

O suporte a nativos e simulador requer a dependência opcional native:

pip install specterqa[native]

Para Agentes de IA

Se você é um agente de IA ou está construindo ferramentas para agentes, o SpecterQA fornece interfaces estruturadas para uso programático.

CLI com saída JSON

specterqa run -p myapp --output json

Retorna JSON estruturado para 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 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

O SpecterQA expõe um módulo protocols.py com classes Protocol Python (AIDecider, ActionExecutor) que permitem substituir seu próprio modelo de IA ou backend de ações:

from specterqa.engine.protocols import AIDecider, Decision

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

Servidor MCP

O SpecterQA inclui um servidor MCP (Model Context Protocol). Qualquer agente compatível com MCP (Claude Desktop, Cursor, Cline, ferramentas personalizadas para agentes) pode descobrir e invocar o SpecterQA como ferramenta -- executar testes, ler resultados, gerenciar configurações -- sem precisar usar a CLI.

Adicione à configuração do seu cliente MCP (claude_desktop_config.json ou equivalente):

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

Ferramentas disponíveis:

Ferramenta	Descrição
`specterqa_run`	Executa testes comportamentais contra um produto. Síncrono — pode levar 45-300s. Incorre em custos de API (orçamento padrão: $5.00).
`specterqa_list_products`	Lista produtos configurados e suas jornadas disponíveis
`specterqa_get_results`	Recupera resultados estruturados completos de uma execução anterior pelo ID da execução
`specterqa_init`	Inicializa um novo diretório de projeto SpecterQA

Consulte docs/for-agents.md para a referência completa da API programática e detalhes de integração MCP.

Referência da API

A referência completa da API está disponível em specterqa.synctek.io/docs.

Classes principais

Classe	Módulo	Descrição
`SpecterQAConfig`	`specterqa.config`	Objeto de configuração raiz. Define diretórios do projeto, chave de API, orçamento e preferências de roteamento de modelos.
`SpecterQAOrchestrator`	`specterqa.engine.orchestrator`	Ponto de entrada principal para execuções programáticas. Chame `orchestrator.run(product, level)` para executar uma jornada.
`AIDecider`	`specterqa.engine.protocols`	Classe Protocol. Implemente para substituir um modelo de visão personalizado ou backend de decisão.
`ActionExecutor`	`specterqa.engine.protocols`	Classe Protocol. Implemente para substituir um backend de execução de ações personalizado (por exemplo, substituir o Playwright).
`RunReport`	`specterqa.models`	Resultado estruturado retornado por `orchestrator.run()`. Contém relatórios de etapas, descobertas e detalhamento de custos.
`Finding`	`specterqa.models`	Problema individual de UX capturado durante uma execução. Inclui severidade, ID da etapa, referência de captura de tela e descrição.

Referência da CLI

Comando	Descrição
`specterqa run -p PRODUCT`	Executa todas as jornadas de um produto
`specterqa run -p PRODUCT --level smoke`	Executa apenas jornadas marcadas como smoke
`specterqa run -p PRODUCT --junit-xml results.xml`	Emite JUnit XML para CI
`specterqa run -p PRODUCT --output json`	Emite JSON estruturado para stdout
`specterqa init`	Cria um diretório de projeto `.specterqa/` com configurações de exemplo
`specterqa install`	Baixa os binários do navegador Playwright
`specterqa list`	Lista produtos e jornadas configurados
`specterqa results RUN_ID`	Imprime o relatório completo de uma execução anterior
`specterqa-mcp`	Inicia o servidor MCP

Ferramentas MCP

Ferramenta	Descrição
`specterqa_run`	Executa testes comportamentais. Parâmetros: `product` (str), `level` (str, opcional), `directory` (str, opcional). Retorna um objeto JSON `RunReport`.
`specterqa_list_products`	Lista todos os produtos e suas jornadas configuradas. Nenhum parâmetro necessário.
`specterqa_get_results`	Recupera um relatório de execução anterior por `run_id`.
`specterqa_init`	Inicializa um novo projeto SpecterQA em um determinado `directory`.

Para definições de esquema, stubs de tipo e detalhes do protocolo federado, consulte docs/for-agents.md.

Segurança

Acesso a diretórios: Quando a variável de ambiente SPECTERQA_ALLOWED_DIRS não está definida, o servidor MCP do SpecterQA permite que o parâmetro directory de specterqa_run aponte para qualquer caminho no sistema de arquivos acessível ao processo. Em ambientes compartilhados ou multiusuário — ou em qualquer lugar onde o servidor MCP esteja exposto a agentes não confiáveis — você deve definir essa variável como uma lista de permissões explícita:

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

Quando definida, o servidor MCP rejeita qualquer valor de directory que não esteja sob um dos prefixos listados. Isso mitiga o vetor de travessia de diretórios do MCP descrito em SECURITY_ADVISORY.md (GHSA-SPECTERQA-001).

Correção de injeção de comandos (v0.2.1): O campo check_command nas definições de serviço YAML do produto foi removido. Ele era a fonte de uma vulnerabilidade crítica de injeção de comandos. As verificações de pré-condição agora são limitadas a verificações de conectividade TCP e endpoints de saúde HTTP, que são seguras. Consulte SECURITY_ADVISORY.md para detalhes completos. Limpeza de credenciais: Os artefatos de execução (arquivos de resultados JSON, saída de logs) removem automaticamente padrões de credenciais conhecidos — chaves de API, tokens, senhas — do conteúdo capturado antes de gravar em disco.

Reportando vulnerabilidades: Não abra issues públicas para bugs de segurança. Envie um e-mail para info@synctek.io ou consulte SECURITY.md para a política completa de divulgação.

Limitações

Seja honesto consigo mesmo sobre o que isso é e o que não é:

Requer uma chave de API da Anthropic. Sem chave de API, sem testes. Não há camada gratuita embutida no próprio SpecterQA.
Custa dinheiro. Cada execução faz chamadas de API. Uma jornada típica de 3 etapas custa US$ 0,30–0,60. A aplicação de orçamento evita surpresas, mas o medidor está sempre rodando.
Os modelos de visão não são perfeitos. A IA às vezes lê mal textos pequenos, clica no elemento errado ou se confunde com layouts complexos. É bom, não infalível. Você verá ocasionalmente falsos positivos e falsos negativos.
Não substitui testes de unidade. O SpecterQA testa fluxos comportamentais de UX. Ele não testa sua lógica de negócios, integridade de dados ou tratamento de casos extremos. Use-o junto com sua suíte de testes existente, não no lugar dela.
Testes nativos de macOS exigem pyobjc. O extra specterqa[native] inclui pacotes pyobjc (~200MB). Necessário apenas para testes nativos de macOS e iOS Simulator.
Software alfa. Versão 0.4.0. As APIs podem mudar. A estrutura de arquivos pode mudar. Espere arestas a serem aparadas.
Persona única por jornada (por enquanto). Testes simultâneos com múltiplas personas (por exemplo, simulando um chat entre dois usuários) estão no roadmap, mas ainda não são suportados.
A reprodução determinística é difícil. Como a IA toma decisões em tempo de execução, a sequência exata de ações varia entre execuções. Mesma jornada, mesma persona, cliques ligeiramente diferentes. Isso é proposital (captura mais problemas), mas torna a reprodução exata complicada.

Contribuindo

Contribuições são bem-vindas. O repositório está em github.com/SyncTek-LLC/specterqa.

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

Abra uma issue antes de iniciar PRs grandes. Preferimos discutir a abordagem primeiro.

Licença

MIT — consulte LICENSE para detalhes.

Construído por SyncTek LLC.