Cómo escribir un reporte de bug útil para desarrolladores
Cómo escribir un reporte de bug que se corrija: un título concreto, pasos exactos para reproducir, resultado esperado y real, entorno y pruebas.
Para escribir un reporte de bug con el que un desarrollador pueda trabajar, primero reproduce el problema y después escribe un título concreto de una línea, el entorno (URL, navegador y versión, sistema operativo, cuenta), pasos numerados para reproducirlo desde un punto de partida conocido, el resultado esperado y el resultado real con los mensajes de error exactos, y adjunta pruebas como una captura o una grabación, los errores de consola y la petición de red que falla. Un bug por reporte.
La prueba de un buen reporte es sencilla: ¿podría un desarrollador que nunca ha visto el problema provocarlo en su propia máquina sin preguntarte nada? Si la respuesta es sí, probablemente el bug se corregirá rápido. Si tiene que volver con preguntas, cada ida y vuelta cuesta un día. Si quieres los campos en forma de checklist, copia nuestra plantilla de reporte de bugs.
1. Reprodúcelo antes de escribir
Intenta que el bug vuelva a ocurrir. Mientras lo haces, fíjate en los detalles que podrían importar:
- Qué cuenta o qué rol estabas usando.
- Qué datos intervenían: un producto concreto, un nombre largo, una lista vacía, un archivo grande.
- Qué pasos son realmente necesarios. Quita pasos de uno en uno para encontrar el camino más corto.
- Si ocurre en otro navegador o en una ventana privada.
Si ocurre siempre, perfecto. Si solo ocurre a veces, cuéntalo: «4 de cada 10 intentos». Si no consigues reproducirlo, repórtalo igualmente y dilo con claridad.
2. Comprueba si ya está reportado
Busca en el gestor de incidencias el mensaje de error, el nombre de la página y algunas palabras clave. Si encuentras una coincidencia, añade allí tus datos en lugar de abrir un ticket nuevo: tu entorno, una nueva forma de provocarlo o el hecho de que sigue ocurriendo en el último build. Los duplicados reparten la información entre varios tickets y hacen perder tiempo en el triaje.
3. Escribe un título concreto
El título suele ser lo único que se lee durante el triaje. Haz que describa el problema, no la función.
| Título flojo | Título mejor |
|---|---|
| Login roto | Iniciar sesión con Google vuelve a la página de login en Safari |
| Bug en informes | A la exportación CSV del informe de Ventas le faltan las filas a partir de la 1.000 |
| La página va lenta | La página de facturación tarda más de 10 segundos en cargar en cuentas con muchas facturas |
| Error al guardar | Guardar un perfil con un emoji en el nombre devuelve «Invalid input» |
Un patrón útil: qué está roto, más cuándo ocurre, más dónde.
4. Describe el entorno
Muchos bugs solo aparecen en una configuración concreta. Incluye:
- URL de la página donde ocurrió.
- Navegador y versión, por ejemplo Chrome, Firefox, Safari o Edge con el número de versión de la página «Acerca de».
- Sistema operativo y dispositivo.
- Tamaño de pantalla, si es un problema de maquetación.
- Versión o build de la app, si la app lo muestra.
- Cuenta, rol o usuario de prueba, y cualquier particularidad (una cuenta de prueba gratuita, una organización grande, un idioma distinto del inglés).
- Hora en que ocurrió, con la zona horaria, para que el equipo pueda encontrarlo en los logs del servidor.
5. Escribe los pasos para reproducir
Los pasos son el núcleo del reporte. Unos buenos pasos:
- Empiezan desde un estado conocido: «Con sesión iniciada como administrador, en el Dashboard».
- Tienen una acción por cada paso numerado.
- Nombran los datos exactos: el producto, el archivo, el texto que escribiste. Nunca incluyas contraseñas ni números de tarjeta reales; usa datos de prueba.
- Usan las etiquetas que muestra la app, en negrita o entre comillas, para que el desarrollador encuentre el mismo botón.
- Terminan en el momento en que aparece el bug.
1. Inicia sesión como [email protected] (rol Administrador).
2. Ve a Ajustes y después a Equipo.
3. Haz clic en «Invitar miembro».
4. Escribe «[email protected]» y elige el rol «Lector».
5. Haz clic en «Enviar invitación».
6. Escribe el resultado esperado y el real
Ponlos uno junto al otro:
Esperado: La invitación aparece en la lista Pendientes y se muestra un aviso de confirmación.
Real: El diálogo se cierra, no se muestra ningún aviso y la lista Pendientes sigue vacía.
Tras recargar, la invitación sigue sin aparecer.
Describe lo que observaste, no lo que crees que lo causó. «La petición de invitación falló» es una conclusión; «el diálogo se cerró y no apareció nada en la lista» es una observación. Si viste un mensaje de error, cópialo como texto, tal cual. Los desarrolladores buscan esa cadena en su código.
7. Añade pruebas
Las pruebas convierten una descripción en una evidencia y a menudo apuntan directamente a la causa.
- Captura de pantalla con la zona del problema resaltada. Recorta los datos personales que no vengan al caso.
- Grabación de pantalla para todo lo que implique movimiento, tiempos o varios pasos. Que sea corta y que empiece justo antes del problema.
- Errores de consola. En las aplicaciones web, un error en rojo en la consola del navegador suele ser la pista más útil. Consulta cómo exportar los logs de consola en Chrome.
- La petición de red que falla. La URL, el código de estado y el cuerpo de la respuesta de la llamada a la API que falló. Consulta cómo capturar el tráfico de red en Chrome.
- Un archivo HAR, si el equipo pide la sesión de red completa. Sigue cómo obtener un archivo HAR y límpialo antes con el sanitizador de HAR, porque los archivos HAR incluyen cookies y tokens.
8. Valora el impacto con honestidad
Di lo grave que es y a cuántas personas afecta. Usa la escala de severidad de tu equipo si la hay. Sé honesto: si todo se marca como crítico, nada lo es. Menciona una alternativa si la encontraste; cambia lo urgente que es la corrección y ayuda a soporte mientras tanto.
9. Limítate a un bug
Si encontraste tres problemas en la misma página, escribe tres reportes. Así cada uno se puede asignar, corregir, probar y cerrar por separado. Vincúlalos si parecen relacionados.
10. Sigue disponible
Después de enviarlo, estate pendiente del ticket por si hay preguntas. Cuando salga la corrección, vuelve a probar con los mismos pasos y confírmalo. Si el bug reaparece más adelante, reabre el ticket original o enlázalo, para que el historial quede en un solo sitio.
Errores habituales
- Títulos vagos como «no funciona» o «problema con la página».
- Faltan pasos, o los pasos empiezan a mitad de un flujo.
- Capturas de los mensajes de error en lugar del texto, que no se pueden buscar.
- Varios bugs en un mismo ticket.
- Secretos reales en el reporte: contraseñas, claves de API, cookies de sesión o datos de clientes en capturas y logs.
- Lenguaje emocional. Un reporte tranquilo y basado en hechos se corrige antes que uno enfadado.
Para ver reportes buenos y malos lado a lado, consulta nuestros ejemplos de reportes de bugs.
Escribe menos, captura más
La mayor parte del esfuerzo de un reporte de bug se va en los detalles técnicos, que además son lo que más se olvida. Midge, una extensión de Chrome gratuita, graba tu pantalla o hace una captura y adjunta esos detalles por ti, así que solo escribes el título, los pasos y lo que esperabas. Cada grabación incluye logs de consola, peticiones de red, acciones del usuario y datos del dispositivo. Las contraseñas, números de tarjeta, tokens y cookies se ocultan en tu navegador antes de que nada salga de tu dispositivo. El reporte se comparte como un único enlace que puedes pegar en el gestor de incidencias que use tu equipo.
Guías relacionadas
- Plantilla de reporte de bugs
- Ejemplos de reportes de bugs
- Cómo reportar un bug (para personas sin perfil técnico)
Preguntas frecuentes
¿Cuáles son las partes más importantes de un reporte de bug?
Los pasos para reproducir, el resultado esperado y el resultado real. Con esas tres, un desarrollador normalmente puede ver el problema por sí mismo. Los datos del entorno y las pruebas, como capturas y errores de consola, lo hacen más rápido.
¿Qué extensión debería tener un reporte de bug?
Lo más corto posible sin dejar de estar completo. La mayoría de los buenos reportes caben en una pantalla: un título de una línea, un resumen breve, de cinco a diez pasos, los resultados esperado y real, y los adjuntos.
¿Y si no consigo reproducir el bug?
Repórtalo igualmente y dilo. Describe exactamente qué estabas haciendo, cuándo ocurrió, y adjunta las pruebas que tengas, como una captura o un error de consola. Marca la frecuencia como «ocurrió una vez».
¿Debo incluir mi opinión sobre la causa?
Separa las observaciones de las suposiciones. Escribe lo que viste en los campos principales y, si tienes una teoría, añádela en una sección de notas indicando que es una suposición.