Imported from Wtyd/githooks (.claude/skills/qa-tester/SKILL.md). Install upstream with npx skills add Wtyd/githooks --skill qa-tester. Copyright stays with the author.

QA Testing funcional de GitHooks

Guía para hacer testing funcional exhaustivo del CLI de GitHooks.

Principios de testing

1. Probar como un QA tester hostil: no verificar que los ficheros existen, EJECUTAR los comandos y comprobar el resultado real.

2. Probar edge cases: inputs vacíos, tipos incorrectos, valores límite, combinaciones imposibles.

3. Probar en entorno real: usar /var/www/html3 como proyecto de prueba — es un proyecto Composer real con tools instaladas, ficheros con errores a propósito y configs variadas.

4. No asumir que funciona: si el Changelog dice que una feature existe, PROBARLA.

5. El CWD importa: la auto-detección de executablePath busca vendor/bin/ relativo al directorio actual. Ejecutar desde /var/www/html3 (tiene vendor/bin/) vs otro directorio da resultados diferentes.

6. Leer la implementación antes de crear configs de test: ante cualquier output inesperado (warnings, errores), buscar en src/ el mensaje exacto con Grep para entender de dónde viene antes de catalogar como BUG.

7. Medir el exit code SIN pipe. Después de un pipe, $? es el exit code del último comando del pipeline (head, tail, python3…), no del binario que pruebas. Eso ha provocado falsos positivos masivos en sesiones reales (todo un bloque de 18 "BUGs" de exit 0 que en realidad eran exit 1). Patrón correcto:

   # CORRECTO — exit limpio
   php7.4 vendor/bin/githooks conf:check --config=X.php > /dev/null 2>&1
   echo "EXIT: $?"
   
   # INCORRECTO — $? viene de head, siempre 0
   php7.4 vendor/bin/githooks conf:check --config=X.php 2>&1 | head -20; echo "EXIT=$?"

   Si necesitas ver el output y el exit code en el mismo bloque, vuelca el output a fichero antes:

   php7.4 vendor/bin/githooks conf:check --config=X.php > /tmp/qa-out 2>&1
   echo "EXIT: $?"
   head -20 /tmp/qa-out

   Variantes válidas en zsh para preservar exit del primer comando del pipeline: ${pipestatus[1]}. En bash: ${PIPESTATUS[0]}.

   Antes de catalogar un caso como "exit 0 cuando se esperaba 1", repite la medición sin pipe. Una herramienta verificadora externa lo descubrirá en segundos y desmontará el reporte.

Pre-flight: allowlist de permisos

La skill cruza la barrera entre html1 (proyecto raíz) y html3 (proyecto de prueba). Sin un allowlist específico, cada Read/Write en html3 y cada rm -rf reports/v33-* dispara un prompt de permiso que rompe el ritmo del testing.

Antes de empezar, comprobar que /var/www/html1/.claude/settings.local.json (el del proyecto activo cuando se invoca la skill) incluye estos permisos. Si falta alguno, añadirlo:

"Read(//var/www/html3/**)",
"Edit(//var/www/html3/**)",
"Write(//var/www/html3/**)",
"Write(//tmp/v33-*)",
"Write(//tmp/qa-*)",
"Bash(rm -rf reports/v33-*)",
"Bash(rm -rf /tmp/v33-*)",
"Bash(md5sum:*)",
"Bash(seq:*)",
"Bash(cd /var/www/html3*)"

Read(//var/www/html3/**) evita 3-5 prompts por sesión leyendo configs y TESTS-vX.Y.md. Write(//tmp/v33-*) cubre los configs inline de tests "(editar inline)" sin tener que checked-in cada uno. Bash(rm -rf reports/v33-*) y Bash(rm -rf /tmp/v33-*) cubren la limpieza entre bloques.

Paso 0: Preguntar al usuario

Antes de empezar, preguntar:

1. Versión a probar: 2.x o 3.x (ej: 3.0.0)
2. Versión de PHP: 7.4, 8.0, 8.1, 8.2, 8.3, 8.4, 8.5...
3. Build: ¿Usar la build actual o construir una nueva?

Con estos datos se determina:

Gestión de la build

Los binarios se encuentran en:

• builds/githooks — para PHP 8.1+
• builds/php7.4/githooks — para PHP 7.4, 8.0

Verificar si la build existe y está actualizada:

ls -la builds/githooks builds/php7.4/githooks   # ¿existen?
git log --oneline -1 -- builds/                  # ¿cuándo se buildeó?
git log --oneline -1                             # ¿último commit del código?

Si la build no existe o está desactualizada respecto al código, preguntar al usuario:

Los builds están desactualizados (código más reciente que la build). ¿Quieres que construya una build nueva antes de probar?

Si el usuario quiere build nueva, construir con la versión de PHP del tier correspondiente:

Importante: el build elimina las dev dependencies de html1. Tras el build, restaurarlas:

git checkout -- composer.json && php{X.Y} tools/composer update

Si el usuario quiere usar la build actual, verificar que los binarios existen. Si no existen, avisar y preguntar de nuevo.

Paso 1: Preparar el entorno de pruebas

cd /var/www/html3

# 1. Checkout rama correcta
git checkout {master|2.x}
git checkout -b {version}-prueba    # ej: 3.0.0-prueba

# 2. Preparar composer.json desde el example
cp composer.example.json composer.json

Editar composer.json

Reemplazar la versión de githooks:

# Cambiar "*" por la versión RC
php{X.Y} -r '
$json = json_decode(file_get_contents("composer.json"), true);
$json["require-dev"]["wtyd/githooks"] = "dev-rc-{versión}";
file_put_contents("composer.json", json_encode($json, JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES) . "\n");
'

Si PHP < 8.1, añadir el evento post-update-cmd para instalar el binario correcto:

php{X.Y} -r '
$json = json_decode(file_get_contents("composer.json"), true);
$json["scripts"] = [
    "post-update-cmd" => ["Wtyd\\GitHooks\\Utils\\ComposerUpdater::phpOldVersions"]
];
file_put_contents("composer.json", json_encode($json, JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES) . "\n");
'

Recordatorio — Cuándo es necesario post-update-cmd:

Sin el post-update-cmd en PHP <8.1, vendor/bin/githooks apuntará al build de 8.1+ que no es compatible.

Instalar dependencias

php{X.Y} composer.phar update

Esto instala GitHooks desde Packagist (rama RC) con el binario correcto en vendor/bin/githooks.

Verificar instalación

php{X.Y} vendor/bin/githooks --version

Debe mostrar la versión correspondiente sin errores PHP.

Paso 2: Ejecutar los tests

Consultar TESTS.md en la rama actual de html3. Contiene el catálogo completo de tests con comandos exactos, salidas esperadas, exit codes y SHAs de commit para cada test.

Patrón de ejecución

Todos los tests se ejecutan DESDE /var/www/html3:

cd /var/www/html3
php{X.Y} vendor/bin/githooks <comando> [--config=<config>]

Sin --config, busca githooks.php en el CWD.

Ir al commit correcto (si el test lo indica)

Algunos tests requieren un SHA específico. Antes de ejecutar:

git checkout <SHA>

Tras el test, volver a la rama de prueba:

git checkout {version}-prueba

Entorno de pruebas: /var/www/html3

Estructura

/var/www/html3/
├── composer.example.json   # Template — copiar a composer.json y editar
├── composer.phar           # Composer standalone (no depende del sistema)
├── src/
│   ├── CleanFile.php       # Código limpio — pasa todas las tools
│   ├── FileWithErrors.php  # Variable no usada, propiedad undefined — falla phpstan, phpmd
│   ├── SyntaxError.php     # Syntax error PHP — falla parallel-lint
│   ├── DuplicateA.php      # Código duplicado con DuplicateB — falla phpcpd
│   └── DuplicateB.php      # (mismo código que DuplicateA)
├── tests/
│   ├── PassingTest.php     # assertTrue(true) — pasa phpunit
│   └── FailingTest.php     # assertTrue(false) — falla phpunit
├── phpunit.xml             # Config PHPUnit (testsuite "default" → tests/)
├── psalm.xml               # Config Psalm (errorLevel 8, src/)
├── TESTS.md                # Catálogo completo de tests con SHAs
└── [configs por rama]      # githooks.php, githooks-v3.php, etc.

Tools disponibles vs no disponibles

Errores esperados por fichero

Configs de test adicionales

Cuando necesites una config v3 o una config rota que no exista ya, créalas en /var/www/html3/ con nombre descriptivo.

IMPORTANTE: antes de crear una config, leer la implementación en src/ para entender el formato exacto. Las condiciones de ejecución condicional (only-on, exclude-on, only-files, exclude-files) van en la sección hooks como parte del HookRef, NO en options del flow. Ejemplo:

'hooks' => [
    'pre-commit' => [
        ['flow' => 'qa', 'only-on' => ['main', 'release/*']],
        ['job' => 'audit', 'only-files' => ['src/**/*.php']],
    ],
],

Áreas de testing

1. Comandos básicos — Happy path

2. Edge cases de configuración

Crear ficheros PHP en /var/www/html3/ con la config de prueba.

3. Formatos de salida

4. Flags especiales

5. Combinaciones de flags

Los bugs más interesantes salen de combinar flags. Probar explícitamente:

6. Comando cache:clear

7. Validación profunda en conf:check

8. Auto-detección de executablePath

9. Tools no instaladas

El proyecto html3 no tiene phpunit ni psalm instalados. Verificar que el comportamiento es correcto:

10. Hooks

Teardown hooks: git config --unset core.hooksPath; rm -rf .githooks/

11. Ejecución condicional (solo hooks)

Las condiciones van en la sección hooks como parte del HookRef. Se prueban via hook:run <evento>.

12. Features v3.2 sin cobertura en release tests

Estas features están en el changelog de [3.2.0] pero no tienen test @group release. Probarlas a mano tras cada build nuevo del .phar hasta que se añadan al pipeline:

Cada item vale para los dos tiers (builds/php7.4/ y builds/). Priorizar los 1-4 (nuevos de gh-49-cores + flags de output más utilizados); 5-9 son útiles pero preexistentes.

13. Migración y compatibilidad legacy

Paso 3: Limpiar

cd /var/www/html3

# 1. Deshacer hooks de git
git config --unset core.hooksPath 2>/dev/null
rm -rf .githooks/ 2>/dev/null

# 2. Limpiar staged + working tree (por si algún test dejó restos)
git restore --staged . 2>/dev/null
git checkout -- . 2>/dev/null
git clean -fd 2>/dev/null

# 3. Volver a la rama base y borrar la de prueba
git checkout {master|2.x}
git branch -D {version}-prueba

# 4. Verificar que html3 queda completamente limpio
git status

El paso 4 es obligatorio. No generar el reporte hasta confirmar que git status muestra working tree limpio (sin staged, sin modificados, sin untracked). Si queda algo sucio, limpiarlo antes de continuar.

Protección: nunca borrar master ni 2.x.

Teardown durante los tests

Cuando un test modifica ficheros (ej: echo >> file && git add file para probar only-files), el teardown inmediato tras ese test debe deshacer tanto el stage como el working tree:

git restore --staged <file> && git checkout -- <file>

git checkout -- <file> solo deshace cambios en working tree, no limpia el staging area. Si hiciste git add, necesitas git restore --staged primero.

Formato de reporte

Al terminar, generar una tabla resumen. Usar la columna Resultado para distinguir entre estados:

Valores de Resultado:

• OK: funciona como se espera
• BUG: no funciona, pendiente de corregir
• BUG CORREGIDO: encontrado y corregido durante el testing
• SKIP: no se pudo probar (falta dependencia, entorno, etc.)

Severidades (solo para BUG/BUG CORREGIDO):

• Critica: crashea, pierde datos, rompe la ejecución normal
• Alta: funcionalidad documentada que no funciona
• Media: edge case mal manejado pero con workaround
• Baja: cosmético, mensaje confuso, comportamiento no ideal