vercel-labs/dogfood

¿Qué hace dogfood?

Explora sistemáticamente una aplicación web, encuentra problemas y genera un informe con evidencia de reproducción completa para cada hallazgo.

Configuración

Sólo se requiere la URL de destino. Todo lo demás tiene valores predeterminados razonables: úsalos a menos que el usuario proporcione explícitamente una anulación.

Parámetro	Valor predeterminado	Anulación de ejemplo
URL de destino	(obligatorio)	vercel.com, http://localhost:3000
Nombre de sesión	Dominio slugificado (ej. vercel.com -> vercel-com)	--session mi-sesion
Directorio de salida	./dogfood-output/	Directorio de salida: /tmp/qa
Alcance	Aplicación completa	Enfócate en la página de facturación
Autenticación	Ninguna	Inicia sesión con [email protected]

Si el usuario dice algo como "dogfood vercel.com", comienza inmediatamente con los valores predeterminados. No hagas preguntas aclaratorias a menos que se mencione autenticación pero falten las credenciales.

Usa siempre agent-browser directamente — nunca npx agent-browser. El binario directo usa el cliente Rust rápido. npx pasa por Node.js y es significativamente más lento.

Flujo de trabajo

1. Inicializar    Configurar sesión, directorios de salida, archivo de informe
2. Autenticar     Iniciar sesión si es necesario, guardar estado
3. Orientar       Navegar al punto de inicio, tomar instantánea inicial
4. Explorar       Visitar páginas y probar funciones sistemáticamente
5. Documentar     Capturar pantalla + grabar cada problema a medida que se encuentra
6. Finalizar      Actualizar resumen de recuentos, cerrar sesión

1. Inicializar

mkdir -p {OUTPUT_DIR}/screenshots {OUTPUT_DIR}/videos

Copia la plantilla del informe en el directorio de salida y completa los campos del encabezado:

cp {SKILL_DIR}/templates/dogfood-report-template.md {OUTPUT_DIR}/report.md

Inicia una sesión con nombre:

agent-browser --session {SESSION} open {TARGET_URL}
agent-browser --session {SESSION} wait --load domcontentloaded

2. Autenticar

Si la aplicación requiere inicio de sesión:

agent-browser --session {SESSION} snapshot -i
# Identifica las referencias del formulario de inicio de sesión, completa las credenciales
agent-browser --session {SESSION} fill @e1 "{EMAIL}"
agent-browser --session {SESSION} fill @e2 "{PASSWORD}"
agent-browser --session {SESSION} click @e3
# Reemplaza con la URL, texto o condición JS posterior al inicio de sesión de la aplicación objetivo:
agent-browser --session {SESSION} wait --url "{POST_LOGIN_URL_PATTERN}"
# O:
# agent-browser --session {SESSION} wait --text "{POST_LOGIN_TEXT}"
# agent-browser --session {SESSION} wait --fn "{POST_LOGIN_CONDITION}"

Para códigos OTP/de correo electrónico: pregunta al usuario, espera su respuesta, luego ingresa el código.

Después de un inicio de sesión exitoso, guarda el estado para posible reutilización:

agent-browser --session {SESSION} state save {OUTPUT_DIR}/auth-state.json

3. Orientar

Toma una captura de pantalla anotada inicial y una instantánea para entender la estructura de la aplicación:

agent-browser --session {SESSION} screenshot --annotate {OUTPUT_DIR}/screenshots/initial.png
agent-browser --session {SESSION} snapshot -i

Identifica los elementos de navegación principales y mapea las secciones a visitar.

4. Explorar

Lee references/issue-taxonomy.md para obtener la lista completa de qué buscar y la lista de verificación de exploración.

Estrategia: trabaja a través de la aplicación sistemáticamente:

• Comienza desde la navegación principal. Visita cada sección de nivel superior.
• Dentro de cada sección, prueba elementos interactivos: haz clic en botones, completa formularios, abre menús desplegables/modales.
• Verifica casos extremos: estados vacíos, manejo de errores, entradas en límites.
• Prueba flujos de trabajo realistas de extremo a extremo (crear, editar, eliminar).
• Revisa la consola del navegador periódicamente para detectar errores.

En cada página:

agent-browser --session {SESSION} snapshot -i
agent-browser --session {SESSION} screenshot --annotate {OUTPUT_DIR}/screenshots/{page-name}.png
agent-browser --session {SESSION} errors
agent-browser --session {SESSION} console

Usa tu criterio sobre qué tan profundo ir. Dedica más tiempo a las funciones principales y menos a las páginas periféricas. Si encuentras un grupo de problemas en un área, investiga más a fondo.

5. Documentar problemas (priorizando la reproducción)

Los pasos 4 y 5 ocurren juntos: explora y documenta en una sola pasada. Cuando encuentres un problema, detén la exploración y documéntalo inmediatamente antes de continuar. No explores toda la aplicación primero y documentes después.

Cada problema debe ser reproducible. Cuando encuentres algo incorrecto, no solo lo anotes, demuéstralo con evidencia. El objetivo es que alguien que lea el informe pueda ver exactamente lo que sucedió y reproducirlo.

Elige el nivel de evidencia adecuado para el problema:

Problemas interactivos / de comportamiento (funcionales, UX, errores de consola al actuar)

Estos requieren interacción del usuario para reproducirse: utiliza reproducción completa con video y capturas de pantalla paso a paso:

1. Inicia un video de reproducción antes de reproducir:

agent-browser --session {SESSION} record start {OUTPUT_DIR}/videos/issue-{NNN}-repro.webm

2. Recorre los pasos a ritmo humano. Pausa de 1 a 2 segundos entre acciones para que el video sea visualizable. Toma una captura de pantalla en cada paso:

agent-browser --session {SESSION} screenshot {OUTPUT_DIR}/screenshots/issue-{NNN}-step-1.png
sleep 1
# Realiza la acción (clic, rellenar, etc.)
sleep 1
agent-browser --session {SESSION} screenshot {OUTPUT_DIR}/screenshots/issue-{NNN}-step-2.png
sleep 1
# ...continúa hasta que el problema se manifieste

3. Captura el estado roto. Pausa para que el espectador pueda verlo, luego toma una captura de pantalla anotada:

sleep 2
agent-browser --session {SESSION} screenshot --annotate {OUTPUT_DIR}/screenshots/issue-{NNN}-result.png

4. Detén el video:

agent-browser --session {SESSION} record stop

5. Escribe los pasos de reproducción numerados en el informe, cada uno haciendo referencia a su captura de pantalla.

Problemas estáticos / visibles al cargar (errores tipográficos, texto de marcador de posición, texto recortado, desalineación, errores de consola al cargar)

Estos son visibles sin interacción: una sola captura de pantalla anotada es suficiente. Sin video, sin reproducción de varios pasos:

agent-browser --session {SESSION} screenshot --annotate {OUTPUT_DIR}/screenshots/issue-{NNN}.png

Escribe una breve descripción y referencia la captura de pantalla en el informe. Establece Video de reproducción como N/A.

---

Para todos los problemas:

1. Agrega al informe inmediatamente. No acumules problemas para después. Escribe cada uno a medida que lo encuentres para que no se pierda nada si la sesión se interrumpe.

2. Incrementa el contador de problemas (ISSUE-001, ISSUE-002, ...).

6. Finalizar

Apunta a encontrar de 5 a 10 problemas bien documentados, luego finaliza. La profundidad de la evidencia es más importante que el recuento total: 5 problemas con reproducción completa son mejores que 20 con descripciones vagas.

Después de explorar:

1. Vuelve a leer el informe y actualiza los recuentos resumidos de gravedad para que coincidan con los problemas reales. Cada bloque ### ISSUE- debe reflejarse en los totales.
2. Cierra la sesión:

agent-browser --session {SESSION} close

3. Informa al usuario que el informe está listo y resume los hallazgos: número total de problemas, desglose por gravedad y los elementos más críticos.

Orientación

• La reproducción lo es todo. Cada problema necesita una prueba, pero adecúa la evidencia al problema. Los errores interactivos necesitan video y capturas de pantalla paso a paso. Los errores estáticos (errores tipográficos, texto de marcador de posición, fallos visuales visibles al cargar) solo necesitan una única captura de pantalla anotada.
• Verifica la reproducibilidad antes de recopilar evidencia. Antes de grabar un video o tomar capturas de pantalla, verifica que el problema sea reproducible con al menos un reintento. Si no se puede reproducir de manera consistente, no es un problema válido.
• No grabes video para problemas estáticos. Un error tipográfico o texto recortado no se beneficia de un video. Reserva el video para problemas que involucren interacción del usuario, tiempos o cambios de estado.
• Para problemas interactivos, captura cada paso. Toma la captura del antes, la acción y el después, para que alguien pueda ver la secuencia completa.
• Escribe pasos de reproducción que se correspondan con las capturas de pantalla. Cada paso numerado en el informe debe hacer referencia a su captura de pantalla correspondiente. Un lector debería poder seguir los pasos visualmente sin tocar un navegador.
• Usa el comando de instantánea correcto.
  • snapshot -i — para encontrar elementos cliqueables/rellenables (botones, entradas, enlaces)
  • snapshot (sin bandera) — para leer el contenido de la página (texto, encabezados, listas de datos)
• Sé minucioso pero usa el criterio. No estás siguiendo un script de prueba; estás explorando como lo haría un usuario real. Si algo parece extraño, investiga.
• Escribe los hallazgos de forma incremental. Agrega cada problema al informe a medida que lo descubres. Si la sesión se interrumpe, los hallazgos se conservan. Nunca acumules todos los problemas para el final.
• Nunca elimines archivos de salida. No rm capturas de pantalla, videos o el informe a mitad de sesión. No cierres la sesión y reinicies. Trabaja hacia adelante, no hacia atrás.
• Nunca leas el código fuente de la aplicación de destino. Estás probando como usuario, no auditando código. No leas archivos HTML, JS o de configuración de la aplicación bajo prueba. Todos los hallazgos deben provenir de lo que observas en el navegador.
• Revisa la consola. Muchos problemas son invisibles en la interfaz de usuario pero aparecen como errores de JS o solicitudes fallidas.
• Prueba como un usuario, no como un robot. Prueba flujos de trabajo comunes de principio a fin. Haz clic en cosas en las que un usuario real haría clic. Ingresa datos realistas.
• Escribe como un humano. Al completar campos de formulario durante la grabación de video, usa type en lugar de fill; escribe carácter por carácter. Usa fill solo fuera de la grabación de video cuando la velocidad sea importante.
• Pon ritmo a los videos de reproducción para humanos. Agrega sleep 1 entre acciones y sleep 2 antes de la captura de pantalla del resultado final. Los videos deben ser visualizables a velocidad 1x; un humano que revisa el informe necesita ver lo que sucedió, no un borrón de cambios de estado instantáneos.
• Sé eficiente con los comandos. Agrupa varios comandos de agent-browser en una sola llamada de shell cuando sean independientes (ej., agent-browser ... screenshot ... && agent-browser ... console). Usa agent-browser --session {SESSION} scroll down 300 para desplazarte; no uses key ni evaluate para desplazarte.

Referencias

Referencia	Cuándo leerla
references/issue-taxonomy.md	Al inicio de la sesión — calibra qué buscar, niveles de gravedad, lista de verificación de exploración

Plantillas

Plantilla	Propósito
templates/dogfood-report-template.md	Copiar en el directorio de salida como archivo de informe