Skip to content

Proyecto: {{PROJECT_NAME}} · Clase SaMD: {{SAMD_CLASS}} · Versión: vX.Y · Fecha: YYYY-MM-DD

Guía maestra del stack de testing

Esta guía es la fuente única sobre qué herramienta verifica qué, cuándo corre y con qué comando en {{PROJECT_NAME}}. El uso previsto del producto es: {{INTENDED_USE}}. La clase SaMD {{SAMD_CLASS}} (IEC 62304 §5.7) exige verificación demostrable: un test que solo "renderiza sin crashear" no es verificación — exigimos aserciones sobre valores, llamadas y efectos secundarios.

Stacks de referencia:

  • Frontend: {{FRONTEND_STACK}}
  • Backend: {{BACKEND_STACK}}
  • Datos: {{DB_STACK}}
  • Nube / CI: {{CLOUD_STACK}}

Idioma de trabajo del equipo: {{CHAT_LANG}}.


1. Tabla del stack

Herramienta Qué verifica Cuándo corre Comando
Unit — frontend (Vitest) Lógica de componentes/hooks/servicios con aserciones específicas (no humo). En cada cambio de frontend; gate de PR. npm test
Unit — backend (pytest) Routers, services, reglas de negocio, fail-safe; async en asyncio_mode = auto. En cada cambio de backend; gate de PR. pytest -ra
Coverage — backend (coverage.py) Cobertura de líneas/ramas; gate ≥95% global (+ piso por capa datos/SQL). Reproducible, en paralelo. Gate de PR backend (ci.yml). bash scripts/check_coverage.sh
Mutation — frontend (Stryker) Que los tests maten mutantes (no solo cubran líneas); gate break ~90. Objetivo: incremental varias veces por semana + full periódico. De fábrica corre a mano: .github/workflows/nightly-mutation.yml trae los crones comentados (solo workflow_dispatch); descomentalos cuando tu suite esté estable. Nunca en paralelo con agentes que escriben tests. npx stryker run
Mutation — backend (mutmut 2.5.1, fijado) Igual que Stryker, en Python; el gate lee el cache de mutmut y falla bajo el umbral (env var). Objetivo: semanal incremental. De fábrica es manual y local: el kit NO trae workflow de CI que lo ejecute; si querés que sea periódico, agregá un job que corra el script (y guardá el resultado de cada corrida como evidencia). bash scripts/run_mutmut.sh
DB tier (pytest @ Postgres + pgvector) Comportamiento real del motor (asyncpg, pgvector, defaults SQL) que SQLite oculta. Al tocar app/models/migraciones; cron 3×/sem; workflow_dispatch. bash scripts/run_pytest_postgres.sh (o .github/workflows/db-tier.yml)
SAST (analizador estático de seguridad) Vulnerabilidades en código Python+TS, secretos hardcodeados, patrones inseguros. Nightly; gate de PR sobre archivos tocados. bash scripts/run_semgrep.sh
DAST (escáner dinámico, OWASP ZAP) Superficie HTTP en runtime: headers, auth, inyección, exposición. Nightly contra entorno efímero. bash scripts/run_zap_dast.sh
Fuzz de API (schemathesis contra OpenAPI) Que cada endpoint respete su contrato OpenAPI bajo entradas adversariales. Al cambiar el esquema/API; nightly. bash scripts/run_schemathesis.sh
SCA / deps (escáner de CVEs) CVEs en dependencias y capas de imagen Docker. Nightly; gate de PR sobre lockfiles. bash scripts/run_trivy.sh
E2E (navegador headless) Flujos críticos de usuario de punta a punta en un navegador real. Pre-release; nightly. <comando e2e>
Flaky check (este kit) Tests cuyo resultado verde↔rojo cambia entre corridas sin tocar código. Cuando se sospecha inestabilidad; antes de cerrar una suite. FLAKY_RUNS=10 TEST_CMD="pytest -q" scripts/run_flaky_check.sh

Rellená cada <comando ...> con el comando real del proyecto cuando conectes la herramienta. Los placeholders <...> marcan lo pendiente.


2. Reglas duras

Estas reglas no son negociables; son consecuencia directa de IEC 62304 §5.7.

  1. Mutation nunca en paralelo con agentes/tareas que escriben tests. La herramienta de mutación congela la lista de tests en su dry-run; los tests nuevos creados en paralelo no entran y el score miente. Patrón correcto: primero los tests nuevos → suite unit verde → entonces mutación.
  2. Verificá la suite COMPLETA antes de cantar verde. Un archivo de producción puede tener *.test y *.mutation.test (u otras) por separado; correr solo uno deja regresiones invisibles. Mocks globales con closure local se filtran entre tests: aislá el estado (afterEach robusto) y confirmá la corrida entera.
  3. Cobertura siempre reproducible. No midas cobertura secuencialmente sobre una suite async+threaded: el tracer y el cambio de contexto (greenlet+thread) corrompen el data file y reportan misses fantasma. Corré en paralelo (-n auto), un data file por worker, luego coverage combine. Detalle en .coveragerc y pytest.ini.
  4. Tests rigurosos, no de humo. Cada test asegura valores, llamadas y efectos concretos. "No crashea" no cuenta como verificación SaMD.
  5. Procesos pesados piden OK explícito (mutación full, fuzz, DAST, suites completas, SCA de imagen): consumen mucho CPU; no se disparan implícitos.
  6. Umbrales como gate, no como adorno. Mutación frontend break ~90 (frontend/stryker.conf.json); mutación backend vía scripts/check_mutmut_score.py (umbral por env var, default 80); cobertura backend ≥95%. Si un módulo baja del umbral, se interviene antes de cerrar.
  7. La mutación backend va con la versión de mutmut FIJADA (2.5.1) y un gate que se prueba a sí mismo. mutmut 3 eliminó --paths-to-mutate y --runner y cambió el formato del cache: con mutmut sin pin, un pip install nuevo rompe run_mutmut.sh sin aviso. Tres decisiones que no son obvias y están ancladas por tests/test_mutmut_gate.py:
  8. El gate cuenta los mutantes del cache SQLite (.mutmut-cache), porque mutmut results solo lista los que NO murieron: un gate que parsea esa salida nunca ve los matados y no puede dar verde.
  9. run_mutmut.sh corre con --CI: sin esa flag el exit de mutmut es un campo de bits (2 = "hubo supervivientes") que el script tomaría por error fatal; con ella solo un error real de mutmut sale distinto de 0, y se propaga (sin || true: un mutmut que muere al arrancar no es «0 mutantes», es «0 miradas»).
  10. scripts/mutmut_pytest_runner.py convierte cualquier salida de pytest distinta de 0 en «mutante muerto»: por defecto mutmut solo mata con exit 1, y un mutante que rompe la importación (exit 4) o deja la lista vacía (exit 5) contaba como superviviente, inflando el ruido. Para subir de versión hay que migrar los dos scripts; la regla ignore de .github/dependabot.yml evita que Dependabot lo haga solo.
  11. Las acciones de CI van pineadas a SHA, y un test lo vigila (tests/test_workflows_pineados_a_sha.py): una regla en prosa que nada comprueba se erosiona sin ruido (ver .claude/rules/github-actions.md).

3. Archivos del paquete de testing en este kit

  • frontend/stryker.conf.json — config de mutación frontend.
  • scripts/check_coverage.sh — cobertura canónica con doble piso (global + capa datos/SQL).
  • scripts/run_mutmut.sh + scripts/check_mutmut_score.py + scripts/mutmut_pytest_runner.py — mutación backend (mutmut 2.5.1) + gate de score (lee .mutmut-cache) + runner que convierte todo exit ≠ 0 en mutante muerto. Anclados por tests/test_mutmut_gate.py.
  • tests/test_workflows_pineados_a_sha.py — guardián: toda acción de .github/workflows/ pineada a SHA de 40 hex, una sola versión por acción.
  • scripts/run_pytest_postgres.sh — suite contra Postgres real (self-contained, docker).
  • scripts/run_zap_dast.sh — DAST (OWASP ZAP) contra la app corriendo.
  • scripts/check_translations.py — auditor i18n (paridad de claves + "copiado sin traducir"). Fail-closed: si no encuentra locales en ninguna de las rutas I18N_* sale con rc=1 (no declara "sincronizado" sin haber mirado). Tests: tests/test_scripts_check_translations.py.
  • scripts/run_flaky_check.sh — cazador de tests inestables.
  • scripts/run_act.sh — corre los workflows de Actions localmente (nektos/act).
  • pytest.ini — config de pytest + nota de cobertura reproducible.
  • .coveragerc — config de cobertura en paralelo (greenlet+thread).
  • .github/workflows/db-tier.yml — suite contra Postgres real + pgvector.

Navegación: Índice del DHF · Master Map