Un buen reporte de bug se corrige. Uno malo recibe la etiqueta «no se puede reproducir», una petición de más información que quien lo envió nunca contesta y una muerte lenta al fondo del backlog. La diferencia rara vez está en el esfuerzo: está en saber qué necesita de verdad quien va a corregir el bug.
Esta guía describe la estructura de un reporte que sobrevive al triaje, tanto si lo escribes tú como si enseñas a usuarios y compañeros a escribirlos mejor.
Anatomía de un reporte útil
Un título que describe el fallo, no lo que sientes
«El checkout está roto» no le dice nada a un desarrollador. «Checkout: al hacer clic en Pagar después de aplicar un código de descuento, el spinner gira sin parar» le dice dónde mirar, qué probar y le da una pista de qué lo dispara. Un buen título indica el lugar, la acción y el resultado observado.
Pasos para reproducirlo
Escribe la secuencia más corta que dispara el bug, empezando desde un estado conocido:
Inicia sesión como cliente con un producto en el carrito
Aplica el código de descuento SAVE10
Haz clic en Pagar
Los pasos numerados importan porque quien corrige el bug los va a seguir al pie de la letra. Si el paso 2 es imprescindible y lo omites, el bug se reproduce en tu máquina y no en la suya, y ahí se atasca todo.
Comportamiento esperado y comportamiento real
Dos líneas cortas: qué debería haber pasado y qué pasó en su lugar. Suena burocrático hasta que te topas con un bug en el que quien lo reporta y quien lo corrige no coinciden en qué es lo «correcto». «Esperado: página de confirmación del pedido. Real: spinner infinito, ninguna actividad de red después del clic» elimina la ambigüedad.
El entorno
Navegador y versión, sistema operativo, dispositivo, tamaño de pantalla y la URL exacta de la página. Una cantidad enorme de bugs de front-end depende del entorno: un problema al parsear fechas que solo ocurre en Safari, un layout que solo se rompe con el ancho de una tablet. Sin datos del entorno, el desarrollador prueba en su propio navegador, no ve nada y cierra el reporte.
La evidencia
Esto es lo que separa un reporte que se diagnostica en cinco minutos de uno que lleva un día entero:
Salida de la consola: el mensaje de error real y el stack trace, no una paráfrasis.
Actividad de red: qué petición falló y con qué código de estado.
Una captura de pantalla o una grabación: sobre todo en bugs visuales y de layout, donde mil palabras valen de verdad menos que una imagen.
El momento: cuándo pasó, para poder cruzarlo con los logs del servidor y los despliegues.
Por qué los usuarios no van a hacer nada de esto
Aquí viene la parte incómoda: es razonable exigirle este checklist a un ingeniero de QA y absurdo exigírselo a un usuario. Los usuarios no saben qué es una consola, no van a buscar la versión de su navegador y no escribirán pasos para reproducir el bug. Lo mejor que te darán, con toda su buena fe, es «no funciona», y cada campo que añades al formulario de bugs te hace perder más reportes.
Tienes dos opciones. Aceptar reportes vagos y pagar el precio en el triaje. O recoger automáticamente la mitad técnica del reporte y dejar que el usuario aporte lo único que solo él tiene: qué intentaba hacer.
Sobre este modelo se construyen los widgets de reporte de bugs. Con una herramienta como BugDump, el usuario hace clic en un botón y escribe una frase; el widget adjunta por su cuenta los logs de consola, las peticiones de red, la repetición de sesión, los datos del entorno y la URL de la página. El usuario escribe «hice clic en pagar y no pasó nada», y con eso basta, porque la excepción no capturada y la petición fallida están ahí mismo, en el reporte.
El checklist
Para reportes que una persona escribe de principio a fin (QA interno, reportes de compañeros, issues de GitHub):
El título indica lugar + acción + resultado observado
Pasos numerados para reproducirlo, desde un estado inicial conocido
Comportamiento esperado, en una línea
Comportamiento real, en una línea
Entorno: navegador + versión, sistema operativo, dispositivo, viewport, URL
Errores de consola, copiados tal cual
Petición de red fallida y su código de estado, si la hay
Captura de pantalla o grabación para todo lo visual
Gravedad e impacto: ¿a quién le pasa y con qué frecuencia?
En los reportes que llegan de usuarios, el checklist cambia de forma: la mayoría de las casillas las tiene que marcar la herramienta, no las personas:
Descripción con las palabras del propio usuario (el único campo obligatorio)
Todo lo demás (entorno, consola, red, repetición de sesión) se captura automáticamente
La identidad de quien reporta se adjunta automáticamente si el usuario tiene la sesión iniciada, para poder hacer seguimiento
Un reporte, un bug
No caigas en la tentación de agrupar. «El panel está lento, además el botón de exportar no funciona y el modo oscuro se ve mal» son tres bugs con el ID de un solo reporte. Un reporte agrupado no se puede priorizar (cada bug tiene su gravedad), no se puede cerrar (al corregir uno quedan dos tercios abiertos) y no se puede asignar limpiamente. Crea tres reportes. Si tu tracker organiza los reportes en tareas (BugDump convierte los reportes en tarjetas de un tablero kanban), la disciplina se nota de inmediato, porque cada tarjeta avanza por su cuenta.
La gravedad, sin exagerar
Marca la gravedad por el impacto, no por la frustración. Una errata que a ti te da vergüenza es de gravedad baja; un fallo en el pago que afecta a un solo navegador es de gravedad alta, aunque no puedas reproducirlo. Si los reportes siempre se marcan como «crítico», el equipo aprende a ignorar ese campo por completo, y eso es peor que no tenerlo.
Lo que se gana
Los buenos reportes de bug se acumulan a tu favor. Cada uno que trae evidencia real se corrige antes; eso mantiene corto el backlog, el triaje sigue siendo rápido y queda más tiempo para los reportes que de verdad son difíciles. Y el hábito se contagia: los desarrolladores que reciben buenos reportes empiezan a escribirlos.
Escribe el reporte que te gustaría recibir un viernes a las cinco de la tarde, y automatiza todo lo que quien reporta no debería tener que saber aportar.
Te puede interesar
Plantilla de reporte de bug que sí funciona (y cómo automatizarla) — una plantilla que vale la pena conservar y por qué puedes borrar tres cuartas partes de ella.
Qué hacer con un reporte de bug que no puedes reproducir — las causas habituales de un bug que no se reproduce y el contexto que las resuelve.
Anatomía de un reporte de bug: qué captura BugDump y por qué — cada dato que recoge el widget de BugDump y cuáles resuelven bugs de verdad.