docwalk
Tutorials for your app that an agent writes, and that fail in CI when the UI changes under them.
A tour that checks itself
Change the app, then replay the tour.
An agent recorded this three-step tour by driving a small sample page. In CI, docwalk test replays it: it finds each element again, takes a new screenshot and compares it with the one in the tutorial. Pick a change to the page and watch the replay.
Tasks
A sample application for docwalk’s example web tour.
- Read the documentation
- Write the tutorial
2 tasks, 1 done
tours/add-a-task 3 steps · threshold 0.0
-
01-find-the-fieldFind the field tier 1pass -
02-type-the-taskType the task tier 1pass -
03-add-it-to-the-listAdd it to the list tier 1pass
$ docwalk test --junit junit.xml add-a-task 3 pass, 0 drift, 0 fail exit 0
docwalk test’s format. The replay itself is an illustration that runs in your
browser. With the zero threshold docwalk recommends for headless capture, any visible change counts as drift.Finding an element again
Four ways, strongest first.
Every highlight stores all four when it’s recorded. Replay tries them in order and reports which one matched. A match on the picture or the old position counts as drift, and replay --update flags the step so someone re-reads the text beside it.
1 · axAccessibility tree
Role, name and path. The exact path first, then the same role and name anywhere in the window.
2 · textThe label, read by OCR
Off by default. On macOS it uses Vision, which comes with the system.
3 · imageA picture of it
A 64×64 template cut at record time, matched at a threshold of 0.85.
4 · rectWhere it used to be
The recorded rectangle, scaled to the window. Always reported as drift.
The package
A tour is a folder you commit.
Steps, screenshots and locator templates live next to your code, pinned by a content hash. It exports to Markdown, a standalone HTML viewer, Driver.js, Shepherd and MkDocs.
tours/add-a-task/ ├── tour.json # steps, prose, locators ├── tour.script.json # what replay runs ├── CHECKSUMS.json ├── steps/ │ ├── 01-find-the-field.png │ └── 01-find-the-field.src.png └── locators/ └── 01-find-the-field.tpl.png
Where it stands
Working on macOS and the web.
It’s a prototype with no public release yet. Native tours are verified on macOS, and web tours run anywhere there’s a Chromium. The Windows and Linux backends are written but not verified on real machines. An agent drives it through the CLI or the MCP server, which carries its own skill.
# record against a page, headless docwalk launch --app http://localhost:3000 --capture cdp # in CI: every tour, with JUnit output docwalk test --junit junit.xml --fail-on-drift # re-shoot what drifted and stage it docwalk replay --update --commit
Capabilities
What it does.
Developers whose screenshots in the docs are three versions out of date.
- 01
Records a tour by driving the real app, then replays it headless in CI with JUnit output
- 02
Four fallback ways to find each element, with weakened matches flagged in the pull request
- 03
Exports to Markdown, a standalone HTML viewer, Driver.js, Shepherd and MkDocs
- 04
An MCP server with a built-in skill, so any agent can write tours
Specification
What it’s built with, and when.
Pulled from the repository each time this site is built.
- State
- Prototype
- Discipline
- Developer tooling
- Shape
- Developer tooling
- Started
- Sep 2026
- Last change
- Sep 2026
- Commits
- 147
- Rust
- MCP
- framewatch
- Chrome DevTools Protocol
- macOS Accessibility
Next
Put docwalk in your pipeline
Ask about hooking it up to the repositories and agents you already run.