| name | craftdriver |
| description | Explore live web applications with the CraftDriver CLI, validate durable selectors, and write, run, and debug CraftDriver tests. Use when a coding agent needs to inspect a page, drive browser flows, choose locators, author browser automation, or diagnose a failing CraftDriver test. |
CraftDriver browser workflow
Use CraftDriver's CLI to inspect and exercise the running application, then use
the public TypeScript API to write and run durable tests. Chrome is the default
agent workflow.
Core loop
start app → navigate → snapshot → inspect → act → validate selector
→ write test → run focused test → debug from fresh evidence
Actions and expect(locator).to…() auto-wait. Do not add sleeps or hand-written
polling loops.
Selector order
Prefer evidence from the live page in this order:
By.role({ name }) / By.labelText / By.testId
→ exact visible text → stable CSS → XPath only as a last resort
Confirm a selector against the live page with craftdriver exists or
craftdriver find before putting it in a test.
Snapshot refs are exploration-only
CLI snapshots show ref=eN. A ref binds to one element for as long as that
element lives, and is never reassigned to another one: if the element is removed
or duplicated, or the page navigates or reloads, the command fails with
STALE_REF. Take a fresh snapshot when that happens — CraftDriver will not
guess a replacement.
A ref still means nothing outside the current session, so never copy one into
test source. Convert the element into a durable locator and let CraftDriver
check it against the live page:
npx craftdriver locators ref=e7
Use a candidate reported unique (ordered by durability: role + accessible
name, label, test ID, unique text, minimal CSS). If none is unique, add a
data-testid to the application instead of committing a positional selector.
Test rules
- Inspect the repository's existing tests and package scripts before choosing
a test location or command.
- Import only from
craftdriver, never from craftdriver/src/....
- Use public locators and
expect(locator) assertions.
- Read failures by stable
CraftdriverError.code, then gather a fresh
snapshot and focused page evidence.
- Make ordinary reviewable source changes. Never hide a failure with runtime
locator repair.
- Always close the browser in
finally or the repository's existing fixture.
Focused references
- Explore and write a test: workflow.md
- Shell commands: cli.md
- TypeScript API cheatsheet: cheatsheet.md
- Worked library recipes: patterns.md
- Full installed package docs:
node_modules/craftdriver/docs/
- Optional MCP adapter:
node_modules/craftdriver/docs/mcp.md
