Pasos para reproducir un bug: cómo escribirlos, con un ejemplo

reportes de bugs

Los pasos para reproducir un bug son las acciones numeradas que llevan a otra persona desde un punto de partida conocido hasta el bug que viste. Unos buenos pasos dicen dónde empezaste (la página, la cuenta, qué había en el carrito), dan una acción por línea con los valores exactos que escribiste y terminan con lo que esperabas y lo que pasó en realidad.

El reporte tal como llega

Maya Thompson compra en Acme Store, la tienda de demostración que uso para las capturas de pantalla. Ella y la tienda son inventadas, y su bug es el mismo del artículo sobre Whisper. Aquí lo que importa son los pasos. Maya escribe FALL20 en el campo del descuento, el total se convierte en $NaN, y ella envía esto con el botón de reporte de bugs de la tienda:

Applied FALL20 and the total turned into "$NaN". Shipping still says Free and I can't continue to payment.

En español: «Apliqué FALL20 y el total pasó a ser “$NaN”. El envío sigue en Free y no puedo continuar al pago».

El reporte de Maya en BugDump: su descripción y la captura de pantalla que envió, con un recuadro alrededor del total $NaN

Para venir de un cliente, es un buen reporte. Dice el código, el síntoma y lo que bloquea. En la máquina de un desarrollador, donde la API de envíos responde, FALL20 da el total correcto.

El mismo bug escrito como pasos

Los pasos que un desarrollador puede seguir empiezan en un estado que puede recrear:

Plain Text
Inicio:      https://acme-store.com/cart, con sesión iniciada como el cliente cus_1042
Carrito:     2 × Enamel camp mug, 1 × Canvas market tote, 1 × Merino rib beanie
Envío a:     Portland, OR 97205

1. Haz clic en + junto a Canvas market tote. La cantidad pasa a 2.
2. Escribe FALL20 en Discount code.
3. Haz clic en Apply.

Esperado:    Discount −$23.20, total $92.80.
Real:        Discount −$23.20, total "$NaN". Shipping sigue en Free.
             Continue to payment no hace nada.

Navegador:   Chrome 141 en macOS, ventana de 1280 × 800
Frecuencia:  en cada intento

Qué aporta cada parte:

  • El estado inicial es algo que otra persona puede recrear. «Un carrito con algunos productos» no lo es.

  • Están todas las acciones, incluso la que parece no venir al caso. Maya cambió la cantidad de la bolsa antes de aplicar el código. Aquí no influyó, pero el desarrollador no podía saberlo sin probarlo.

  • Una acción por paso, que empieza por el verbo: haz clic, escribe, selecciona, desplázate.

  • Valores exactos, porque FALL20 y «un cupón» son entradas distintas. Un código descuenta el 20 %, otro descuenta $10, y puede que solo uno de ellos falle.

  • Las etiquetas tal como las muestra la página: Discount code, Apply, Continue to payment. El desarrollador busca esos textos en el código.

  • El resultado esperado como un número. Con «el total correcto», el desarrollador primero tiene que calcularlo, y $92.80 se comprueba de un vistazo.

  • Navegador, sistema operativo y tamaño de ventana, porque un bug de maquetación a 1280 píxeles puede no existir a 1440.

  • La frecuencia: siempre, uno de cada cinco intentos, una sola vez.

  • Cualquier cosa que viste por el camino: un mensaje de error, un indicador de carga que nunca se detuvo.

La condición previa que el cliente no podía ver

En una máquina donde la API de envíos responde, estos pasos dan $92.80.

Cuando Maya pulsó Apply, la tienda pidió a su API de envíos una tarifa nueva. La API respondió con un 503 al cabo de 1,2 segundos, con carrier_timeout en lugar de las tarifas, y la página sumó al total un importe de envío indefinido. Así que la primera línea de los pasos es una condición previa: el endpoint de tarifas de envío responde con un error, aquí un 503. Un cliente no puede escribir eso: la fila Shipping sigue en Free y nada en la página menciona la petición fallida.

Los pasos necesitan una línea de condición previa para el estado que quien reporta no controla: las respuestas del servidor, los feature flags, los datos de la cuenta.

BugDump registra los pasos mientras el cliente hace clic

En BugDump, el widget registra los pasos por su cuenta. Cada reporte que envía el widget lleva una lista Actions: clics, valores escritos, interruptores, opciones seleccionadas, formularios enviados y navegaciones entre páginas, en orden. Esta es la de Maya:

La pestaña Actions del reporte de Maya: un clic en un botón, un clic en el campo del cupón, «FALL20» escrito, un clic en el botón de enviar, el formulario del cupón enviado, un clic en el botón de realizar el pedido

Seis líneas coinciden con los pasos de arriba, incluido el clic en la bolsa que Maya nunca mencionó. Cómo funciona la lista:

  • Nombra elementos, no etiquetas. La primera línea, Clicked <button type="button">, es el + junto a la bolsa. La repetición de sesión del mismo reporte muestra qué botón era.

  • Oculta los campos sensibles. Los campos de contraseña, los campos cuyo autocomplete indica un número de tarjeta, una fecha de vencimiento, un código de seguridad o un código de un solo uso, y todo lo que esté dentro de data-bugdump-mask o .bugdump-block aparecen como Typed (hidden). Un campo de tarjeta sin ese autocomplete se registra como cualquier otro. Los demás valores escritos se cortan a los 80 caracteres.

  • Guarda las últimas 500 acciones, o 3000 mientras quien reporta graba la pantalla.

La condición previa está en el mismo reporte. La pestaña Network tiene el 503 de /api/shipping/rates, y la pestaña Console, la línea de error que la propia tienda registró sobre él. La tienda activó la captura de los cuerpos de petición y respuesta, así que la pestaña también muestra carrier_timeout. Los cuerpos vienen desactivados por defecto, y sin ellos la pestaña sigue mostrando el 503 y cuánto tardó.

Con eso, el desarrollador escribe la primera línea: el endpoint de tarifas responde 503. Un mock o una regla de proxy que lo devuelva hace que los pasos 1 a 3 den $NaN cada vez. Bloquear la petición no basta: una petición que no recibe respuesta deja el total en $92.80.

Preguntas habituales sobre los pasos para reproducir

¿Los pasos para reproducir son lo mismo que un reporte de bug? No, son una parte. Un reporte de bug también tiene un título y las pruebas: capturas de pantalla, consola, red.

¿Cuántos pasos debería haber? Los menos posibles que aún lleven del inicio al bug. Empieza en la página más cercana al bug que otra persona pueda abrir directamente: cada paso anterior es un paso más que puede salir de otra manera.

¿Y si no consigo reproducirlo? Anota lo que hiciste, di que pasó una vez y adjunta la consola y la red de ese momento.

Te puede interesar