Matware E2E Runner

Com o pool Docker, o Chrome roda dentro de um contêiner, então localhost lá significa o contêiner — não sua máquina. host.docker.internal faz a ponte para o seu host. No Linux (Docker Engine, não Docker Desktop) adicione --add-host=host.docker.internal:host-gateway, ou use seu IP LAN. As opções 1 & 2 não têm isso — o navegador é local, então localhost simplesmente funciona.

cp node_modules/@matware/e2e-runner/opencode.json ./
mkdir -p .opencode && cp -r node_modules/@matware/e2e-runner/.opencode/* .opencode/

Veja OPENCODE.md para detalhes.

Cada arquivo .json em e2e/tests/ contém um array de testes. Cada teste tem um name e actions sequenciais:

[
  {
    "name": "homepage-loads",
    "actions": [
      { "type": "goto", "value": "/" },
      { "type": "assert_visible", "selector": "body" },
      { "type": "assert_url", "value": "/" },
      { "type": "screenshot", "value": "homepage.png" }
    ]
  }
]

Arquivos de suíte podem ter prefixos numéricos para ordenação (01-auth.json, 02-dashboard.json). A flag --suite corresponde com ou sem o prefixo, então --suite auth encontra 01-auth.json.

Clicar por texto — quando click usa text em vez de selector, ele busca em elementos interativos e de conteúdo comuns:

button, a, [role="button"], [role="tab"], [role="menuitem"], [role="option"],
[role="listitem"], div[class*="cursor"], span, li, td, th, label, p, h1-h6

{ "type": "click", "text": "Sign In" }

Estas ações lidam com padrões comuns em aplicativos React/MUI que normalmente exigem boilerplate verboso de evaluate:

// Before: 5 lines of evaluate boilerplate
{ "type": "evaluate", "value": "const input = document.querySelector('#search'); const nativeSet = Object.getOwnPropertyDescriptor(window.HTMLInputElement.prototype, 'value').set; nativeSet.call(input, 'term'); input.dispatchEvent(new Event('input', {bubbles: true})); input.dispatchEvent(new Event('change', {bubbles: true}));" }

// After: 1 action
{ "type": "type_react", "selector": "#search", "value": "term" }

Todas as ações subsequentes são executadas na aba ativa:

{ "type": "click", "text": "Open report" }
{ "type": "wait_for_tab", "text": "report" }
{ "type": "assert_text", "text": "Quarterly results" }
{ "type": "close_tab" }

Tentativa em nível de teste — tenta novamente um teste inteiro em caso de falha. Defina globalmente via config ou por teste:

{ "name": "flaky-test", "retries": 3, "timeout": 15000, "actions": [...] }

Testes que passam após a tentativa são marcados como flaky no relatório e no sistema de aprendizado.

Tentativa em nível de ação — tenta novamente uma única ação sem reexecutar o teste inteiro. Útil para cliques e esperas sensíveis a tempo:

{ "type": "click", "selector": "#dynamic-btn", "retries": 3 }
{ "type": "wait", "selector": ".lazy-loaded", "retries": 2 }

Defina globalmente: actionRetries na config, --action-retries <n> na CLI ou variável de ambiente ACTION_RETRIES. Atraso entre tentativas: actionRetryDelay (padrão 500ms).

Testes que compartilham estado (ex.: dois testes modificando o mesmo registro) podem competir quando executados em paralelo. Marque-os como seriais:

{ "name": "create-patient", "serial": true, "actions": [...] }
{ "name": "verify-patient-list", "serial": true, "actions": [...] }

Testes seriais são executados um de cada vez após todos os testes paralelos terminarem — prevenindo interferência sem desacelerar testes independentes.

A abordagem mais simples — faça login pela interface como um usuário real:

{
  "hooks": {
    "beforeEach": [
      { "type": "goto", "value": "/login" },
      { "type": "type", "selector": "#email", "value": "test@example.com" },
      { "type": "type", "selector": "#password", "value": "test-password" },
      { "type": "click", "text": "Sign In" },
      { "type": "wait", "selector": ".dashboard" }
    ]
  },
  "tests": [...]
}

Para SPAs com JWT, pule o formulário de login injetando o token diretamente:

{ "type": "set_storage", "value": "accessToken=eyJhbGciOiJIUzI1NiIs..." }

Ou defina globalmente na config:

// e2e.config.js
export default {
  authToken: 'eyJhbGciOiJIUzI1NiIs...',
  authStorageKey: 'accessToken',
};

Cada teste é executado em um contexto de navegador novo, então o estado de autenticação é automaticamente limpo entre testes.

Mais estratégias: Autenticação baseada em cookies, injeção de cabeçalho HTTP, bypass de OAuth/SSO, módulos de autenticação reutilizáveis e testes baseados em papéis — veja docs/authentication.md

Extraia fluxos comuns em módulos parametrizados:

// e2e/modules/login.json
{
  "$module": "login",
  "description": "Log in via the UI login form",
  "params": {
    "email": { "required": true, "description": "User email" },
    "password": { "required": true, "description": "User password" }
  },
  "actions": [
    { "type": "goto", "value": "/login" },
    { "type": "type", "selector": "#email", "value": "{{email}}" },
    { "type": "type", "selector": "#password", "value": "{{password}}" },
    { "type": "click", "text": "Sign In" },
    { "type": "wait", "value": "2000" }
  ]
}

Use em testes:

{
  "name": "dashboard-loads",
  "actions": [
    { "$use": "login", "params": { "email": "user@test.com", "password": "secret" } },
    { "type": "assert_text", "text": "Dashboard" }
  ]
}

Módulos suportam validação de parâmetros (parâmetros obrigatórios falham rapidamente), blocos condicionais ({{#param}}...{{/param}}), composição aninhada e detecção de ciclos.

Execute ações em pontos do ciclo de vida. Defina globalmente na config ou por suíte:

{
  "hooks": {
    "beforeAll": [{ "type": "goto", "value": "/setup" }],
    "beforeEach": [{ "type": "goto", "value": "/" }],
    "afterEach": [{ "type": "screenshot", "value": "after.png" }],
    "afterAll": []
  },
  "tests": [...]
}

Importante: beforeAll é executado em uma página de navegador separada que é fechada antes dos testes começarem. Use beforeEach para estado que os testes precisam (cookies, localStorage, tokens de autenticação).

Pule testes exploratórios ou rascunhos de execuções --all:

// e2e.config.js
export default {
  exclude: ['explore-*', 'debug-*', 'draft-*'],
};

Execuções de suíte individuais (--suite) não são afetadas por padrões de exclusão.

claude plugin marketplace add fastslack/mtw-e2e-runner
claude plugin install e2e-runner@matware

Isso dá ao Claude 17 ferramentas MCP, uma skill de fluxo de trabalho, 4 comandos de barra (/e2e-runner:run, /e2e-runner:create-test, /e2e-runner:verify-issue, /e2e-runner:capture) e 3 agentes especializados (test-analyzer, test-creator, test-improver).

Instalação somente MCP (apenas ferramentas, sem skill/comandos/agentes):

claude mcp add --transport stdio --scope user e2e-runner \
  -- npx -y -p @matware/e2e-runner e2e-runner-mcp

cp node_modules/@matware/e2e-runner/opencode.json ./
mkdir -p .opencode && cp -r node_modules/@matware/e2e-runner/.opencode/* .opencode/

Veja OPENCODE.md para detalhes.

Iniciar/parar o pool são apenas via CLI — não expostos via MCP.

Descreva como a página deve parecer — a IA julga passou/falhou a partir das capturas de tela:

{
  "name": "dashboard-loads",
  "expect": "Patient list with at least 3 rows, no error messages, sidebar with navigation links",
  "actions": [
    { "type": "goto", "value": "/dashboard" },
    { "type": "wait", "selector": ".patient-list" }
  ]
}

Após as ações do teste serem concluídas, o runner captura automaticamente uma captura de tela de verificação. A resposta do MCP inclui o hash da captura de tela — o Claude Code a recupera e verifica visualmente contra sua descrição expect. Nenhuma chave de API é necessária.

Como funciona:

1. Buscar — Obtém os detalhes da issue (título, corpo, labels) via CLI gh ou glab
2. Gerar — A IA cria ações de teste em JSON com base na descrição da issue
3. Executar — Opcionalmente, executa os testes imediatamente para verificar se um bug é reproduzível

# Fetch and display
e2e-runner issue https://github.com/owner/repo/issues/42

# Generate a test file via Claude API
e2e-runner issue https://github.com/owner/repo/issues/42 --generate

# Generate + run + report
e2e-runner issue https://github.com/owner/repo/issues/42 --verify
# -> "BUG CONFIRMED" or "NOT REPRODUCIBLE"

No Claude Code, basta pedir:

"Busque a issue #42 e crie testes E2E para ela"

Lógica de verificação de bugs: Os testes gerados verificam o comportamento correto. Falha no teste = bug confirmado. Todos os testes passam = não reproduzível.

Autenticação: O GitHub exige a CLI gh, o GitLab exige a CLI glab. O GitLab self-hosted é suportado.

Execução ao vivo — monitore testes em tempo real com progresso passo a passo, durações e contagem de workers ativos.

Suites de teste — navegue por todas as suites entre projetos. Execute uma única suite ou todos os testes com um clique.

Histórico de execuções — acompanhe tendências de taxa de aprovação com o gráfico integrado. Clique em qualquer linha para expandir os detalhes completos.

Detalhe da execução — selos de PASS/FAIL, miniaturas de capturas de tela com hashes copiáveis (ss:77c28b5a), erros de console formatados e logs de requisições de rede.

Galeria de capturas de tela — navegue por todas as capturas de tela com busca por hash (capturas de ação, erro e verificação).

Status do pool — saúde do pool do Chrome: slots disponíveis, sessões em execução, pressão de memória.

O runner aprende com cada execução de teste — construindo conhecimento sobre sua suite de testes ao longo do tempo. Consulte insights por meio da ferramenta MCP e2e_learnings:

Armazenamento e exportação:

• SQLite (~/.e2e-runner/dashboard.db) — padrão, sem configuração
• Grafo de conhecimento Neo4j — opcional, para análise baseada em relacionamentos. Gerencie por meio da ferramenta MCP e2e_neo4j ou docker compose
• Relatório Markdown (e2e/learnings.md) — gerado automaticamente após cada execução

Narração de teste: Cada execução de teste gera uma narrativa legível do que aconteceu passo a passo, visível na saída da CLI e no dashboard.

Asserção explícita — coloque assert_no_network_errors após carregamentos críticos de página:

{ "type": "goto", "value": "/dashboard" },
{ "type": "wait", "selector": ".loaded" },
{ "type": "assert_no_network_errors" }

Flag global — defina failOnNetworkError: true para falhar automaticamente qualquer teste com erros de rede:

e2e-runner run --all --fail-on-network-error

Quando desabilitado (padrão), o runner ainda coleta e relata erros de rede — a resposta do MCP inclui um aviso quando os testes passam, mas têm erros de rede.

Registro completo de rede — todas as requisições XHR/fetch são capturadas com URL, método, status, duração, cabeçalhos de requisição/resposta e corpo da resposta (truncado em 50KB). Visualizável no dashboard com linhas expansíveis de detalhes de requisição.

Fluxo de detalhamento do MCP:

1. e2e_run          → compact networkSummary + runDbId
2. e2e_network_logs(runDbId)                     → all requests (url, method, status, duration)
3. e2e_network_logs(runDbId, errorsOnly: true)   → only failed requests
4. e2e_network_logs(runDbId, includeHeaders: true) → with headers
5. e2e_network_logs(runDbId, includeBodies: true)  → full request/response bodies

A resposta do e2e_run permanece compacta (~5KB) independentemente de quantas requisições foram capturadas. Use e2e_network_logs com o runDbId retornado para detalhar sob demanda.

Capture capturas de tela de qualquer URL sob demanda — sem necessidade de suite de testes:

e2e-runner capture https://example.com
e2e-runner capture https://example.com --full-page --selector ".loaded" --delay 2000

Por meio do MCP, a ferramenta e2e_capture suporta authToken e authStorageKey para páginas autenticadas — ela injeta o token no localStorage antes de navegar.

Cada captura de tela recebe um hash determinístico (ss:a3f2b1c9). Use e2e_screenshot para recuperar qualquer captura de tela por hash — ela retorna a imagem com metadados (nome do teste, etapa, tipo).

{
  "tests": [
    {
      "name": "checkout flow (heavy JS, real Chrome)",
      "driver": "browserless",
      "actions": [...]
    },
    {
      "name": "scrape product page (lightweight)",
      "driver": "obscura",
      "fallbackDriver": "cdp",
      "actions": [...]
    }
  ]
}

driver é opcional. Se definido, apenas pools cujo driver detectado corresponda se tornam candidatos. fallbackDriver é opt-in explícito — sem ele, um driver de destino ausente falha o teste com uma mensagem clara. A ocupação do pool não aciona fallback; o runner aguarda dentro do conjunto filtrado.

Force um driver para uma execução inteira (as substituições da CLI vencem os campos por teste — útil para benchmarks A/B):

e2e-runner run --all --driver obscura
e2e-runner run --all --driver obscura --fallback-driver cdp

# browserless (default) — managed by `pool start`
e2e-runner pool start

# Lightpanda — pool start uses templates/docker-compose-lightpanda.yml
e2e-runner pool start                 # with poolDriver: 'lightpanda' in config

# Obscura — install the binary and run it yourself
curl -LO https://github.com/h4ckf0r0day/obscura/releases/latest/download/obscura-x86_64-linux.tar.gz
tar xzf obscura-x86_64-linux.tar.gz
./obscura serve --port 9222 --stealth
# then point the runner at it: poolUrls: ['http://localhost:9222'], poolDriver: 'obscura'

# Run tests
e2e-runner run --all                  # All suites
e2e-runner run --suite auth           # Single suite
e2e-runner run --tests path/to.json   # Specific file
e2e-runner run --inline '<json>'      # Inline JSON

# Pool management (CLI only, not MCP)
e2e-runner pool start                 # Start Chrome container
e2e-runner pool stop                  # Stop Chrome container
e2e-runner pool status                # Check pool health

# Issue-to-test
e2e-runner issue <url>                # Fetch issue
e2e-runner issue <url> --generate     # Generate test via AI
e2e-runner issue <url> --verify       # Generate + run + report

# Dashboard
e2e-runner dashboard                  # Start web dashboard

# Other
e2e-runner list                       # List available suites
e2e-runner capture <url>              # On-demand screenshot
e2e-runner init                       # Scaffold project

Crie e2e.config.js na raiz do seu projeto:

export default {
  baseUrl: 'http://host.docker.internal:3000',
  concurrency: 4,
  retries: 2,
  actionRetries: 1,
  testTimeout: 30000,
  outputFormat: 'both',
  failOnNetworkError: true,
  exclude: ['explore-*', 'debug-*'],

  hooks: {
    beforeEach: [{ type: 'goto', value: '/' }],
  },

  environments: {
    staging: { baseUrl: 'https://staging.example.com' },
    production: { baseUrl: 'https://example.com', concurrency: 5 },
  },
};

Prioridade de configuração (a maior vence):

1. Flags da CLI
2. Variáveis de ambiente
3. Arquivo de configuração (e2e.config.js ou e2e.config.json)
4. Padrões

Quando --env <name> está definido, o perfil correspondente substitui tudo.

e2e-runner run --all --output junit

jobs:
  e2e:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm ci
      - run: npx e2e-runner pool start
      - run: npx e2e-runner run --all --output junit
      - uses: mikepenz/action-junit-report@v4
        if: always()
        with:
          report_paths: e2e/screenshots/junit.xml

import { createRunner } from '@matware/e2e-runner';

const runner = await createRunner({ baseUrl: 'http://localhost:3000' });

const report = await runner.runAll();
const report = await runner.runSuite('auth');
const report = await runner.runFile('e2e/tests/login.json');
const report = await runner.runTests([
  { name: 'quick-check', actions: [{ type: 'goto', value: '/' }] },
]);