beraki/my-code-factory-skills

Pruebas basadas en evidencia

Registra pruebas anotadas del comportamiento y luego adjúntalas al PR y al issue del gestor de tareas.

La grabación es la captura de ti probando la aplicación mediante el uso del ordenador: inicia el grabador, luego maneja la aplicación tú mismo — haz clic, escribe, navega — a través de cada objetivo de prueba. Cada acción en el vídeo es la prueba realizándose en vivo; la grabación no tiene valor como evidencia a menos que muestre esa sesión interactiva. Si el entorno no tiene herramientas de uso del ordenador pero existe una interfaz gráfica, maneja la aplicación con cua-driver en su lugar (ver más abajo) — sigue siendo tu sesión en vivo.

El grabador incluido, scripts/evidence.py, captura la pantalla con FFmpeg en Linux, macOS y Windows, marca la hora de cada anotación que agregas mientras pruebas, las incrusta en el vídeo al detenerse y verifica el resultado con ffprobe. Escribe evidence.mp4, report.md y manifest.json en la carpeta de la sesión.

Entradas

• Objetivos de prueba (obligatorio): Los comportamientos/flujos a verificar, expresados como afirmaciones comprobables.
• PR / issue (opcional): Dónde publicar la evidencia. Si se omite, entregar solo al solicitante.

El grabador

EVIDENCE a continuación significa la ruta a scripts/evidence.py dentro de la carpeta de esta habilidad (dondequiera que esté instalada, por ejemplo, ~/.claude/skills/evidence-driven-testing/scripts/evidence.py). Solo necesita Python 3 y FFmpeg.

• Verificar primero: python3 $EVIDENCE doctor — verifica ffmpeg, ffprobe, libx264 y el filtro ass (ready), luego qué fuente de captura de pantalla funciona en esta máquina (capture_ready y la fuente auto elegirá). Sale con código distinto de cero solo cuando falta la cadena de herramientas; lea capture_ready antes de grabar.

• Plataformas (--source auto elige la primera disponible):

  SO	Fuente	Necesita
  Linux X11 / XWayland	x11 (x11grab)	DISPLAY establecido
  Linux Wayland	wayland (wf-recorder)	WAYLAND_DISPLAY establecido, wf-recorder en PATH y un compositor confirmado que soporte wlr-screencopy — ya sea un conocido basado en wlroots (Sway, Hyprland, river, Wayfire, labwc, dwl, niri) o verificado mediante wayland-info. GNOME y KDE Wayland no se pueden capturar de esta manera; doctor lo indica. Use x11 a través de XWayland para aplicaciones X11, o un grabador alternativo. --source wayland aún lo fuerza
  macOS	avfoundation	Permiso de Grabación de Pantalla concedido al terminal / aplicación anfitriona del agente; doctor lista los índices de pantalla para --screen-index
  Windows	gdigrab	cualquier compilación estándar de ffmpeg; powershell para comprobaciones de procesos

  La captura es la pantalla completa por defecto; --geometry WxH y --offset X,Y recortan una región en x11, wayland y gdigrab. XWayland solo ve ventanas X11, por lo que se prefiere la fuente wayland cuando la aplicación bajo prueba es nativa de Wayland.

• Captura bruta a prueba de fallos: la grabación bruta es MPEG-TS (raw.ts), por lo que si el grabador se mata forzosamente o falla, lo capturado aún se puede sondear y renderizar. stop lo remuxifica o reconvierte en un evidence.mp4 estándar.

• Cómo funciona la detención: en Linux el grabador se señaliza a través de un pidfd. En macOS y Windows start lanza un pequeño proceso supervisor que posee el proceso hijo ffmpeg, y stop le pide (a través de stop.request en la carpeta de sesión) que interrumpa, luego termine y luego mate; escribe recorder-exit.json cuando termina. Nunca se señaliza un PID simple, por lo que no se puede alcanzar un PID reciclado. Si el supervisor muere mientras el grabador aún se está ejecutando, stop se niega y te dice qué PID detener manualmente. Si murió antes de poder registrar qué proceso inició, stop permanece bloqueado hasta que hayas verificado tú mismo un grabador perdido y lo vuelvas a ejecutar con --accept-untracked-recorder; el informe entonces lleva esa advertencia.

• Grabadores alternativos cuando doctor no informa ninguna fuente de captura (por ejemplo, Wayland sin wf-recorder): cua-driver recording start <dir> / stop (ver la sección cua-driver), o el grabador del SO (macOS: screencapture -v out.mov). En estas rutas no hay superposición de anotaciones, así que mantén el protocolo de anotaciones como archivos: un assertions.md que liste cada setup / test_start / assertion con su resultado y la marca de tiempo aproximada del vídeo, exactamente como en la ruta headless.

• Nunca presentes --source test (el generador de patrones sintéticos) como evidencia de interfaz de usuario. Existe para pruebas de humo de la cadena de herramientas; tests/test_evidence.py del repositorio lo ejercita.

Instrucciones

1. Preparar la pantalla

• Maximiza la ventana del navegador/aplicación; cierra ventanas emergentes, notificaciones y paneles adicionales.
• Navega al estado inicial (sesión iniciada, página correcta) ANTES de grabar, a menos que la configuración en sí misma esté bajo prueba.
• Anota la revisión exacta bajo prueba: git rev-parse HEAD y git branch --show-current (o la URL de despliegue) — el grabador las estampa en el informe.

2. Iniciar la grabación

• Inicia la grabación de pantalla antes de la primera acción significativa:

  python3 $EVIDENCE start \
    --output .artifacts/<task-name> \
    --title "<lo que se está verificando>" \
    --commit "$(git rev-parse HEAD)" --branch "$(git branch --show-current)" \
    --environment "<SO / navegador / pantalla / despliegue>"
  

  Imprime JSON con una ruta de session y la source elegida; guarda la ruta (SESSION=...) para cada comando posterior. La fuente se detecta automáticamente y se captura toda la pantalla; pasa --source, --geometry, --offset, --display/--xauthority (X11), --screen-index (macOS) o --output-name (Wayland) solo cuando doctor o la situación lo requiera.

• Añade una anotación setup describiendo el contexto inicial:

  python3 $EVIDENCE annotate "$SESSION" --type setup \
    --message "Sesión iniciada, navegando a la página de conectores"
  

3. Probar mediante uso del ordenador, anotando sobre la marcha

• Realiza cada interacción a través del uso del ordenador en la aplicación en vivo — la grabación captura tu sesión, por lo que la prueba y la evidencia son el mismo acto. Trabaja a un ritmo observable: deja que la interfaz de usuario se estabilice después de cada acción para que los cambios de estado sean visibles en el vídeo.

• Al inicio de cada prueba con nombre, añade una anotación test_start al estilo Jest:

  python3 $EVIDENCE annotate "$SESSION" --type test_start \
    --message "Debería ejecutar la herramienta directamente cuando el permiso es 'siempre'"
  

• Después de cada comprobación, añade una anotación assertion con --result passed, failed o untested:

  python3 $EVIDENCE annotate "$SESSION" --type assertion --result passed \
    --message "La herramienta se ejecutó sin un aviso de permiso"
  

• Reglas para las afirmaciones:

  • Una afirmación por cambio de estado significativo — consolida, no anotes por cada etiqueta de la interfaz.
  • Usa afirmaciones "Precondición: ..." para establecer el estado inicial.
  • Mantén menos de 80 caracteres, con alta señal (el grabador rechaza mensajes más largos).
  • Si una prueba no puede ejecutarse (falta un requisito previo, ventana de autenticación expirada), márcala como untested con el motivo — nunca la omitas en silencio.
  • La marca de tiempo registra cuándo afirmaste, no si era verdad — mira la pantalla antes de elegir passed.

4. Detener y revisar

• Detén la grabación después de la afirmación final:

  python3 $EVIDENCE stop "$SESSION"
  

  Esto detiene la captura (de forma ordenada, para que el grabador vacíe el búfer; solo escala si ignora la solicitud), incrusta las anotaciones en evidence.mp4, sondea el resultado y escribe report.md y manifest.json junto a él. Imprime "verified": true en caso de éxito; si el renderizado falla, la sesión se marca como finalization_failed — corrige la causa informada y ejecuta stop de nuevo (un reintento no señaliza el grabador dos veces). Si el proceso del grabador ya no se puede señalizar de forma segura (murió, o su PID ahora pertenece a otro proceso), la sesión se marca como recorder_lost. Ejecutar stop de nuevo finaliza el vídeo que se haya capturado, pero solo una vez que se confirma que ese proceso del grabador ha desaparecido — si aún está vivo, detenlo primero, o el vídeo se renderizaría mientras aún se está escribiendo.

• Confirma que la grabación capturó los momentos clave antes de compartir: extrae un fotograma en cada marca de tiempo de afirmación (ffmpeg -ss <t> -i evidence.mp4 -frames:v 1 frame.png) y verifica que el estado y la etiqueta sean visibles.

• Completa la sección de Advertencias de report.md; nunca dejes el marcador de posición.

5. Publicar la evidencia

• report.md es el informe: qué se probó, entorno + commit exacto, pasa/falla por prueba, advertencias. Amplíalo en lugar de reescribirlo desde cero.
• Publica el vídeo + resumen como un comentario en el PR (incrusta en la descripción del PR si es tu PR). gh pr comment no puede adjuntar un vídeo local — sube evidence.mp4 a través del cuadro de comentarios del PR en un navegador autenticado, o súbelo a un host y enlázalo (por ejemplo, los adaptadores de subida before-and-after). Vuelve a abrir el comentario y confirma que el vídeo se reproduce antes de afirmar que está publicado.
• Adjunta el mismo vídeo al issue del gestor de tareas (Linear/Jira) con un resumen de una línea.
• Envía el informe + grabación al solicitante.

Barreras de seguridad

• El vídeo debe mostrar la sesión de prueba real siendo manejada en vivo. Nunca presentes reproducción por script, clips unidos o material sintético como una grabación; si el entorno carece de herramientas de uso del ordenador pero existe una interfaz gráfica, maneja mediante cua-driver; sin interfaz gráfica en absoluto, usa la ruta headless en su lugar.
• Nunca grabes una ventana medio cubierta o en mosaico — maximízala primero.
• Nunca grabes una pantalla que muestre secretos, tokens, datos de clientes o detalles de pago; si un flujo los requiere, márcalo como untested y di por qué.
• Al verificar una corrección, muestra o referencia el fallo anterior junto con el nuevo éxito.
• Indica siempre el commit/rama/despliegue exacto contra el que se probó.

¿Sin herramientas de uso del ordenador? Maneja con cua-driver (interfaz gráfica disponible)

Cuando existe una pantalla pero el agente no tiene capacidad incorporada de uso del ordenador, usa cua-driver (macOS / Windows / Linux) como actuador. Sigues siendo tú probando la aplicación en vivo — la regla de grabación se mantiene sin cambios; solo difiere el mecanismo de entrada.

• Verifica la configuración con cua-driver doctor antes de grabar. Si hay una habilidad de cua-driver instalada, léela y sigue su protocolo — el invariante de captura de pantalla antes de la acción es obligatorio.
• Bucle por interacción: launch_app → get_window_state (árbol de accesibilidad + captura de pantalla) → actúa mediante element_token (click, type_text, press_key) → verify_state para la postcondición esperada. Cada comprobación verify_state se asigna 1:1 a una anotación assertion.
• Donde doctor informe capture_ready: yes, sigue usando el grabador incluido anteriormente para el vídeo y las anotaciones; cua-driver solo proporciona la entrada.
• De lo contrario, cua-driver recording start <output-dir> / cua-driver recording stop es el grabador (el directorio de salida es obligatorio y el demonio debe estar ejecutándose: cua-driver serve). La captura de vídeo está activada por defecto y se finaliza en <output-dir>/recording.mp4 al detenerse — pero en Windows/Linux se delega a ffmpeg, por lo que una falta de ffmpeg o de pantalla produce solo las carpetas de trayectoria por turno (capturas de antes/después, action.json, click.png), sin vídeo. Después de detener, verifica que recording.mp4 existe antes de citarlo; si está ausente, corrige el grabador o presenta las capturas de antes/después por turno como capturas numeradas según el protocolo headless.
• Si no hay superposición de anotaciones disponible en esta ruta, mantén el protocolo como archivos: un assertions.md que liste cada test_start / assertion con su resultado, exactamente como en la ruta headless.

Ruta headless (sin interfaz gráfica disponible)

Cuando el agente no tiene escritorio que grabar, mantén la misma disciplina de afirmaciones; cambia el grabador por captura por script:

• Guarda todo en .artifacts/<task-name>/ (inclúyelo en .gitignore — la evidencia se sube, nunca se confirma). Mantén el script de captura junto a las capturas para que la ejecución sea repetible.

• Capturas de pantalla: la CLI before-and-after (@vercel/before-and-after) captura URLs o elementos y sus pares alimentan directamente las inserciones en el PR. En contenedores/VMs donde Chrome falla con "No usable sandbox", establece AGENT_BROWSER_ARGS="--no-sandbox".

• Vídeo / flujos de varios pasos: un script de Playwright único, ejecutado sin añadir playwright a las dependencias del proyecto:

  npx --yes --package=playwright node record.mjs
  

  (El simple npx playwright node record.mjs falla — node no es un comando CLI de Playwright; --package=playwright es lo que pone el módulo en la ruta.) record.mjs mínimo:

  import { chromium } from "playwright";
  const browser = await chromium.launch();
  const context = await browser.newContext({
    recordVideo: { dir: ".artifacts/<task-name>/" },
  });
  const page = await context.newPage();
  await page.goto("http://localhost:3000/path-under-test");
  // ...maneja el flujo, un cambio de estado significativo por paso...
  await context.close(); // finaliza el .webm
  await browser.close();
  

  Recorta o comprime con ffmpeg si el archivo es grande.

• El protocolo de anotaciones se convierte en archivos: numera las capturas en orden de prueba con la afirmación en el nombre — 01-precondition-signed-in.png, 02-it-saves-on-blur-passed.png — y mantén un assertions.md en la carpeta de artefactos que liste cada test_start / assertion con su resultado (passed / failed / untested + motivo).

Los cambios sin interfaz de usuario también necesitan evidencia

• API / rendimiento: un sondeo por script con números medidos — recuentos de solicitudes por fase, latencia antes/después — capturado en probe-output.txt.
• Renderizado / canvas / shader: fotogramas renderizados más afirmaciones de píxeles (valores de diferencia), revisados visualmente y guardados como PNG.
• Comportamiento del agente: el extracto de la transcripción relevante que muestra la llamada a la herramienta y la respuesta.
• Correcciones de errores: reproduce y captura el fallo antes de escribir la corrección — esa captura es la mitad "antes" de un par antes/después.

Higiene de captura

• Confirma que el servidor que estás sondando está ejecutando tu código (puerto correcto, proceso correcto), especialmente cuando múltiples agentes comparten una máquina: lsof -i :<port> — o donde lsof no esté instalado, ss -ltnp "sport = :<port>".
• Tras detener, confirma que la grabación existe y se reproduce antes de adjuntarla.
• Guarda los artefactos de prueba junto a la grabación para que ejecutar stop de nuevo (por ejemplo, después de una corrección de herramientas) no elimine los resultados antiguos.
• Tras publicar en el PR, vuelve a abrir el comentario y confirma que la vista previa del vídeo se renderiza.

Flujo de trabajo para "reproducir y corregir"

1. Captura el fallo grabando la reproducción — detén, revisa, adjunta al issue como "before" y guarda los artefactos de la sesión antes de cambiar cualquier código.
2. Aplica la corrección.
3. Captura la verificación — detén, revisa, adjunta al mismo issue como "after" y al PR.
4. Añade un enlace cruzado a la evidencia "before" y "after" en una sola línea en el hilo del issue.

Índice de referencia rápida

Paso	Comando
Verificar cadena de herramientas	python3 $EVIDENCE doctor
Iniciar grabación	python3 $EVIDENCE start --output .artifacts/<name> --title "<...>" --commit ...
Anotar setup	python3 $EVIDENCE annotate "$SESSION" --type setup --message "..."
Anotar inicio de prueba	python3 $EVIDENCE annotate "$SESSION" --type test_start --message "It should..."
Anotar afirmación	python3 $EVIDENCE annotate "$SESSION" --type assertion --result passed --message "..."
Detener y finalizar	python3 $EVIDENCE stop "$SESSION"
Reintentar después de fallo de finalización	python3 $EVIDENCE stop "$SESSION" (no señaliza dos veces)