test-trust

Les dice a los agentes de codificación de IA (Claude Code, Codex, OpenHands, Cursor o un modelo local — agnóstico al agente mediante MCP, el Protocolo de Contexto de Modelo) no solo qué pruebas cubren un cambio, sino si esas pruebas pueden ser realmente confiables para detectar una regresión allí.

«CI está en verde» y «este cambio es seguro» son tratados como lo mismo por todos los agentes hoy en día. No lo son. Una prueba que cubre una función no es lo mismo que una prueba que realmente fallaría si esa función se rompiera: las pruebas con exceso de mocks, las pruebas de instantánea que simplemente vuelven a grabar lo que sea que sea la nueva salida, y las pruebas sin aserciones muestran verde mientras no detectan nada.

Cómo

1. Pruebas de mutación (envuelve motores existentes maduros, no reimplementados — mutmut para Python, StrykerJS para JS/TS, gremlins para Go, cargo-mutants para Rust): introduce deliberadamente pequeños errores en el código modificado y comprueba si las pruebas que lo cubren realmente fallan. La selección de pruebas por mutante proviene de los datos de cobertura de cada motor, no se reimplementa aquí — mutmut y Stryker (donde hay un runner compatible: jest/mocha/vitest) seleccionan solo las pruebas específicas que cubren cada mutante; gremlins y cargo-mutants omiten mutantes con cobertura cero pero vuelven a ejecutar la suite de pruebas relevante completa para cada mutante que tenga alguna, un mecanismo más grueso (y más lento en repos grandes) pero igualmente correcto.

2. Delimitación por diff (nuestra): mapea las líneas modificadas de un diff de git a la función que las contiene mediante el análisis sintáctico propio de cada lenguaje, de modo que tanto la ejecución de mutaciones como la puntuación de confianza se limitan a lo que realmente cambió, no a un archivo/repo completo.

3. Fusión (la parte nueva, no construida en ningún otro lugar — verificado): combina lo anterior en una puntuación de confianza por función modificada, expuesta como una herramienta MCP que cualquier agente puede llamar antes de tratar una ejecución de pruebas en verde como evidencia de seguridad.

Consulta examples/weak-test-fixture/ (Python), examples/weak-test-fixture-js/ (JS), examples/weak-test-fixture-go/ (Go), examples/weak-test-fixture-rust/ (Rust), examples/plug-and-play-fixture/ (sin configuración alguna) y examples/multi-file-fixture-js/ (una función que importa un módulo hermano, lo que demuestra que la delimitación por mutación no rompe las importaciones entre archivos) para ver demostraciones funcionales y en vivo: una función cubierta por una prueba que pasa hoy pero que no detectaría un error real.

Related MCP server: sumo-qa

Validado contra repos reales, no solo fixtures

Cada fixture anterior es un juguete. Antes de confiar en el concepto, esto también se ejecutó con configuración cero contra repositorios reales, externos y sin modificar en los cuatro lenguajes: psf/requests (Python, 37 funciones reales puntuadas, p. ej. resolve_proxies correctamente marcada con confianza 0.0 — genuinamente cero pruebas la referencian), kind-of (JS, ~50M de descargas semanales, isArray e isRegexp marcadas a pesar de que las 36 pruebas pasan), dustin/go-humanize (Go) y chronotope/humantime (Rust, un crate genuinamente multimódulo — confirma que la delimitación por mutación no se rompe en código real entre módulos, no solo en nuestro propio fixture). Ese proceso detectó y corrigió varios errores reales en tres de los cuatro — incluido uno donde una ejecución de mutación fallida se informaba silenciosamente como una puntuación de confianza falsa del 100%, y un error de escalado donde una solicitud limitada a un archivo mutaba silenciosamente un paquete real completo en su lugar. La verificación del repo real de Rust no reveló un nuevo error, consistente con que cargo-mutants -f es el mecanismo de delimitación más limpio y directamente compatible de los cuatro. Consulta docs/architecture.md para el relato completo.

Herramientas externas que envuelve (instala una vez, por lenguaje que uses)

• Python: mutmut — instalado automáticamente como dependencia de este proyecto.

• JS/TS: @stryker-mutator/core — obtenido automáticamente mediante npx en el primer uso.

• Go: gremlins — go install github.com/go-gremlins/gremlins/cmd/gremlins@latest

• Rust: cargo-mutants — cargo install cargo-mutants

Pruébalo

Aún no publicado en PyPI. Todos los comandos a continuación asumen un clon local de este repositorio, ejecutado desde dentro de él (uv run --directory <path> ... desde fuera, como en el ejemplo de integración con agentes más abajo). Una vez publicado, todo eso se reduce a un simple pip install test-trust / uvx test-trust, ejecutable desde cualquier lugar — sin clon, sin ruta que recordar, sin uv run --directory. Ese único cambio es el último paso entre «funciona, con configuración» y «realmente fácil de adoptar»; nada sobre cómo se comporta la herramienta cambia, solo cómo la obtienes.

Requiere Python 3.11+ y uv. Los motores de mutación por lenguaje (ver arriba) solo se necesitan para los lenguajes que realmente uses — el ejemplo de Python a continuación no necesita nada más allá de uv sync.

uv sync
uv run test-trust check examples/plug-and-play-fixture inventory.py

Sin archivo de configuración, sin ejecución manual de pruebas de mutación — este único comando detecta automáticamente el lenguaje, escribe la configuración automáticamente, ejecuta automáticamente las pruebas de mutación limitadas a ese archivo usando el comando de prueba real del repositorio, e imprime la puntuación de confianza.

Para ejecutar contra un archivo o repositorio diferente:

uv run test-trust check <path-to-repo> <source-file> [--changed-file F] [--base-ref REF] [--threshold T]

Cambiando el umbral (por defecto 0.5) — qué cuenta como adecuadamente probado. Súbelo (p. ej. 0.8) para marcar cualquier cosa por debajo de una cobertura de mutación casi total; bájalo para marcar solo las peores lagunas. El mismo parámetro, tres superficies:

• CLI: --threshold 0.8, como se muestra arriba.

• Herramienta MCP: threshold es un argumento de get_test_trust, p. ej. get_test_trust(repo_path=..., source_file=..., threshold=0.8). No lo llamas tú mismo — lo hace el agente — así que configurarlo significa decirle al agente (en tu prompt, o como instrucción permanente en CLAUDE.md: «llama a get_test_trust con threshold=0.8»). Si se deja sin configurar, usa 0.5.

• GitHub Action: la entrada low-trust-threshold en tu archivo de flujo de trabajo:

- uses: ./.github/actions/test-trust-pr
  with:
    github-token: ${{ secrets.GITHUB_TOKEN }}
    low-trust-threshold: "0.8"

Incorpóralo en un agente

Configuración única, registrada globalmente en lugar de por proyecto — dado que repo_path es un parámetro en cada llamada en lugar de fijarse al inicio, un registro sirve para todos los proyectos que abras después, no solo para el que se configuró. Para Claude Code, añade a ~/.claude.json (a nivel de usuario, no al .mcp.json de un proyecto):

{
  "mcpServers": {
    "test-trust": {
      "command": "uv",
      "args": ["run", "--directory", "/absolute/path/to/test-trust", "test-trust", "mcp"]
    }
  }
}

La misma forma de command/args funciona para Codex, Cursor o cualquier otro cliente MCP — consulta docs/embedding.md para esos y para lo que cambia una vez que esto se publique en PyPI (uvx test-trust mcp, sin necesidad de ruta local en absoluto).

Después de eso es invisible en el día a día: el agente llama a get_test_trust por sí mismo, a mitad de tarea, de la misma manera que ya llama a sus herramientas de lectura de archivos o bash — no lo llamas directamente.

O ejecútalo en cada PR, sin necesidad de agente

.github/actions/test-trust-pr puntúa cada archivo modificado y compatible en un PR y publica (o actualiza, en pushes posteriores) un comentario — marca cualquier función cuyas pruebas existentes no detectarían realmente una regresión allí. Útil para cualquier equipo que haga revisión de código, ya sea que alguien use un agente de IA o no. .github/workflows/test-trust.yml es el ejemplo funcional; verificado de extremo a extremo (detección de diff, puntuación, ambas representaciones de comentarios: «todo claro» y «marcado») contra commits reales en un repositorio real — solo la llamada en vivo a la API de GitHub en sí no está probada, ya que eso requiere un PR real para verificar.

Desarrollo

uv sync
uv run pytest tests/            # this project's own unit test suite
uv run test-trust check <repo> <file>   # exercise it against real code

tests/ cubre la lógica determinista (delimitación por diff, agregación de puntuación de confianza, auto-detección de lenguaje, adaptador de informe de cada motor de mutación) con fixtures elaborados — rápido, sin necesidad de herramientas externas de pruebas de mutación, y esta suite es la que realmente se ejecuta en CI (.github/workflows/ci.yml). No reemplaza la validación contra repos reales anterior — eso fue un ejercicio manual, de una sola vez, realizado durante el desarrollo (clones externos reales, motores reales instalados), no algo que CI re-ejecute en cada push. Vale la pena automatizarlo más adelante; aún no está hecho.

Licencia MIT.