flakiness-knowledge-graph-mcp

Construye un grafo de conocimiento de pruebas inestables a partir del historial de ejecuciones de Playwright

Documentación

📊 flakiness-knowledge-graph-mcp

Un reporter personalizado de Playwright + servidor MCP que construye un grafo de conocimiento local sobre la flakiness a partir del historial de ejecuciones de tus pruebas. Pregunta a tu agente de IA qué pruebas son poco fiables, en qué navegador, y si están empeorando.

🤔 El Problema

Un trace de Playwright te dice qué falló ahora mismo. No te dice si esta prueba ha estado fallando de forma intermitente durante dos semanas, o si solo falla en Firefox en CI, o si se está volviendo más lenta con cada release.

Esta herramienta lo soluciona acumulando el historial de ejecuciones en una base de datos SQLite y exponiéndolo a agentes de IA mediante MCP.

🛠️ Herramientas

Herramienta	Argumentos	Qué devuelve
`get_flaky_tests`	`db_path`, `min_runs?`, `limit?`, `since_days?`	Pruebas ordenadas por tasa de flakiness (fallos+flaky / ejecuciones totales)
`get_test_history`	`db_path`, `test_id`, `limit?`	Historial completo de ejecuciones para una prueba específica — estado, duración, error, reintento, navegador, SO
`get_failure_patterns`	`db_path`, `since_days?`	Tasas de fallo desglosadas por combinación navegador × SO
`get_slow_tests`	`db_path`, `limit?`	Pruebas ordenadas por duración media
`get_error_groups`	`db_path`, `min_failures?`, `limit?`, `since_days?`	Fallos agrupados por prefijo exacto de error — revela causas raíz compartidas entre pruebas
`get_flakiness_trend`	`db_path`, `test_id`, `days?`	Tasa de flakiness diaria durante los últimos N días — muestra si una prueba está empeorando
`cluster_semantic_error_trees`	`db_path`, `min_instances?`, `since_days?`	Como `get_error_groups` pero normaliza primero valores dinámicos (UUIDs, IDs, URLs) y luego fusiona difusamente con Levenshtein
`correlate_git_commit_flakiness`	`db_path`, `min_stable_runs?`, `since_days?`	Encuentra el SHA de commit exacto donde una prueba pasó de estable→flaky (o viceversa), con rama y autor

🚀 Configuración

1. Instalación

npm install -g flakiness-knowledge-graph-mcp

O compila desde el código fuente:

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

2. Añade el reporter a tu proyecto de Playwright

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

Ejecuta tus pruebas normalmente — el reporter escribe cada resultado en flakiness.db automáticamente.

3. Añade el servidor MCP a tu editor

Cursor / VS Code (`.cursor/mcp.json` o `.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. Pruébalo con datos de demostración

¿Aún no tienes un proyecto de Playwright? Genera 30 días de datos de muestra realistas:

npx flakiness-graph-seed ./demo.db

Luego apunta tu agente de IA a ./demo.db para explorar las 8 herramientas.

💬 Ejemplo 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?

Agrupar errores que parecen diferentes pero no lo son

get_error_groups agrupa por prefijo de cadena crudo — si el error contiene un UUID o ID de elemento, crea grupos separados para lo que en realidad es una sola causa raíz. cluster_semantic_error_trees elimina primero los valores dinámicos:

{
  "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"]
    }
  ]
}

Encontrar el commit que rompió una prueba

correlate_git_commit_flakiness usa una máquina de estados — busca ejecuciones donde una prueba fue estable durante ≥3 pases consecutivos y luego falló. El registro de transición incluye el SHA del entorno 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"
    }
  ]
}

El reporter lee GITHUB_SHA / CI_COMMIT_SHA / CIRCLE_SHA1 / GIT_COMMIT automáticamente — no se necesitan cambios de configuración del reporter más allá de actualizar a v0.2.0.

🔗 Funciona muy bien con playwright-trace-decoder-mcp

Estos dos servidores MCP están diseñados para complementarse:

flakiness-knowledge-graph-mcp responde "¿es esta prueba flaky históricamente, y qué commit lo causó?"
playwright-trace-decoder-mcp responde "¿qué falló exactamente en esta ejecución específica?"

Combinados, un agente de IA puede diagnosticar si un fallo de CI es una prueba flaky conocida o una nueva regresión — sin que tengas que abrir un solo archivo.

⚖️ Ejecución en paralelo y sharding de CI

flakiness-knowledge-graph-mcp usa una cola de escritura en proceso para garantizar que los workers paralelos de Playwright dentro de un único proceso de Node no corrompan la base de datos.

Sin embargo, si ejecutas pruebas en múltiples procesos independientes (por ejemplo, shards de CI en paralelo o runners en máquinas separadas) escribiendo en el mismo archivo de red compartido:

Condiciones de carrera: Los sistemas de archivos estándar no garantizan escrituras atómicas para archivos SQLite entre procesos sin bloqueo a nivel de sistema operativo.
Enfoque recomendado: Cada shard de CI debería escribir en su propio archivo de base de datos (por ejemplo, flakiness-shard-1.db, flakiness-shard-2.db).
Fusión: Al final del pipeline de CI, puedes fusionar estos archivos en una única base de datos maestra usando herramientas SQLite estándar o ejecutando un script que lea de una e inserte en la otra.

Para desarrollo local o ejecuciones de CI en una sola máquina, la configuración predeterminada es segura.

🏗️ Arquitectura

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)

sql.js se usa en lugar de better-sqlite3 — SQLite en JavaScript puro compilado a WebAssembly, sin necesidad de compilación nativa. Las columnas de git se añaden mediante la migración ALTER TABLE en el primer uso — las bases de datos existentes se actualizan automáticamente.

📋 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

📄 Licencia

MIT

flakiness-knowledge-graph-mcp

Documentación