Docs: Guide mode

View as Markdown

Guide mode

Available from 0.2.4

Walk an agent through a flow in any web app and Astral writes the user guide for you.

What you get

A guide written from a recorded run, in the run's folder next to report.html:

  • guide.md and guide.html (a self-contained page): a title, an intro, one numbered section per step and a numbered instruction for each action.
  • One screenshot per action, taken before a click, with the target marked.
  • A final Result section with a closing screenshot.
  • A link to the recording: an MP4 on macOS, an animated PNG elsewhere.
  • Only relative file names, so the folder can be moved or zipped as it is.

Ask your agent

Any MCP agent connected to Astral can do it. Ask it, for example: "write a user guide for creating a customer in Spanish". Behind that is the write-guide MCP prompt, which your agent lists with the others (see the tool reference). Its arguments:

  • task (required): what the guide teaches, such as "how to create an account".
  • lang: the guide's language as a code, es or en (default en).
  • url: where the walkthrough starts (optional: the current tab otherwise).

The agent explores the flow, runs it once as a test run with the guide option, checks the result and reports the files.

The guide option

The prompt uses an option of astral.test, which you can also set yourself in a 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 takes lang, title and intro. It turns on per-action screenshots by itself; add record: 'video' to get a recording too. The result of the run carries guide: {md, html, lang}.

Languages

The captions drawn on the page and the guide's labels (Result, Watch the recording, Screenshot) are translated for English and Spanish. Any other language code falls back to English captions, while the step names, the title and the intro stay in whatever language the agent wrote them. Name each step as the user would, such as "Create your account", not as a test would.

Passwords

A typed password never reaches the guide. The instruction reads "Type your password in «Password»" (or "Escribe tu contraseña en «Password»") and the value is not written to any file.

Failed walkthroughs

If a step fails, the guide is still written but starts with a warning, "This walkthrough did not complete: step N failed. Do not publish this guide as it is.", and the failed step is marked. Fix the flow and run it again.

What it looks like

The guide.md of a real run against the DevLab demo app (only the address is replaced):

# 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

   ![Captura de pantalla](01-step1-navigate.png)

## 2. Rellena tus datos

1. Escribe «Ana Guía» en «Name»

   ![Captura de pantalla](03-step2-type.png)

2. Escribe «[email protected]» en «Email»

   ![Captura de pantalla](04-step2-type.png)

3. Escribe tu contraseña en «Password»

   ![Captura de pantalla](05-step2-type.png)

4. Escribe tu contraseña en «Confirm password»

   ![Captura de pantalla](06-step2-type.png)

## 3. Crea la cuenta

1. Haz clic en «Create account»

   ![Captura de pantalla](08-step3-click-before.png)

## Resultado

![Resultado final](10-step3-final.png)

[Ver la grabación](recording.mp4)

The field names come from the app's own labels, so an English app gives «Email» inside Spanish sentences.

Platforms

Verified on macOS only. The MP4 recording is encoded on macOS; on other systems the recording is an animated PNG. Windows and Linux are not verified for guide mode.