Modo guía
Disponible desde la 0.2.4
Recorre un flujo de cualquier aplicación web con un agente y Astral escribe la guía de usuario por ti.
Qué obtienes
Una guía escrita a partir de una ejecución grabada, en la carpeta de la ejecución junto a report.html:
guide.mdyguide.html(una página autocontenida): un título, una introducción, una sección numerada por paso y una instrucción numerada por cada acción.- Una captura por acción, tomada antes de un clic, con el objetivo marcado.
- Una sección final de Resultado con una captura de cierre.
- Un enlace a la grabación: un MP4 en macOS, un PNG animado en el resto.
- Solo nombres de archivo relativos, así que la carpeta se puede mover o comprimir tal cual.
Pídeselo a tu agente
Cualquier agente MCP conectado a Astral puede hacerlo. Pídeselo, por ejemplo: «escribe una guía de usuario para crear un cliente, en español». Detrás está el prompt MCP write-guide, que tu agente lista junto con los demás (consulta la referencia de herramientas). Sus argumentos:
task(obligatorio): lo que enseña la guía, por ejemplo «cómo crear una cuenta».lang: el idioma de la guía como código,esoen(por defectoen).url: dónde empieza el recorrido (opcional: si no, la pestaña actual).
El agente explora el flujo, lo ejecuta una vez como ejecución de prueba con la opción guide, comprueba el resultado e informa de los archivos.
La opción guide
El prompt usa una opción de astral.test, que también puedes definir tú mismo en un script:
await astral.test('Create a customer', async () => {
await astral.step('Open the customers page', () =>
astral.navigate({url: 'http://127.0.0.1:4555/'}));
// ...the rest of the flow
}, {
record: 'video',
guide: {lang: 'es', title: 'Crear un cliente', intro: 'Cómo dar de alta un cliente nuevo.'}
});guide acepta lang, title e intro. Activa por sí misma las capturas por acción; añade record: 'video' para obtener también una grabación. El resultado de la ejecución incluye guide: {md, html, lang}.
Idiomas
Los rótulos dibujados en la página y las etiquetas de la guía (Resultado, Ver la grabación, Captura de pantalla) están traducidos para inglés y español. Cualquier otro código de idioma recurre a los rótulos en inglés, mientras que los nombres de los pasos, el título y la introducción quedan en el idioma en que los escribió el agente. Nombra cada paso como lo haría el usuario, por ejemplo «Crea tu cuenta», no como lo haría una prueba.
Contraseñas
Una contraseña escrita nunca llega a la guía. La instrucción dice “Escribe tu contraseña en «Password»” (o “Type your password in «Password»” en inglés) y el valor no se escribe en ningún archivo.
Recorridos fallidos
Si un paso falla, la guía se escribe igualmente, pero empieza con una advertencia, “This walkthrough did not complete: step N failed. Do not publish this guide as it is.” (en el idioma de la guía), y el paso fallido queda marcado. Corrige el flujo y vuelve a ejecutarlo.
Cómo se ve
El guide.md de una ejecución real contra la app de demostración DevLab (solo se sustituye la dirección):
# Cómo crear una cuenta
Esta guía te lleva por el registro paso a paso.
## 1. Abre la página de registro
1. Ve a https://your-app.example/register
## 2. Rellena tus datos
1. Escribe «Ana Guía» en «Name»
2. Escribe «[email protected]» en «Email»
3. Escribe tu contraseña en «Password»
4. Escribe tu contraseña en «Confirm password»
## 3. Crea la cuenta
1. Haz clic en «Create account»
## Resultado
[Ver la grabación](recording.mp4)Los nombres de los campos vienen de las propias etiquetas de la app, así que una app en inglés da «Email» dentro de frases en español.
Plataformas
Verificado solo en macOS. La grabación MP4 se codifica en macOS; en otros sistemas la grabación es un PNG animado. Windows y Linux no están verificados para el modo guía.