explorbot 0.2.3 → 0.2.4

package/docs/contributing/testing.md

@@ -0,0 +1,95 @@
+# Testing Guide
+
+## Running Tests
+
+### Unit Tests
+```bash
+# Run all unit tests
+bun test tests/unit
+
+# Run specific test file
+bun test tests/unit/state-manager.test.ts
+
+# Run tests with coverage
+bun test tests/unit --coverage
+```
+
+### Coverage Reports
+
+#### Text Coverage Report
+```bash
+# Get coverage with text output
+bun run test:coverage
+```
+
+#### Coverage Summary Only
+```bash
+# Get just the coverage summary
+bun run test:coverage:summary
+```
+
+#### LCOV Coverage File
+The `--coverage` flag writes coverage data to `coverage/lcov.info`.
+
+## Coverage Configuration
+
+Coverage is configured in `bunfig.toml`:
+
+- **Coverage Directory**: `coverage/`
+- **Coverage Threshold**: 80%
+- **Included Files**: `src/**/*.{ts,tsx,js,jsx}`
+- **Excluded Files**: Test files, TUI components, build artifacts
+
+## Test Structure
+
+```
+tests/
+├── unit/                    # Unit tests (Bun)
+│   ├── state-manager.test.ts
+│   ├── experience-tracker.test.ts
+│   └── ...
+├── integration/             # AI agent tests with mocked LLM
+├── node/                    # Node.js build smoke tests
+├── regression/              # End-to-end runs with real AI
+└── mocks/                   # Test mocks
+```
+
+This page covers unit tests. The other suites: integration tests exercise AI agents against a mocked LLM via aimock — see [AI integration tests](./ai-integration-tests.md). Node smoke tests in `tests/node/` verify the compiled npm build and run in CI (`bun run test:node`). Regression tests run Explorbot with real AI against a local fixture app — see [regression tests](./regression-tests.md).
+
+## Writing Tests
+
+### Best Practices
+
+1. **Happy path focus**: Test successful scenarios and core functionality.
+2. **Test isolation**: Make each test independent and clean up after itself.
+3. **Descriptive names**: Name tests for what they check.
+4. **Mock external dependencies**: Use `MockAIProvider` for AI-related tests.
+5. **Temp directories**: Use `/tmp/` paths for file system tests.
+
+### Mock AI Provider
+
+```typescript
+import { MockAIProvider } from '../mocks/ai-provider.mock';
+
+const mockAI = new MockAIProvider();
+mockAI.setResponses([
+  { text: 'Mock response 1' },
+  { text: 'Mock response 2' }
+]);
+
+// Use mockAI.getModel() in your tests
+```
+
+## CI/CD Integration
+
+Generate coverage reports for your CI pipeline:
+
+```bash
+# Generate coverage for CI
+bun test tests/unit --coverage --coverage-reporter=lcov
+
+# Check coverage threshold (exits with error if below 80%)
+bun test tests/unit --coverage --coverage-reporter=text
+```
+
+Upload the LCOV file (`coverage/lcov.info`) to a coverage service like Codecov or Coveralls.

package/docs/doc-collection/basics.md

@@ -0,0 +1,128 @@
+# Doc Collection Basics
+
+Explorbot can document your web app for you. The doc collector opens the app in a browser, crawls it page by page, and has AI describe each page: its purpose, screenshots of its sections, and what a user can do there. The result is a browsable markdown spec.
+
+This is useful when you need:
+
+- documentation for an app that has none
+- onboarding material for a new team member
+- a machine-readable spec of your app to feed into agents or test planning
+
+The output is honest about what it knows: every capability is marked as either proven (backed by visible UI) or assumed.
+
+## How it works
+
+The collector starts at the path you give it. For each page it:
+
+1. Navigates to the page and captures its state.
+2. Runs the [Researcher](../web-testing/researcher.md) to map sections and interactive elements.
+3. Asks AI to write the page documentation from that research.
+4. Saves a markdown file plus screenshots, and queues links found on the page.
+
+It repeats this until the queue is empty or the page budget is spent. Only same-origin links are followed.
+
+## Configure
+
+The collector runs on your regular Explorbot setup — the AI provider and browser come from `explorbot.config.js` (see [configuration](../reference/configuration.md)). Crawl behavior lives in a separate file: `docbot.config.ts` (`.js` and `.mjs` work too).
+
+Generate a starter config:
+
+```bash
+npx explorbot docs init
+```
+
+Three options matter for a first run:
+
+```ts
+export default {
+  docs: {
+    maxPages: 100, // how many pages to document
+    output: 'docs', // subfolder inside your output dir
+    screenshot: true, // capture page and section screenshots
+    ignoreErrors: true, // skip pages that fail instead of stopping the crawl
+  },
+};
+```
+
+If no `docbot.config` file exists, these defaults apply. `docs init` refuses to overwrite an existing file unless you pass `--force`.
+
+One more option worth knowing early: `prompt` adds your own instructions to the AI that writes page docs — for example `prompt: 'Focus on billing workflows'`.
+
+## First run
+
+```bash
+npx explorbot docs collect /                       # start from the home page
+npx explorbot docs collect /admin --max-pages 20   # start deeper, smaller budget
+npx explorbot docs collect https://staging.example.com/app  # full URL: its origin becomes the base URL for this run
+```
+
+Useful flags:
+
+- `--max-pages <count>` — override the configured page budget for this run
+- `-s, --show` — watch the browser while it crawls
+- `--session [file]` — reuse a saved login session; needed for apps behind authentication. See [--session](../reference/commands.md#--session).
+- `--docs-config <path>` — load a `docbot.config` from another location
+- `-c, --config <path>`, `-p, --path <dir>`, `--verbose` — same as in other Explorbot commands
+
+When the run finishes it prints how many pages were documented, how many were skipped, and where the spec index is.
+
+## Output files
+
+```
+output/docs/
+├── index.md         # state map and index of everything documented
+├── state-diagram.mmd # raw Mermaid state-transition artifact (reusable by other agents)
+├── pages/           # one markdown file per page
+└── screenshots/     # full-page and section captures
+```
+
+`index.md` opens with run stats and a Mermaid state-transition map, then lists every page with its purpose and capabilities. Page nodes in the diagram link to their documentation. Transient dialogs, modals, tabs, and expanded screen areas appear as child states when interactive collection observes them. Pages that were skipped are listed at the bottom with reasons.
+
+`state-diagram.mmd` is the same state-transition map as a standalone Mermaid file (no markdown fences), so other agents can embed or post-process it without re-rendering `index.md`.
+
+## Use the spec in Explorbot
+
+Pass the generated directory or its `index.md` to any Explorbot web command:
+
+```bash
+npx explorbot start / --spec output/docs
+npx explorbot plan /admin/users --spec output/docs
+npx explorbot explore / --spec output/docs
+```
+
+You can also set `dirs.spec: 'output/docs'` in `explorbot.config.js` to use it by default. Explorbot selects documentation for the current URL instead of loading the whole site spec into every prompt. Proven capabilities and observed transitions are supporting context; possible capabilities remain explicitly unverified until the live UI confirms them.
+
+The format is not tied to Docbot. See [Application Specs](../workflow/application-spec.md) to create or generate a compatible bundle with another tool.
+
+Each page file follows the same shape:
+
+```markdown
+# /admin/users
+
+Title: User Management
+
+## Purpose
+
+Lists all user accounts and provides entry points for managing them.
+
+## Screenshots
+
+![Page screenshot](../screenshots/admin_users_page.png)
+
+## User Can
+
+- user can search users by name -> list of items
+  Proof: Search input above the users table.
+
+## User Might
+
+- user might export the user list -> all items
+  Signal: Toolbar shows an unlabeled download icon.
+```
+
+`User Can` lists capabilities proven by visible UI, each with its evidence. `User Might` lists capabilities the UI suggests but research could not fully confirm. Pages where research found almost nothing are skipped rather than padded with guesses.
+
+## Next steps
+
+- The crawl visited too much, too little, or the wrong pages — tune it in [Choosing What to Crawl](./crawling.md).
+- Document what pages do, not only what they show — enable [Interactive Mode](./interactive-mode.md).

package/docs/doc-collection/crawling.md

@@ -0,0 +1,67 @@
+# Choosing What to Crawl
+
+With defaults, a run crawls everything it can reach on the same origin, up to 100 pages. That is often too much — the crawler wanders into settings and profile pages — or too little, burning the budget before it reaches the part you care about. The options below control where it goes. All of them live under the `docs` key in `docbot.config.ts`.
+
+## How the queue is built
+
+After documenting a page, the crawler queues new targets from three sources: links found on the page, navigation entries identified by research (this is how hash-navigated pages such as OpenAPI reference docs get crawled), and URLs discovered through clicks when [interactive mode](./interactive-mode.md) is on. Every target must pass the filters on this page before it is queued. Pages already visited in this session are not revisited, and the crawl stops early if it detects a dead loop.
+
+## maxPages — the budget
+
+The crawl stops once this many pages are documented. Skipped pages — failed navigation, low-signal pages — do not count against the budget. `--max-pages` on the command line overrides the config for one run.
+
+```ts
+docs: {
+  maxPages: 30,
+}
+```
+
+## scope — how far from the start path
+
+`scope` bounds the crawl relative to the path you start from:
+
+```ts
+docs: {
+  scope: 'subtree',
+}
+```
+
+- `site` (default) — anywhere on the same origin.
+- `subtree` — only the start path and paths beneath it. Starting at `/admin/reports` allows `/admin/reports/2026` but blocks `/admin/users`.
+- `section` — like `subtree`, plus sibling paths that extend the start path with a dash. Starting at `/docs/api` also allows `/docs/api-reference`.
+
+The scope root is the start path (capped at its first four segments for deeper paths). Links outside the scope are never queued.
+
+## includePaths and excludePaths
+
+Path filters for finer control than `scope`:
+
+```ts
+docs: {
+  excludePaths: ['/settings/*', '/help/*'],
+}
+```
+
+Patterns match the URL path: exact paths, `/admin/*` for a path and everything under it, glob patterns like `/users/*/edit`, or a regex prefixed with `^`.
+
+`excludePaths` blocks matching paths. `includePaths` inverts the logic: when it is non-empty, only matching paths are crawled — and it becomes the only filter. `excludePaths` and `deniedPathSegments` are not consulted, so keep include patterns tight enough that they cannot match destructive endpoints.
+
+## deniedPathSegments — the safety list
+
+The crawler follows links in a real browser. Some links are dangerous to follow: `/logout` ends the session, and `delete`- or `destroy`-style endpoints can modify data with a single request. Any URL with a path segment on this list is never queued.
+
+The default list covers sign-out endpoints (`logout`, `signout`, `sign_out`), destructive actions (`delete`, `destroy`, `remove`), and OAuth `callback` routes. Matching is by whole segment, case-insensitive: `/users/delete/3` is blocked because one segment equals `delete`; `/deleted-items` is not.
+
+Setting `deniedPathSegments` replaces the built-in list, so keep the defaults when adding your own entries.
+
+## collapseDynamicPages — one page per template
+
+Apps repeat the same page under many URLs: `/users/1`, `/users/2`, and so on. By default, URLs that differ only in dynamic segments (numeric IDs, UUIDs, hashes) count as the same page, and the first one reached represents them all.
+
+```ts
+docs: {
+  collapseDynamicPages: false,
+}
+```
+
+Set it to `false` when such pages genuinely differ and you want each URL documented separately. Expect the page budget to fill up faster.

package/docs/doc-collection/interactive-mode.md

@@ -0,0 +1,99 @@
+# Interactive Mode and Screenshots
+
+A static crawl documents what each page looks like. Interactive mode also documents what pages do: before writing a page's docs, the collector clicks a few of its controls and records what actually happens. Tabs get switched, panels get opened, and the results become observed behavior instead of guesses.
+
+Enable it in `docbot.config.ts`:
+
+```ts
+export default {
+  docs: {
+    interactive: true,
+  },
+};
+```
+
+## What changes
+
+The collector picks a handful of safe controls on each page and clicks them one by one. After every click it compares page state — the URL and the elements that appeared or disappeared — and records the difference. If a click navigates away, it returns to the page and continues.
+
+These raw observations are handed to the AI as evidence for the page's capabilities, and the page file gains a `## State Transitions` section:
+
+```markdown
+## State Transitions
+
+### Clicked tab: Merged
+
+**Before:** 18 elements (tab:3, link:5, text:7). URL /pulls
+
+**After:** 21 elements (tab:3, link:8, text:7). URL /pulls
+
+**Observed changes:**
+- ARIA snapshot gained 6 elements
+- Visible links after interaction: 8
+```
+
+URLs discovered through clicks join the crawl queue, so interactive mode can reach pages that no plain link points to.
+
+## What gets tried per page
+
+The collector does not click everything:
+
+- **Tabs first.** If research found a tab group (2 to 6 tabs), each tab is clicked to capture the page's alternate states.
+- **Then primary actions.** Up to `maxPrimaryCandidates` (default 3) of the most promising links and buttons from the page's content and control sections. Navigation menus, headers, and footers are excluded. Controls that open dialogs or change a local screen area are recorded as child states; controls inside an already open overlay are not explored recursively.
+- **Hard cap.** `maxInteractions` (default 5) limits total clicks per page, tabs included.
+
+Raise the numbers for control-dense pages you want covered deeply; lower them to speed up large crawls:
+
+```ts
+docs: {
+  interactive: true,
+  maxInteractions: 8,
+  maxPrimaryCandidates: 5,
+}
+```
+
+Clicks that change nothing observable are discarded. If no click on a page produces a meaningful change, or interaction fails entirely, the page falls back to static documentation. Interactive mode adds evidence; it never blocks a page from being documented.
+
+## deniedActionLabels — the click safety list
+
+The crawling filters keep the collector away from dangerous URLs; `deniedActionLabels` does the same for clicks. A control is never clicked when its label or locator contains a denied word. The defaults cover destructive and session-ending vocabulary: `delete`, `remove`, `destroy`, `archive`, `discard`, `logout`, and similar. Matching is substring-based and case-insensitive, so "Delete account" and "Archive all" are both skipped.
+
+Setting `deniedActionLabels` replaces the built-in list, so keep the defaults when adding words specific to your app.
+
+## Low-signal pages
+
+Some crawled pages have nothing worth documenting: empty states, redirect stubs, error pages. A page is skipped from the spec when both are true:
+
+- it yields fewer proven actions than `minCanActions` (default 1), and
+- research found fewer interactive elements than `minInteractiveElements` (default 3)
+
+Skipped pages appear at the end of `index.md` with the reason. This filter applies in static and interactive mode alike. If real pages are being dropped, lower the thresholds; `minCanActions: 0` keeps every page.
+
+## Screenshots
+
+Screenshots are on by default (`screenshot: true`) in both modes. For every documented page the collector captures:
+
+- one full-page screenshot
+- one screenshot per section the [Researcher](../web-testing/researcher.md) identified — a sidebar, a data table, a filter bar — capped by `maxSectionScreenshots` (default 8)
+
+Images land in `output/docs/screenshots/` and are embedded in the page files, each section shot labeled with the CSS selector it was taken from.
+
+Interactive states are captured before the collector restores the original page. DocBot compares viewport screenshots from immediately before and after the action, finds the rectangle containing the changed pixels, adds a 30-pixel margin, and saves that fragment. If the images cannot be compared safely, it saves the current viewport instead.
+
+```ts
+docs: {
+  maxSectionScreenshots: 4,
+}
+```
+
+Set `screenshot: false` to turn captures off entirely. This also disables screenshot-assisted research, which makes the run cheaper and faster but text-only.
+
+## Error handling
+
+`ignoreErrors` controls page-level crawl failures. `true` keeps the current best-effort behavior and skips every failed page, `false` stops the crawl on the first error, and an array skips only errors whose code, name, or message contains one of the listed strings.
+
+```ts
+docs: {
+  ignoreErrors: ['timeout', 'navigation interrupted'],
+}
+```

package/docs/index.json

@@ -0,0 +1,86 @@
+{
+  "title": "Explorbot Documentation",
+  "description": "Explorbot explores your web app, plans tests, and runs them — no scripts required.",
+  "start": "basics/getting-started.md",
+  "sections": [
+    {
+      "title": "Basics",
+      "dir": "basics",
+      "pages": [
+        { "title": "Getting started", "file": "basics/getting-started.md", "description": "Install to first test in ten minutes" },
+        { "title": "Running Explorbot", "file": "basics/running.md", "description": "Interactive TUI vs headless CLI, and when to use each" },
+        { "title": "Prerequisites", "file": "basics/prerequisites.md", "description": "Check that your app is a good fit" },
+        { "title": "Providers", "file": "basics/providers.md", "description": "Set up an AI provider and pick models" }
+      ]
+    },
+    {
+      "title": "Web testing",
+      "dir": "web-testing",
+      "pages": [
+        { "title": "Basics", "file": "web-testing/basics.md", "description": "The explore loop, states, and your first session" },
+        { "title": "Customization", "file": "web-testing/customization.md", "description": "Make it work on your app: login, cookie bars, modals, test data" },
+        { "title": "Planner", "file": "web-testing/planner.md", "description": "Tune what gets tested" },
+        { "title": "Researcher", "file": "web-testing/researcher.md", "description": "How pages are analyzed, and how to tune it" },
+        { "title": "Page interaction", "file": "web-testing/page-interaction.md", "description": "How agents read and act on a page" },
+        { "title": "Automated tests", "file": "web-testing/automated-tests.md", "description": "The runnable test files you keep" },
+        { "title": "Rerun", "file": "web-testing/rerun.md", "description": "Re-run generated tests with AI healing" },
+        { "title": "Agents", "file": "web-testing/agents.md", "description": "What each agent does under the hood" },
+        { "title": "Hooks", "file": "web-testing/hooks.md", "description": "Run your own code before or after an agent" }
+      ]
+    },
+    {
+      "title": "API testing",
+      "dir": "api-testing",
+      "pages": [
+        { "title": "Basics", "file": "api-testing/basics.md", "description": "Chief and Curler, configuration, your first API test" },
+        { "title": "Planning", "file": "api-testing/planning.md", "description": "Specs, endpoint knowledge, and planning styles" },
+        { "title": "Running tests", "file": "api-testing/running-tests.md", "description": "Executing plans, request logs, autonomous explore" }
+      ]
+    },
+    {
+      "title": "Doc collection",
+      "dir": "doc-collection",
+      "pages": [
+        { "title": "Basics", "file": "doc-collection/basics.md", "description": "Crawl your app and generate page docs" },
+        { "title": "Crawling", "file": "doc-collection/crawling.md", "description": "Choose what gets visited" },
+        { "title": "Interactive mode", "file": "doc-collection/interactive-mode.md", "description": "Document behavior, not just pages" }
+      ]
+    },
+    {
+      "title": "Common workflow",
+      "dir": "workflow",
+      "description": "These pages apply to web and API testing alike",
+      "pages": [
+        { "title": "Knowledge", "file": "workflow/knowledge.md", "description": "Teach Explorbot about your app" },
+        { "title": "Application Specs", "file": "workflow/application-spec.md", "description": "Reuse versioned application documentation" },
+        { "title": "Test plans", "file": "workflow/test-plans.md", "description": "The plan file format and how plans are reused" },
+        { "title": "Planning styles", "file": "workflow/planning-styles.md", "description": "Normal, curious, psycho, and your own" },
+        { "title": "Reporting", "file": "workflow/reporting.md", "description": "Local reports and Testomat.io" },
+        { "title": "Continuous integration", "file": "workflow/ci.md", "description": "Scheduled runs with cached experience on any CI" },
+        { "title": "Agentic usage", "file": "workflow/agentic-usage.md", "description": "Drive Explorbot from a coding agent: config-free runs and agent-written plans" }
+      ]
+    },
+    {
+      "title": "Reference",
+      "dir": "reference",
+      "pages": [
+        { "title": "Commands", "file": "reference/commands.md", "description": "Every CLI and terminal command" },
+        { "title": "Configuration", "file": "reference/configuration.md", "description": "The config file, top to bottom" },
+        { "title": "Scripting", "file": "reference/scripting.md", "description": "The programmatic API" }
+      ]
+    },
+    {
+      "title": "Contributing",
+      "dir": "contributing",
+      "pages": [
+        { "title": "Contributing", "file": "contributing/contributing.md", "description": "How to contribute" },
+        { "title": "Observability", "file": "contributing/observability.md", "description": "Trace and debug AI calls" },
+        { "title": "Testing", "file": "contributing/testing.md", "description": "Run the test suite" },
+        { "title": "AI integration tests", "file": "contributing/ai-integration-tests.md", "description": "How agent tests work" },
+        { "title": "Regression tests", "file": "contributing/regression-tests.md", "description": "The real-AI e2e harness" },
+        { "title": "Demo videos", "file": "contributing/demo-videos.md", "description": "Turn recorded sessions into demo clips" },
+        { "title": "npm package", "file": "contributing/npm-package.md", "description": "Build and publish" }
+      ]
+    }
+  ]
+}