flakiness-knowledge-graph-mcp

📊 flakiness-knowledge-graph-mcp

Um reporter personalizado do Playwright + servidor MCP que constrói um grafo de conhecimento de flakiness local a partir do histórico de execuções de testes. Pergunte ao seu agente de IA quais testes são não confiáveis, em qual navegador e se estão piorando.

🤔 O Problema

Um único trace do Playwright informa o que falhou agora. Ele não informa se este teste está falhando silenciosamente há duas semanas, ou se falha apenas no Firefox no CI, ou se está ficando mais lento a cada release.

Esta ferramenta resolve isso acumulando o histórico de execuções em um banco de dados SQLite e expondo-o a agentes de IA via MCP.

🛠️ Ferramentas

Ferramenta	Argumentos	O que retorna
get_flaky_tests	db_path, min_runs?, limit?, since_days?	Testes classificados por taxa de flakiness (falhas+flaky / total de execuções)
get_test_history	db_path, test_id, limit?	Histórico completo de execuções para um teste específico — status, duração, erro, retry, navegador, SO
get_failure_patterns	db_path, since_days?	Taxas de falha detalhadas por combinação de navegador × SO
get_slow_tests	db_path, limit?	Testes classificados por duração média
get_error_groups	db_path, min_failures?, limit?, since_days?	Falhas agrupadas por prefixo exato de erro — revela causas raiz compartilhadas entre testes
get_flakiness_trend	db_path, test_id, days?	Taxa diária de flakiness nos últimos N dias — mostra se um teste está piorando
cluster_semantic_error_trees	db_path, min_instances?, since_days?	Como get_error_groups mas normaliza valores dinâmicos (UUIDs, IDs, URLs) primeiro, depois faz merge difuso com Levenshtein
correlate_git_commit_flakiness	db_path, min_stable_runs?, since_days?	Encontra o SHA exato do commit onde um teste transicionou de estável→flaky (ou vice-versa), com branch e autor

🚀 Configuração

1. Instalação

npm install -g flakiness-knowledge-graph-mcp

Ou compile a partir do código-fonte:

git clone https://github.com/vola-trebla/flakiness-knowledge-graph-mcp.git
cd flakiness-knowledge-graph-mcp
npm install && npm run build

2. Adicione o reporter ao seu projeto Playwright

// playwright.config.ts
export default defineConfig({
  reporter: [["html"], ["flakiness-knowledge-graph-mcp/reporter", { dbPath: "./flakiness.db" }]],
});

Execute seus testes normalmente — o reporter grava cada resultado em flakiness.db automaticamente.

3. Adicione o servidor MCP ao seu editor

Cursor / VS Code (.cursor/mcp.json ou .vscode/mcp.json)

{
  "mcpServers": {
    "flakiness-knowledge-graph": {
      "command": "flakiness-knowledge-graph-mcp"
    }
  }
}

Claude Code

claude mcp add flakiness-knowledge-graph flakiness-knowledge-graph-mcp

4. Experimente com dados de demonstração

Ainda não tem um projeto Playwright? Gere 30 dias de dados de exemplo realistas:

npx flakiness-graph-seed ./demo.db

Então aponte seu agente de IA para ./demo.db para explorar todas as 8 ferramentas.

💬 Exemplo de uso

I've been running my Playwright suite for two weeks. The DB is at /my-project/flakiness.db.

1. get_flaky_tests — which tests are most unreliable? Show last 7 days only.
2. get_test_history for the top flaky test — is it getting worse?
3. get_flakiness_trend for the same test over 14 days — plot the daily rate.
4. get_failure_patterns — does it only fail on a specific browser or OS?
5. cluster_semantic_error_trees — are multiple tests failing with semantically identical errors?
6. correlate_git_commit_flakiness — which commit introduced the flakiness?
7. get_slow_tests — which tests should I optimize for CI speed?

Agrupando erros que parecem diferentes mas não são

O get_error_groups agrupa por prefixo bruto de string — se o erro contém um UUID ou ID de elemento, ele cria grupos separados para o que é realmente uma única causa raiz. O cluster_semantic_error_trees remove valores dinâmicos primeiro:

{
  "total_clusters": 2,
  "clusters": [
    {
      "cluster_id": "cluster-1",
      "canonical_message": "TimeoutError: locator.click: Timeout 30000ms exceeded\n  waiting for locator('#submit-btn')",
      "normalized_message": "TimeoutError: locator.click: Timeout <num>ms exceeded waiting for locator",
      "error_taxonomy": "TimeoutError",
      "instance_count": 14,
      "affected_tests": 3,
      "sample_test_ids": ["checkout > submit order", "cart > add item", "checkout > apply coupon"]
    },
    {
      "cluster_id": "cluster-2",
      "canonical_message": "Error: 2 requests to https://api.example.com/orders/8f3a1c were made. Expected 1",
      "normalized_message": "Error: <num> requests to <url> were made. Expected <num>",
      "error_taxonomy": "AssertionError",
      "instance_count": 6,
      "affected_tests": 1,
      "sample_test_ids": ["api-mock > intercept order"]
    }
  ]
}

Encontrando o commit que quebrou um teste

O correlate_git_commit_flakiness usa uma máquina de estados — ele procura execuções onde um teste estava estável por ≥3 passes consecutivos, depois falhou. O registro de transição inclui o SHA do ambiente de CI:

{
  "total_transitions": 1,
  "transitions": [
    {
      "test_id": "auth > login > should redirect after login",
      "title": "should redirect after login",
      "transition_type": "stable_to_flaky",
      "git_commit_sha": "a3f8c1d9e2b54f6a",
      "git_branch": "main",
      "git_author": "dev-handle",
      "transition_date": "2025-04-14"
    }
  ]
}

O reporter lê GITHUB_SHA / CI_COMMIT_SHA / CIRCLE_SHA1 / GIT_COMMIT automaticamente — nenhuma mudança de configuração do reporter é necessária além de atualizar para v0.2.0.

🔗 Funciona muito bem com playwright-trace-decoder-mcp

Esses dois servidores MCP são projetados para se complementarem:

• flakiness-knowledge-graph-mcp responde "este teste é flaky historicamente, e qual commit causou isso?"
• playwright-trace-decoder-mcp responde "o que exatamente falhou nesta execução específica?"

Combinados, um agente de IA pode diagnosticar se uma falha de CI é um teste flaky conhecido ou uma nova regressão — sem você abrir um único arquivo.

⚖️ Execução Paralela e Sharding de CI

O flakiness-knowledge-graph-mcp usa uma fila de escrita em processo para garantir que workers paralelos do Playwright dentro de um único processo Node não corrompam o banco de dados.

No entanto, se você executar testes em múltiplos processos independentes (ex.: shards de CI paralelos ou runners em máquinas separadas) gravando no mesmo arquivo de rede compartilhado:

1. Condições de corrida: Sistemas de arquivos padrão não garantem gravações atômicas para arquivos SQLite entre processos sem bloqueio em nível de SO.
2. Abordagem recomendada: Cada shard de CI deve gravar em seu próprio arquivo de banco de dados (ex.: flakiness-shard-1.db, flakiness-shard-2.db).
3. Mesclagem: No final do pipeline de CI, você pode mesclar esses arquivos em um único banco de dados mestre usando ferramentas SQLite padrão ou executando um script que lê de um e insere no outro.

Para desenvolvimento local ou execuções de CI em uma única máquina, a configuração padrão é segura.

🏗️ Arquitetura

playwright.config.ts
  └── FlakinessReporter → flakiness.db (SQLite via sql.js)

flakiness.db
  └── test_runs table
        id, test_id, title, suite, file,
        status, duration_ms, browser, os,
        timestamp, error, retry,
        git_commit_sha, git_branch, git_author   ← added in v0.2.0

MCP server
  └── reads flakiness.db on demand (in-process handle reuse)

O sql.js é usado em vez de better-sqlite3 — SQLite puro em JavaScript compilado para WebAssembly, sem necessidade de compilação nativa. As colunas git são adicionadas via migração ALTER TABLE no primeiro uso — bancos de dados existentes são atualizados automaticamente.

📋 Scripts

npm run build        # compile TypeScript → dist/
npm run lint         # ESLint
npm run format       # Prettier --write
npm run format:check # Prettier check (used in CI)
npm run seed         # populate flakiness.db with 30 days of demo data

📄 Licença

MIT