Prueba manual (hand test)
Las pruebas demuestran lo que hace el código. Una prueba manual demuestra que una persona recibe lo que se pretendía. Para cada cambio que una persona pueda ver, oír o sentir, debes generar evidencia que un desconocido pueda juzgar en un minuto, en frío: un video y un tablero, ANTES (insignia roja) junto a DESPUÉS (insignia verde), el mismo lugar y la misma acción, de modo que solo el cambio difiera. El cambio permanece sin fusionar hasta que el revisor diga OK.
Los datos del proyecto viven en docs/agents/hand-test.md en el repositorio del usuario: cómo obtener el ANTES, cómo manejar y capturar esta superficie, las reglas del dispositivo, dónde va la evidencia, quién aprueba y qué hacen OK y No OK. Si ese archivo falta, sigue SETUP.md primero.
La herramienta es scripts/handtest.py. Ejecútala como uv run <carpeta de esta habilidad>/scripts/handtest.py <comando>; --help en cualquier comando lista sus banderas. Necesita ffmpeg y ffprobe en PATH; uv trae Pillow. Sin uv, crea un entorno virtual fuera del repositorio (python3 -m venv <dir> && <dir>/bin/pip install pillow) y ejecuta la herramienta con <dir>/bin/python.
1. Clasificar el cambio
Agrega una sección ## Prueba manual en el cuerpo del PR (o donde se describa el cambio):
sí: <qué buscar>para cualquier cosa que una persona vea, oiga o sienta: interfaz, comportamiento, sincronización, sonido, texto, diseño.no: <por qué no se ve, oye ni siente nada>para herramientas, compilación, pruebas, documentación o una refactorización con la misma salida.
Ante la duda, es sí.
Hecho cuando: la sección está. Un no termina la habilidad.
2. Planificar la toma
Nombra el momento: el único paso donde se muestra el cambio. Cuando el cambio está en pantalla desde el primer fotograma (un color, una etiqueta, un diseño), el momento es la llegada de la pantalla, o el primer paso después de ella.
Escribe los pasos como un guion que controle la aplicación real, idéntico para ambos lados (comandos por superficie en CAPTURE.md):
- Entrada real a través de la interfaz propia de la aplicación: un atajo de prueba omite el código que una persona ejecuta.
- Busca elementos por su etiqueta o rol, nunca por coordenadas: el diseño en movimiento suele ser el cambio mismo.
- Espera un estado real (una etiqueta mostrada, una solicitud completada) antes del momento, nunca un temporizador fijo. Mantén un tiempo fijo después.
- Mismo dispositivo, tamaño de ventana, idioma, datos y estado inicial en ambos lados.
- Restaura todo en un bloque
finally.
El ANTES proviene del estado real anterior: la compilación del commit base, o el cambio desactivado en tiempo de ejecución. Sin cambios en archivos guardados para ello.
Si el cambio es una cuestión de espacio, tiempo o sensación que nadie resolvió antes de la compilación (qué tan grande, qué tan rápido, cómo debería sentirse), detente e informa al usuario. Eso pertenece a un boceto interactivo antes de la compilación; una prueba manual verifica una decisión, no la toma.
Hecho cuando: el guion se ejecuta en seco (sin grabar nada) en ANTES y en DESPUÉS, encuentra todos los elementos (o alcanza todos los estados, donde solo se pueden tomar imágenes fijas), y deja el dispositivo y el árbol de trabajo como estaban, con la suma de verificación del árbol igual antes y después.
3. Grabar ambos lados
Graba ANTES, luego DESPUÉS, con el mismo guion. Respeta las reglas del dispositivo del proyecto: toca solo la aplicación bajo prueba, no desinstales nada, no cambies ninguna configuración del sistema, y envía entrada solo mientras la aplicación bajo prueba esté en primer plano.
Hecho cuando: existen dos grabaciones en bruto, cada una muestra el momento, y la suma de verificación del árbol de trabajo sigue coincidiendo.
4. Generar la evidencia
init --out "$HANDTEST_ROOT/<grupo>" --id <N> --topic <kebab-case> --title "<palabras simples>" --base <sha> --head <sha> --ok "<...>" --not-ok "<...>". El grupo, OK y No OK provienen del archivo del proyecto. Es posible que tu shell no conserveHANDTEST_ROOTentre comandos: establécelo en el mismo comando.find-change <raw> --from <s> --to <s>en cada grabación alrededor del momento. El tiempo de sincronización es el fotograma donde cambia la imagen, no el tiempo registrado de un paso.pair --before <raw> --after <raw> --sync-before <s> --sync-after <s> --title ... --what ... --caption ... --out <carpeta>/<id>_<topic>.mp4. Completa los tiempos del video en README.md y PACKAGE.md, e imprime dónde cae el momento en el video.- Una imagen fija por lado, un instante después del momento, de las grabaciones en bruto:
stills <raw> --at <s> --out <scratch>/before, lo mismo para DESPUÉS. Imprime cada archivo. Luegoboard --before <png> --after <png> --title ... --caption ... --out <carpeta>/<id>_<topic>_ANTES_DESPUES.png. - Completa cada marca
<rellenar: ...>. Las reglas para las palabras y los números están en EVIDENCE.md.
Hecho cuando: check <carpeta> imprime "listo para una persona".
5. Revisión del revisor
Antes de que ninguna persona lo vea, revísalo tú mismo como lo haría un desconocido. Extrae imágenes fijas del video dos veces: stills <video> --every 1 --out <scratch>, luego stills <video> --at <t-0.5> <t> <t+0.5> --out <scratch>, donde t es la hora del momento en el video, no en una grabación en bruto (pair lo imprimió; handtest.json lo contiene como video.change_at). Mira cada imagen fija y el tablero.
- Cada una debe mostrar lo que su pie de foto dice que se mire. Cubierto, vacío, estado incorrecto, idioma incorrecto, una superposición sobre el cambio:
archivela carpeta y graba de nuevo desde el paso 3. Graba de nuevo en lugar de explicar una mala imagen en el README. - Un número debe coincidir con la imagen. Cuando no coinciden, el número está mal: descubre por qué.
- Una prueba verde con una imagen incorrecta es un hallazgo. Repórtalo al usuario como un error.
Hecho cuando: cada imagen fija y el tablero muestran lo que afirman los pies de foto, y cada número en el README coincide con la imagen.
6. Entrega
Coloca la carpeta donde va la evidencia del proyecto. Publica PACKAGE.md donde dice el archivo del proyecto, nombrando solo la ruta relativa de la carpeta, nunca una cuenta o una ruta absoluta. Completa la línea sí del PR con esa ruta y con quién espera (el formulario está bajo "La sección del PR" en EVIDENCE.md). Pregunta al revisor. El cambio permanece sin fusionar (un PR en borrador donde hay PRs) mientras la prueba manual esté abierta.
Hecho cuando: el paquete está publicado, la línea del PR nombra la carpeta, se le ha preguntado al revisor y nada del cambio se ha fusionado.
7. Registrar el veredicto
El veredicto es del revisor. Nunca registres un OK que no haya dado.
- OK:
verdict <carpeta> --ok --by "<quien>"(rechaza una carpeta que fallacheck), luego haz lo que dice el archivo del proyecto que hace OK (generalmente: marcar el PR como listo). - No OK:
verdict <carpeta> --not-ok --by "<quien>" --note "<lo que dijeron>". Arrégralo en la misma rama,archivela carpeta y vuelve al paso 3. La rehacer crea los mismos nombres de archivo de nuevo; la toma anterior se mueve aprevious/. Cuandoinithaya escrito el nuevo README.md, copia las líneas que aún se mantienen deprevious/<marca>_README.md;pairreescribe los tiempos.
Hecho cuando: handtest.json contiene el veredicto de la persona y el rastreador coincide.
Un lanzamiento
Mantén cada carpeta de prueba manual bajo una carpeta de grupo por lanzamiento, luego ejecuta report <grupo> --title "<lanzamiento>". Escribe REPORT.md y un index.html autocontenido, con las pruebas manuales pendientes primero. Consulta EVIDENCE.md.