explorbot-plan

Writing Explorbot Test Plans

Write an Explorbot test plan by hand in Explorbot's exact markdown format, from a feature description / requirements / docs and a starting URL. No browser or live exploration needed.

Explorbot does not need to be installed to author a plan — it is just a markdown file. Installation is only required later to run the plan (see Output).

Inputs to gather

• The feature / requirements / user story (ask for docs or a description).
• A suite title (the feature under test).
• The start URL: a path relative to the app host (e.g. /login), or a full absolute URL. This is mandatory. Relative paths resolve against web.url in a project config, or against the site the command names (EXPLORBOT_URL / a registered host) in global mode.
• Priority for each scenario: critical, important, high, normal, low.

Format

<!-- suite -->
# User Authentication

### Prerequisite

* URL: /login

<!-- test
priority: critical
-->
# User signs in with valid credentials

## Steps
* Enter a registered email in the email field
* Enter the matching password
* Submit the sign-in form

## Expected
* The user lands on the authenticated dashboard
* The signed-in account is shown in the header

<!-- test
priority: high
-->
# Sign-in is rejected for an unknown account

## Steps
* Enter an unregistered email and any password
* Submit the sign-in form

## Expected
* An invalid-credentials error is shown
* The user stays on the sign-in page

Rules

• <!-- suite --> then the next line is # Suite Title. One suite per file is normal; add more by repeating <!-- suite -->.
• ### Prerequisite — its first list item must be * URL: <path>. This documents the suite-wide start page for readers and the TUI. A relative path resolves against web.url / playwright.url; absolute URLs work too.
• Each test: a <!-- test … priority: <level> … --> block, then # Scenario (h1). Missing priority defaults to normal.
• The Prerequisite URL is the start page for every test in the suite. A scenario that starts on a different page goes in its own suite with its own Prerequisite URL.
• ## Steps and ## Expected use * bullets; wrap a long bullet by indenting continuation lines two spaces.
• Steps are guidance — the Tester adapts them; keep each step atomic and free of brittle selectors. Every ## Expected bullet must be independently verifiable (a data change, state change, or UI change with a real side effect), not a restated step.
• Scenario titles describe a business outcome, not a click path.

Validate

Before handing the plan over, check it has test cases and a URL: /path or URL: https://… Prerequisite. Exit 0 passes; fix the plan and re-run on anything else:

npx -y mdq-cli@latest 'comment(/^test/) && section("Prerequisite") item(/^URL: (\/|https?:\/\/)\S*$/)' <plan-file>

Output

A hand-written plan is input only — Explorbot never rewrites it, so keep it in the repo next to the code it covers (tests/plans/<feature>.md or similar) and pass its path to explorbot test. Save it under the run's output/plans/ only when the user wants it alongside generated plans: output/plans/ in a project setup, ~/.explorbot/sites/<host>/output/plans/ in global mode.

Run it (index: 1, 1,3, 1-5, or * for all):

npx explorbot test checkout-plan.md '*'
EXPLORBOT_URL=https://app.example.com npx explorbot test checkout-plan.md '*'

test takes no URL argument: it uses web.url from a project config, and needs EXPLORBOT_URL in global mode. It exits 0 whenever the session completes — read the report in output/reports/, not the exit code. See [[explorbot-fundamentals]].