Stepshots

Recording

The stepshots record command automates browser interaction to capture screenshots for each step in your tutorials.

How It Works

The CLI launches headless Chrome via the Chrome DevTools Protocol (CDP).
It sets the viewport to the dimensions specified in your config (default: 1280×800).
For each tutorial, it navigates to the starting URL.
For each step, it executes the action (click, type, navigate, etc.), waits for the configured delay, then captures a full-page screenshot.
Screenshots are bundled into a .stepshot file (a zip archive with a manifest.json and PNG images).

Basic Usage

Record all tutorials:

bash

stepshots record

Record specific tutorials by key:

bash

stepshots record --tutorial onboarding --tutorial checkout

Change the output directory:

bash

stepshots record --output ./recordings

Dry Run

See what would be recorded without launching Chrome:

bash

stepshots record --dry-run

Previewing

Preview a tutorial in a visible (non-headless) browser window to verify your steps work correctly:

bash

stepshots preview my-tutorial

Tip

Always preview before recording. This lets you see exactly what Chrome does at each step and catch selector issues early.

Troubleshooting

Chrome not found — Make sure Google Chrome or Chromium is installed and on your PATH. The CLI looks for Chrome at its default install location for your OS.

Selector not found — The step will fail with an error message showing the selector that couldn't be found. Use stepshots preview to debug interactively.

Timeout waiting for selector — The wait action waits up to 10 seconds for an element to appear. If your page takes longer to load, add a delay to the previous step.

Screenshots look wrong — Check your viewport dimensions. Some responsive layouts behave differently at different sizes.