Cómo documentar un error con capturas paso a paso en Mac

Un informe de error es útil cuando otra persona puede reproducir el error a partir de él sin hacerte ninguna pregunta. Las capturas paso a paso eliminan la mayor parte de las suposiciones: quien desarrolla ve cada pantalla que viste, en orden.

Esta publicación explica qué necesita un informe reproducible y cómo capturar los pasos en un Mac con Action Capture de Temposhot.

Los ejemplos siguientes siguen un caso práctico de principio a fin. Una app web tiene una lista de proyectos, y al renombrar un proyecto la lista no se actualiza hasta que se recarga la página. El caso usa una cuenta de prueba, necesita 7 acciones para reproducirse y falla en 3 de 5 intentos.

Registra primero el entorno

Muchos errores aparecen solo en una versión, en un navegador o en un tipo de cuenta. Anota el entorno antes de reproducir el error, mientras todavía recuerdas la configuración.

Dato	Ejemplo
Versión de la app o del sitio	Número de compilación de la ventana Acerca de o del pie de página
Versión de macOS	Desde Acerca de este Mac
Modelo del Mac y chip	Desde Acerca de este Mac
Navegador y versión	En apps web, desde la página Acerca de del navegador
Tipo de cuenta o rol	Gratuita, de pago, administrador, lector
Idioma y región	Si el error afecta a textos, fechas o monedas
Fecha y hora	Con zona horaria, para poder cruzarla con los registros

Copia los valores como texto. Una captura de la ventana Acerca de es buena prueba, pero quien desarrolla no puede buscar dentro de una imagen.

Recoge los valores que cambian el resultado

No todos los datos importan en todos los errores. Los valores que merecen registrarse son los que podrían cambiar el resultado si fueran distintos. En el error de renombrado, importan la versión del navegador y el rol de la cuenta, porque la vista de lista se almacena en caché de forma distinta para lectores y editores.

Una prueba rápida muestra qué datos importan. Cambia un valor, como el navegador, y vuelve a intentarlo. Si el error desaparece, anótalo como hallazgo: "Se reproduce en el navegador de escritorio, no en la app móvil".

Pon el entorno en la primera página

Coloca el bloque del entorno al principio del informe, por encima de los pasos. Quien desarrolla revisa un gestor de incidencias leyendo el título y las primeras líneas antes de decidir si abre los adjuntos. Si el entorno queda enterrado en la página 6 de un PDF, quien desarrolla puede probar otro navegador e informar de "no se puede reproducir".

Adjunta registros y la salida de la consola como texto

En una app web, la consola del navegador suele mostrar un error en el momento del fallo. Copia las líneas del error como texto y pégalas debajo del bloque del entorno. Una captura de la consola es un extra útil, pero quien desarrolla necesita el texto para buscar el mensaje en el código.

Conserva solo las líneas cercanas al fallo. Un volcado de 400 líneas con un único error relevante obliga al lector a encontrarlo. Anota la hora del error para poder relacionarla con el registro del intento.

En una app de Mac, el equivalente es un informe de fallo o un cuadro de error. Copia el texto del cuadro con exactitud, incluido cualquier código de error, y captura el cuadro con el atajo manual durante la ejecución.

Indica el resultado esperado y el resultado real

Dos frases cortas enmarcan todo el informe:

• Esperado: "Tras seleccionar Save, el nuevo nombre aparece en la lista."
• Real: "Tras seleccionar Save, la lista sigue mostrando el nombre anterior. Al recargar la página aparece el nuevo nombre."

Describe lo que observas, no lo que crees que es la causa. "La lista no se actualiza" es una observación. "La caché está rota" es una suposición.

Escribe observaciones, no diagnósticos

Los diagnósticos en un informe de error dirigen a quien desarrolla al lugar equivocado. Si la causa real es un evento que no se disparó y no una caché, "la caché está rota" hace perder tiempo. Una observación es algo que cualquiera puede comprobar en pantalla.

Incluye el workaround como un hecho, no como un juicio de gravedad. El equipo que clasifica el informe decide la gravedad.

Reproduce desde un punto de partida conocido

Un informe que empieza con "abre la app" cuando ya estabas en mitad de una sesión oculta la configuración real. Empieza desde un estado al que cualquiera pueda llegar: un inicio de sesión nuevo, un proyecto nuevo, una URL concreta.

Reproduce el error al menos dos veces antes de grabar. Si aparece solo a veces, anota con qué frecuencia, por ejemplo "3 de 5 intentos".

Construye el estado inicial

En el error de renombrado, el estado inicial es una ventana del navegador con la sesión cerrada en la página de inicio de sesión. Cerrar la sesión primero borra la sesión anterior, así que quien desarrolla empieza desde el mismo punto que quien informa.

Registra cada intento

Los errores intermitentes necesitan un registro breve de intentos. Anota la hora de cada intento y si falló, para que quien desarrolla pueda cruzar los intentos con los registros del servidor. Cinco intentos suelen bastar para dar una frecuencia.

Reduce el recorrido al mínimo

El primer recorrido que muestra un error rara vez es el más corto. Antes de grabar, prueba a quitar una acción cada vez y comprueba si el error sigue apareciendo. En el ejemplo, abrir los detalles del proyecto antes de renombrarlo resultó innecesario, lo que redujo el recorrido de 9 acciones a 7.

Un recorrido más corto ayuda de dos maneras. Quien desarrolla dedica menos tiempo a cada reproducción, y menos acciones significan menos puntos en los que el lector puede tomar otro camino. Deja de reducir cuando quitar cualquier acción restante haga desaparecer el error.

Si el error no aparece durante la ejecución grabada, conserva la grabación de todos modos. Repite las últimas acciones y pulsa el atajo manual cuando aparezca el fallo. Una grabación de una ejecución correcta sigue siendo útil cuando muestra el recorrido exacto.

Captura una pantalla por cada acción necesaria

1. Abre Action Capture

   Pulsa Command+3 y selecciona Start Action Capture. Elige Specific Window para una sola app, o Active Window si los pasos cruzan apps.

2. Realiza los pasos

   Cada clic aceptado guarda la ventana justo antes del clic, así que cada página muestra el control antes de que actúes sobre él.

3. Captura el fallo

   Cuando aparezca el resultado incorrecto, pulsa Shift+Command+2 o selecciona Capture now en la barra flotante. La pantalla del fallo suele aparecer sin clic.

4. Termina la captura

   Selecciona Finish capture. El Document se abre en el editor con una página por paso.

Con Parse clicked elements activado, los títulos de página empiezan como Click "[[element-name]]". Activa Show cursor on click captures y Mark clicked area en Visual Annotations para que cada página muestre dónde hiciste clic. Si el error está en el propio Temposhot, activa Include toolbar in captures para que la barra flotante aparezca en los pasos.

Configura la ejecución una vez

Los ajustes de Configure Action Capture se guardan en el Mac y se reutilizan en ejecuciones posteriores. La configuración hecha para los informes de error se mantiene para el siguiente.

Elige Specific Window para un error dentro de una ventana del navegador. Un clic en otra ventana se ignora en ese caso, salvo que Capture outside clicks esté activado. Elige Active Window cuando la reproducción pase entre apps, por ejemplo de un enlace de correo a un navegador.

Ajusta la ejecución al límite de pasos

El plan gratuito tiene un límite de 5 pasos por ejecución de Action Capture. El error de renombrado necesita 7 acciones obligatorias más la pantalla del fallo, así que una ejecución gratuita se pausa después del quinto paso. Los pasos guardados hasta ese momento permanecen en la ejecución.

Hay dos formas de resolverlo. Divide la reproducción en dos ejecuciones en una pausa natural, por ejemplo después del inicio de sesión, y añade la segunda ejecución al mismo Document. O activa Temposhot Pro, que elimina el límite para que una sola ejecución cubra todos los pasos.

Usa el teclado durante la ejecución

Mantener las manos en el teclado durante una reproducción evita clics extra que se convierten en páginas sobrantes. Los atajos siguientes cubren la ejecución y la edición posterior.

Temposhot ignora los clics que siguen uno al otro demasiado de cerca. Un doble clic sobre un elemento de la lista produce un paso, no dos.

Cuando la ejecución pierde clics

Una ejecución que guarda menos pasos de los esperados tiene una lista corta de causas. Compruébalas en este orden antes de volver a grabar.

• La barra flotante muestra Paused. Selecciona Resume capture; los clics hechos en pausa no se guardan.
• El destino es Specific Window y el clic cayó en otra ventana. Haz clic dentro del destino, o activa Capture outside clicks.
• Mouse click capture está en un modo que exige u omite una tecla mantenida. Vuelve a Capture every mouse click para los informes de error.
• Falta Accessibility. Tanto Screen Recording como Accessibility deben mostrar Granted en Permissions Required.

Si todos los títulos analizados dicen Click here, la app de destino expone pocos datos de accesibilidad para sus controles. Los pasos se guardan igualmente; solo los títulos necesitan una reescritura manual.

Añade texto que explique los cambios de estado

Las capturas muestran pantallas. No siempre muestran qué cambió entre ellas. Usa la Page description para eso: "Aquí el contador debería mostrar 4. Muestra 3."

En la página del fallo, dibuja un Rectangle (R) alrededor del valor incorrecto y añade una etiqueta Text (T) con el valor esperado. Elimina las páginas de clics accidentales para que la secuencia contenga solo acciones obligatorias. Reescribe los títulos como pasos claros, por ejemplo "Selecciona Save". La guía del editor enumera todas las herramientas y atajos.

Limpia el ejemplo práctico

La ejecución grabada del renombrado produjo 9 páginas. Una procedía de un clic en una parte vacía de la lista, y otra de un clic en la barra de direcciones del navegador. Se eliminaron ambas, y se conservó la página de fallo del atajo manual, lo que dejó 7 páginas de acción más la página de fallo.

Los títulos analizados son un punto de partida. Click "Rename" se convierte en "Selecciona Rename en el menú del proyecto", que además indica al lector dónde está el control. Las páginas en las que el analizador no encontró ningún nombre muestran Click here y siempre necesitan reescribirse.

Patrones de descripción para los cambios de estado

Tres patrones breves cubren la mayoría de las descripciones de página de un informe de error. "Antes de este paso, la lista muestra 12 proyectos" registra un valor de partida. "Espera 2 segundos después de escribir" registra un tiempo que la captura no puede mostrar. "Aquí la lista debería mostrar Q3 Budget" registra el estado esperado en la página donde falla.

Limita cada descripción a una o dos frases. Las descripciones largas empujan la captura hacia abajo en el PDF, y con las descripciones definidas como Before image, el lector ve primero el texto.

Marca la página del fallo

La página del fallo contiene más información, así que recibe más anotaciones. Normalmente bastan un rectángulo alrededor del nombre antiguo y una etiqueta de texto con el nombre esperado. Más de 3 anotaciones en una misma página dificultan encontrar el valor incorrecto.

Usa Framing con un nivel como Close (nivel 4) en la página del fallo cuando la lista es pequeña en una ventana grande. La imagen original no cambia, y Show full image la restaura si quien desarrolla necesita el contexto completo.

Protege la información privada

Los informes de error se copian en gestores de incidencias, hilos de chat y tickets de proveedores. Trata cada captura como pública dentro de tu organización.

• Reproduce con una cuenta de prueba y datos de muestra siempre que sea posible.
• Recorta barras laterales, pestañas del navegador y notificaciones con Framing (F) y Custom.
• Difumina nombres, correos electrónicos, tokens e identificadores con Blur (B, Pro).
• Elimina los tokens de sesión y las claves de API de cualquier URL o texto de registro que pegues.

Revisa cada página al tamaño de exportación

Un desenfoque que oculta un valor en el lienzo al 50 por ciento de zoom puede ser legible a tamaño completo. Define Blur strength en el Object Inspector con un valor en el que el texto no se pueda leer; el valor predeterminado es 12 en una escala de 2 a 80. Después recorre la vista previa de exportación antes de enviar.

Las URL de la barra de direcciones del navegador son una fuga habitual. Un enlace para compartir o un token de restablecimiento en la barra es visible en cada página de una reproducción en el navegador, así que recorta la barra de direcciones con el encuadre o desenfócala en cada página.

Usa esta estructura de informe de error

1. Título: qué falla y dónde. "El elemento renombrado no se actualiza en la vista de lista."
2. Entorno: los valores de la tabla de arriba.
3. Pasos para reproducir: numerados, desde un estado conocido.
4. Resultado esperado y Resultado real.
5. Frecuencia: siempre, o con qué frecuencia.
6. Pruebas: la guía de capturas exportada, más los registros o errores de la consola como texto.
7. Workaround: si existe.

Exporta desde el Document con Export PDF para un solo adjunto, o con More export formats para páginas PNG que los gestores muestran en línea. Los nombres de los archivos de imagen siguen los títulos de página. La guía de exportación enumera todos los formatos.

Elige la exportación según el gestor de incidencias

Los gestores de incidencias difieren en cómo muestran los adjuntos. Las páginas PNG en línea funcionan cuando el gestor previsualiza imágenes en el cuerpo de la incidencia, porque quien desarrolla lee los pasos sin abrir ningún archivo. Un PDF único funciona cuando el gestor solo lista adjuntos, o cuando el informe va a un proveedor externo.

El formato paquete ZIP contiene en un solo archivo las páginas PNG renderizadas y un archivo document.json. Encaja con un ticket de proveedor que acepta un solo archivo y necesita tanto las imágenes como el texto de las páginas.

Un ejemplo completado

El informe del renombrado se lee así en el gestor de incidencias. El título es "El proyecto renombrado conserva el nombre antiguo en la lista de proyectos hasta recargar". El bloque del entorno enumera el número de compilación, la versión de macOS, la versión del navegador, el rol editor y las horas de los intentos, de 14:02 a 14:20.

Los pasos son 7 líneas numeradas, desde "Inicia sesión como qa-editor" hasta "Cierra el cuadro de renombrado". Esperado y real son las dos frases de antes, y la frecuencia es "3 de 5 intentos". La prueba es un PDF de 8 páginas, y el workaround es "Recarga la página".

El PDF usa los ajustes de exportación predeterminados: A4, horizontal, portada activada, números de paso activados, números de página activados y descripciones antes de la imagen. Personalizar esos ajustes requiere Temposhot Pro; los valores predeterminados ya se ajustan a un informe de error.

Escribe también los pasos como texto

Pega los pasos numerados como texto en el cuerpo de la incidencia, aunque el PDF ya los incluya. Los pasos en texto se pueden buscar, citar en comentarios y copiar a un caso de prueba. Las capturas sirven entonces como prueba de cada paso, no como único registro de este.

Prueba el informe antes de enviarlo

Lee el informe desde el principio como si nunca hubieras visto el error. Mejor aún, pide a una compañera que lo siga en su Mac. Si reproduce el error sin hacer ninguna pregunta, el informe está listo.

Huecos habituales que aparecen en una prueba en seco

Una prueba en seco hecha por una compañera suele encontrar uno de tres huecos. Falta el estado inicial, por ejemplo un proyecto que debe existir antes. Un paso ocurre sin clic, como un atajo de teclado, y no tiene página. O el fallo depende del tiempo, por ejemplo seleccionar Save menos de 2 segundos después de escribir.

Añade el estado que falta al primer paso, añade una página para la acción del teclado con el atajo manual, e indica el tiempo en la descripción de la página. Después repite la prueba en seco.

Conserva el Document de origen

El Document sigue siendo editable después de exportar. Si quien desarrolla pide una pantalla más, abre el Document, añade la página con Capture new images… y vuelve a exportar. Los archivos ya exportados no se actualizan por sí solos.

Preguntas frecuentes

¿Un informe de error debe incluir vídeo o capturas?

Las capturas funcionan para la mayoría de los errores y son fáciles de revisar y anotar. El vídeo ayuda en problemas de tiempos y animaciones. Consulta guía paso a paso con capturas frente a grabación de pantalla.

¿Cuántas capturas necesita un informe de error?

Una por cada acción obligatoria más la pantalla del fallo. Elimina las páginas que no cambian el resultado.

¿Dónde quedan las capturas después de enviar el informe?

El Document permanece en tu Mac. Temposhot no tiene enlace alojado, así que adjunta los archivos exportados al gestor de incidencias o al ticket.

¿Qué pasa si el error necesita más de 5 pasos en el plan gratuito?

La ejecución se pausa en el límite de pasos y conserva los pasos guardados hasta ese momento. Divide la reproducción en dos ejecuciones y añade ambas a un mismo Document, o usa Temposhot Pro para grabar más allá del límite.

¿Puedo capturar un error que aparece sin ningún clic?

Sí. Pulsa el atajo de captura manual, Shift+Command+2 por defecto, cuando aparezca el estado incorrecto. El paso se guarda sin clic y recibe el ajuste de marca de clic si está configurado.

Convierte tus clics en una guía paso a paso clara

Action Capture registra los pasos de la reproducción mientras los realizas, con marcas de clic y títulos de borrador. Descarga Temposhot y adjunta tu próximo informe de error como una guía ordenada.