Communitygithub.com

hand-test

Prueba manual de un cambio que las personas ven, oyen o sienten. ANTES y DESPUÉS se reproducen lado a lado en un video y un tablero, el agente los verifica, y el cambio espera la aprobación de una persona. Úsalo cuando el usuario solicite una prueba manual, un video antes/después, evidencia visual para un PR, un informe de versión de lo que cambió para los usuarios, o diga 'muéstrame lo que cambió'.

¿Qué es hand-test?

Hand test es una habilidad para agentes de IA (como Claude Code, Cursor o Codex) que automatiza la verificación visual y funcional de cambios en software que afectan la experiencia del usuario (lo que se ve, oye o siente). En lugar de solo pruebas unitarias, esta habilidad genera evidencia reproducible: un video sincronizado lado a lado (ANTES vs. DESPUÉS) y un tablero con imágenes fijas, que permiten a un revisor humano aprobar o rechazar el cambio de manera informada. La habilidad sigue un flujo de 7 pasos: clasificar el cambio, planificar la grabación (con un script que controla la interfaz real), grabar ambos estados, generar el video y tablero con marcas de tiempo precisas, realizar una auto-revisión, entregar el paquete al revisor y registrar el veredicto. Se ejecuta mediante un script Python (`scripts/handtest.py`) que requiere ffmpeg y ffprobe, y utiliza Pillow para el procesamiento de imágenes. Hand test es especialmente útil para pull requests que modifican interfaces de usuario, comportamientos visuales, animaciones, sonidos o cualquier elemento perceptible. El agente se encarga de toda la orquestación, guiando al usuario solo cuando se requiere una decisión humana (por ejemplo, aprobar un cambio estético no definido previamente). El resultado es un conjunto de archivos autocontenido (video, tablero, README) que puede incluirse en informes de versión o PRs.

Compatible con~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/GhostRoboticsLab/skills/tree/HEAD/skills/engineering/hand-test

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

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

  1. 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 conserve HANDTEST_ROOT entre comandos: establécelo en el mismo comando.
  2. 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.
  3. 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.
  4. 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. Luego board --before <png> --after <png> --title ... --caption ... --out <carpeta>/<id>_<topic>_ANTES_DESPUES.png.
  5. 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: archive la 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 falla check), 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, archive la carpeta y vuelve al paso 3. La rehacer crea los mismos nombres de archivo de nuevo; la toma anterior se mueve a previous/. Cuando init haya escrito el nuevo README.md, copia las líneas que aún se mantienen de previous/<marca>_README.md; pair reescribe 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.

Individual skills in this repo

This repo contains 1 individual skill — each has its own dedicated page.

Skills relacionados