explorbot 0.2.3 → 0.2.5

package/docs/web-testing/hooks.md

@@ -0,0 +1,238 @@
+# Agent Hooks
+
+Hooks run custom code before or after a specific agent. Use them to prepare and clean up the page per agent.
+
+> [!NOTE]
+> For simple page automation such as waiting or clicking cookie banners, use [Knowledge Files](../workflow/knowledge.md) with the `wait`, `waitForElement`, or `code` fields. Reach for hooks when you need different behavior for different agents.
+
+## When to Use Hooks vs Knowledge
+
+| Use Case | Solution |
+|----------|----------|
+| Wait for element on all page visits | Knowledge: `waitForElement` |
+| Dismiss cookie banner on page load | Knowledge: `code` |
+| Wait for network idle only during research | Hook: `researcher.beforeHook` |
+| Clean up test data after each test | Hook: `tester.afterHook` |
+| Different waits for navigation vs testing | Hooks for each agent |
+
+## Configuration
+
+Hooks are configured per-agent in `explorbot.config.js`:
+
+```javascript
+export default {
+  ai: {
+    model: myProvider('gpt-4o'),
+    agents: {
+      navigator: {
+        beforeHook: {
+          type: 'playwright',
+          hook: async ({ page, url }) => {
+            await page.waitForLoadState('networkidle');
+          }
+        }
+      },
+      tester: {
+        afterHook: {
+          type: 'codeceptjs',
+          hook: async ({ I, url }) => {
+            await I.executeScript(() => localStorage.clear());
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+## Hook Types
+
+### Playwright Hooks
+
+Get direct access to the Playwright page object:
+
+```javascript
+beforeHook: {
+  type: 'playwright',
+  hook: async ({ page, url }) => {
+    await page.waitForLoadState('networkidle');
+    await page.locator('.loading').waitFor({ state: 'hidden' });
+  }
+}
+```
+
+### CodeceptJS Hooks
+
+Use the CodeceptJS `I` actor:
+
+```javascript
+beforeHook: {
+  type: 'codeceptjs',
+  hook: async ({ I, url }) => {
+    await I.waitForElement('.page-ready');
+    await I.wait(1);
+  }
+}
+```
+
+## URL Pattern Matching
+
+Run different hooks for different URL patterns:
+
+```javascript
+researcher: {
+  beforeHook: {
+    '/login': {
+      type: 'codeceptjs',
+      hook: async ({ I }) => await I.waitForElement('#login-form')
+    },
+    '/admin/*': {
+      type: 'playwright',
+      hook: async ({ page }) => await page.waitForLoadState('networkidle')
+    },
+    '/api/*': {
+      type: 'codeceptjs',
+      hook: async ({ I }) => await I.wait(2)
+    }
+  }
+}
+```
+
+### Pattern Syntax
+
+| Pattern | Matches |
+|---------|---------|
+| `/login` | Exact path `/login` |
+| `/admin/*` | `/admin` and any path starting with `/admin/` |
+| `*` | All URLs (fallback) |
+| `^/users/\d+$` | Regex: `/users/` followed by digits |
+| `**/*.html` | Glob: any `.html` file |
+
+## Supported Agents
+
+| Agent | beforeHook | afterHook | Description |
+|-------|------------|-----------|-------------|
+| `navigator` | After navigation | After page capture | Browser navigation |
+| `researcher` | After navigation | After research complete | Page analysis |
+| `tester` | Before test loop | After test loop | Test execution |
+| `driller` | Before drilling starts | After drilling completes | Component drilling |
+| `captain` | Before handling command | After command complete | User commands |
+
+> [!WARNING]
+> The `planner` agent does not support hooks as it doesn't interact with the browser.
+
+## Examples
+
+### Wait for SPA to Load
+
+```javascript
+navigator: {
+  beforeHook: {
+    type: 'playwright',
+    hook: async ({ page }) => {
+      await page.waitForFunction(() => {
+        return window.__APP_READY__ === true;
+      });
+    }
+  }
+}
+```
+
+### Dismiss Modals Before Research
+
+```javascript
+researcher: {
+  beforeHook: {
+    type: 'codeceptjs',
+    hook: async ({ I }) => {
+      const modalVisible = await I.grabNumberOfVisibleElements('.modal-overlay');
+      if (modalVisible > 0) {
+        await I.click('.modal-close');
+        await I.wait(0.5);
+      }
+    }
+  }
+}
+```
+
+### Clean Up After Tests
+
+```javascript
+tester: {
+  afterHook: {
+    type: 'playwright',
+    hook: async ({ page }) => {
+      await page.evaluate(() => {
+        localStorage.clear();
+        sessionStorage.clear();
+      });
+    }
+  }
+}
+```
+
+### Different Behavior per URL
+
+```javascript
+tester: {
+  beforeHook: {
+    '/checkout': {
+      type: 'codeceptjs',
+      hook: async ({ I }) => {
+        // Ensure cart has items before checkout tests
+        await I.executeScript(() => {
+          if (!localStorage.getItem('cart')) {
+            localStorage.setItem('cart', JSON.stringify([{ id: 1, qty: 1 }]));
+          }
+        });
+      }
+    },
+    '/admin/*': {
+      type: 'codeceptjs',
+      hook: async ({ I }) => {
+        // Ensure admin session
+        await I.waitForElement('.admin-header', 5);
+      }
+    }
+  }
+}
+```
+
+## Error Handling
+
+A hook error is logged but does not stop the agent:
+
+```javascript
+beforeHook: {
+  type: 'codeceptjs',
+  hook: async ({ I }) => {
+    try {
+      await I.waitForElement('.optional-banner', 2);
+      await I.click('.dismiss');
+    } catch {
+      // Banner not present, continue
+    }
+  }
+}
+```
+
+## Execution Flow
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                    Agent Execution                       │
+├─────────────────────────────────────────────────────────┤
+│  1. Agent starts                                         │
+│  2. Navigate to URL (if applicable)                      │
+│  3. ▶ beforeHook executes                               │
+│  4. Agent performs main work                             │
+│  5. ▶ afterHook executes                                │
+│  6. Agent completes                                      │
+└─────────────────────────────────────────────────────────┘
+```
+
+## See Also
+
+- [Knowledge Files](../workflow/knowledge.md) — page-level automation with `wait`, `waitForElement`, `code`
+- [Configuration](../reference/configuration.md) — full configuration reference
+- [Agents](./agents.md) — agent descriptions and workflows

package/docs/web-testing/page-interaction.md

@@ -0,0 +1,84 @@
+# Page Interaction
+
+This page explains how Explorbot agents read a web page and act on it — and the two things you can change to help them: filtering noisy HTML and marking custom components.
+
+## How agents see a page
+
+Agents read each page three ways at once:
+
+| Source | What it gives | Used for |
+|--------|---------------|----------|
+| **ARIA snapshot** | Roles, labels, states, hierarchy | Understanding structure, building locators |
+| **HTML** | Classes, IDs, data attributes, form fields | Precise locators, reading field values |
+| **Screenshot** | Layout, colors, icons, coordinates | Visual checks, click fallbacks |
+
+The accessibility tree is the primary source. HTML adds detail. The screenshot is a fallback when the first two aren't enough.
+
+## Filter noisy HTML
+
+Agents work from the `combined` HTML snapshot. Cookie banners, chat widgets, ads, and analytics tags add noise and burn tokens. Exclude them in your config:
+
+```javascript
+// explorbot.config.js
+html: {
+  combined: {
+    include: ['*'],
+    exclude: ['script', 'style', 'svg', '.cookie-banner', '.analytics-tracker'],
+  },
+}
+```
+
+Three snapshots exist, each configurable:
+
+| Snapshot | Purpose | Config key |
+|----------|---------|------------|
+| `combined` | Main HTML for agents | `html.combined` |
+| `minimal` | Interactive elements only | `html.minimal` |
+| `text` | Text content only | `html.text` |
+
+## Mark custom components
+
+Some components are interactive but have no ARIA role or semantic HTML, so agents miss them. Mark them with a `data-explorbot-*` attribute:
+
+```html
+<div data-explorbot-role="button" data-explorbot-label="Save Draft">
+  <svg>...</svg>
+  Save
+</div>
+```
+
+A marked element is always kept in snapshots, treated as interactive, and shown to agents. During processing, `data-explorbot-role="button"` becomes `role="button"`, so you add a hint without changing how your component behaves.
+
+Use this when standard locators fail to find an element, or when a custom control isn't detected as interactive.
+
+## Locator priority
+
+When an agent picks a locator, it prefers the most stable option first:
+
+```mermaid
+flowchart LR
+    A[ARIA, semantic text, and role] --> B[Scope with a container]
+    B --> C[HTML attributes, CSS, or XPath]
+    C --> D[Screenshot and visual coordinates]
+```
+
+The agent starts with short semantic locators from ARIA or visible text. When a match is ambiguous, it scopes that locator to a container before moving to HTML-based selectors and, finally, visual coordinates.
+
+1. Short ARIA or text — `I.click({ role: 'button', text: 'Save' })` or `I.click('Save')` when it is unique
+2. Text with a container — `I.click('Save', '.modal')` — simplest and preferred when a container is known
+3. ARIA with a container — `I.click({ role: 'button', text: 'Save' }, '.modal')` — for semantic disambiguation
+4. CSS or XPath — `I.click('#save-btn')`
+5. Coordinates — `I.clickXY(400, 300)` (last resort)
+
+When a locator fails, the agent tries the next strategy, then a visual click. Locators that worked are saved to experience and preferred on the next run.
+
+## What happens after each action
+
+After every action, Explorbot captures the new page state and compares it with the previous one. The resulting diff tells the agent what changed — the URL, the accessibility tree, or the HTML — so it can confirm the action worked and decide what to do next. The Researcher turns a page into a structured UI map of sections and elements; see [Researcher](./researcher.md).
+
+## See also
+
+- [Knowledge files](../workflow/knowledge.md) — teach Explorbot about your app
+- [Agent hooks](./hooks.md) — run code before or after an agent
+- [Configuration](../reference/configuration.md) — full configuration reference
+- [Researcher](./researcher.md) — how pages become UI maps

package/docs/web-testing/planner.md

@@ -0,0 +1,122 @@
+# Planner Agent
+
+The Planner agent turns Researcher findings into test scenarios. Each scenario has steps, expected outcomes, and a priority, ready for the Tester to run.
+
+## Overview
+
+When you run `/plan` or `/explore`, the Planner:
+
+1. Receives the Researcher's UI map of the current page.
+2. Applies a planning style.
+3. Generates 3 to 12 scenarios with steps and expected outcomes.
+4. Assigns priorities based on business importance.
+
+Run it again and the Planner adds new scenarios in a different style. It skips scenarios that already exist.
+
+## Write a useful focus
+
+Focus works best when it names one feature boundary, the user goal, and the behavior that matters. Treat it as a testing brief, not a keyword.
+
+```bash
+npx explorbot plan /checkout --focus "Guest checkout: complete an order with card payment; cover validation, declined payment, retry, and confirmation without testing account registration"
+```
+
+The same focus works in the TUI:
+
+```
+/plan --focus "Guest checkout: complete an order with card payment; cover validation, declined payment, retry, and confirmation without testing account registration"
+```
+
+`checkout` alone leaves the scope ambiguous. The fuller focus tells Planner where the flow starts and ends, which outcomes deserve scenarios, and what to leave out. Keep the focus observable from the current page; put durable product facts or credentials in [Knowledge](../workflow/knowledge.md), not in the focus.
+
+## Configuration
+
+```javascript
+ai: {
+  agents: {
+    planner: {
+      model: groq('gpt-oss-20b'),
+      styles: ['normal', 'curious', 'psycho'],
+      rules: [
+        { '/checkout/*': 'payment-focus' },
+      ],
+    },
+  },
+}
+```
+
+### Options Reference
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `model` | `LanguageModel` | default model | Override model for Planner |
+| `styles` | `string[]` | `['normal', 'curious', 'psycho']` | Style names and cycling order |
+| `rules` | `RuleEntry[]` | `[]` | URL-aware rule files from `rules/planner/` |
+| `systemPrompt` | `string` | - | Inline instructions appended to the prompt |
+
+## Planning Styles
+
+A style is a testing approach that shapes which tests the Planner creates. Styles cycle on each planning iteration, so repeated runs produce different kinds of tests. See [Planning Styles](../workflow/planning-styles.md) for how cycling works, custom style files, and `extract-rules`.
+
+### Built-in Styles
+
+All three built-in styles rank scenarios by outcome strength, from strongest to weakest:
+
+1. **Data change** — a record is created, edited, deleted; a setting is persisted; a message is sent; a job is triggered.
+2. **State change** — a route change, a filter or sort applied to real data, a mode or auth change the app remembers.
+3. **UI-only change** — something opens, closes, is cancelled, is hovered, or is toggled for display. The application registers nothing new.
+
+The Planner prefers scenarios that end in category 1 or 2. It proposes category 3 only when the UI-only behaviour has a verifiable side effect, such as a warning prompt, a persisted draft, or a badge appearing.
+
+| Style | Focus | What it generates |
+|-------|-------|-------------------|
+| **normal** | Complete user workflows | CRUD operations, full commit flows, filter+verify flows, distributed across feature areas. UI-only tests (tab switching, pagination, view toggles) come last. |
+| **curious** | Coverage gaps | Cross-references previous test results with page research to find untested controls. Variation scenarios and dismissal scenarios are kept separate — the planner will not merge them by appending a cancel at the end. |
+| **psycho** | Invalid and extreme inputs | Attacks **every reachable control in the same scenario** with a different strange value — empty, 10000 chars, unicode, SQL, script tags, invalid formats, conflicting toggles, out-of-range dates — then commits. Scenarios that enter bad data and cancel are rejected: the application never received the payload. |
+
+### Style Cycling
+
+The default cycle is: normal, curious, psycho, then back to normal. The 1st `/plan` uses normal, the 2nd curious, the 3rd psycho. Each iteration proposes only scenarios that aren't already in the plan. When all feature areas are covered, the Planner returns an empty list.
+
+Force a specific style:
+
+```
+/plan --style psycho
+```
+
+Set `styles` in the config to control the rotation. To customize or add style files, see [Planning Styles](../workflow/planning-styles.md).
+
+## Page-Specific Rules
+
+Use [rules](../reference/configuration.md#rules) to give the Planner extra instructions for specific pages:
+
+```javascript
+planner: {
+  rules: [
+    'no-delete-tests',                    // rules/planner/no-delete-tests.md — all pages
+    { '/checkout/*': 'payment-rules' },   // rules/planner/payment-rules.md — checkout only
+    { '/admin/*': 'admin-scenarios' },    // rules/planner/admin-scenarios.md — admin pages
+  ],
+}
+```
+
+Rules are additive. The Planner concatenates all matching rules and appends them to its prompt alongside the active style.
+
+## Test Priorities
+
+The Planner assigns priorities by business importance:
+
+| Priority | Meaning | Examples |
+|----------|---------|---------|
+| **critical** | Core business functionality | Login, checkout, primary CRUD |
+| **important** | Key user flows | Profile edit, search, main filters |
+| **high** | Secondary features | Edge cases for critical flows |
+| **normal** | Supporting actions | Settings, configuration |
+| **low** | Minor interactions | Cosmetic checks, boundary tests |
+
+## See Also
+
+- [Planning Styles](../workflow/planning-styles.md) — cycling, custom styles, `extract-rules`
+- [Configuration: Rules](../reference/configuration.md#rules) — URL-aware rule files
+- [Agents](./agents.md) — all agent descriptions
+- [Commands](../reference/commands.md) — CLI and TUI commands

package/docs/web-testing/rerun.md

@@ -0,0 +1,164 @@
+# Rerunning Tests
+
+Explorbot generates CodeceptJS test files in `output/tests/` after an exploration session. Use the `runs` and `rerun` commands to list, inspect, and re-execute these tests with AI healing.
+
+## Workflow
+
+```
+npx explorbot explore /dashboard          # generates output/tests/dashboard.js
+npx explorbot runs                        # list all generated tests with indices
+npx explorbot runs output/tests/dashboard.js   # preview steps (dry-run)
+npx explorbot rerun output/tests/dashboard.js --session   # run with healing
+npx explorbot rerun output/tests/dashboard.js 3 --session # run test #3 only
+```
+
+## Listing tests
+
+```bash
+npx explorbot runs
+```
+
+Lists all generated test files with numbered scenarios:
+
+```
+Dashboard Testing
+output/tests/dashboard_testing.js
+  1. ❯ Create a new item
+  2. ─ Delete an item (skipped)
+  3. ❯ Edit item title
+```
+
+Active tests show `❯`, skipped tests show `─`.
+
+### Dry-run a file
+
+```bash
+npx explorbot runs output/tests/dashboard_testing.js
+```
+
+Prints the CodeceptJS steps each test runs, including `Before` hooks, without launching a browser. Use it to check what a test does before running it.
+
+## Re-running tests
+
+```bash
+npx explorbot rerun <file> [index] [--session]
+```
+
+Runs tests through CodeceptJS. The Rerunner agent heals steps that fail.
+
+### Index selection
+
+| Syntax | Meaning |
+|--------|---------|
+| _(no index)_ | Run all tests in the file |
+| `3` | Run test #3 only |
+| `1-5` | Run tests 1 through 5 |
+| `1,3,7` | Run specific tests |
+
+Indices match the numbers shown by `npx explorbot runs`.
+
+### What gets skipped
+
+- **Scenario.skip / Scenario.todo** — already marked as skipped in the test file.
+- **Tests without assertions** — tests with no `I.see`, `I.seeElement`, `I.dontSee`, or similar are skipped, because their results can't be verified.
+
+## AI healing
+
+When a step fails, the Rerunner agent diagnoses the problem and tries to fix it. It uses the same tools as the Tester agent: click, form, pressKey, xpathCheck, see, research, and bash.
+
+### How it works
+
+1. A step like `I.click("Save", ".modal")` fails.
+2. The healer receives the current page state (URL, ARIA tree) and trace data.
+3. It diagnoses the cause: wrong page, loading, broken locator, or missing data.
+4. It runs a replacement action, for example waiting for the page to load and then clicking with a corrected locator.
+5. On success, the test continues. On failure, it moves to the next test.
+
+### Healing boundaries
+
+AI healing repairs how an existing step reaches the same intended outcome. It is deliberately not a second exploratory test run.
+
+| Healing can | Healing does not |
+|-------------|------------------|
+| Replace a stale or ambiguous locator | Change the scenario's business intent |
+| Wait for loading or dismiss a blocking transient UI | Turn a failed assertion into a pass |
+| Restore expected navigation or repeat an equivalent interaction | Invent missing credentials, permissions, or test data |
+| Adapt to a small UI structure change | Work around a real product defect or unavailable service |
+
+The healer only has `healLimit` attempts per test and `healMaxIterations` AI iterations per failed step. It should stop when the expected element or state no longer exists, required data is missing, access is denied, or the application behavior contradicts the assertion. In those cases the test remains failed and the trace preserves the evidence for review.
+
+Successful healing updates the generated test file with the replacement step. Review that diff before committing it: healing shows that an equivalent interaction worked now, not that every UI change is safe or intentional.
+
+### Healing output
+
+During healing, the agent's actions show as substeps:
+
+```
+  ❯ Create a new test
+    I.amOnPage("/projects/testcaselabs/")
+    I.click("Test", ".sticky-header .first")
+    → Healing: I.click("Test", ".sticky-header .first")
+   > ✔ Detected loading spinner, waiting
+   > ✔ Click Test button in toolbar
+    ✔ Healed: I.click({"role":"button","text":"Test"})
+```
+
+### Healing configuration
+
+Configure the Rerunner agent in `explorbot.config.js`:
+
+```javascript
+export default {
+  ai: {
+    agents: {
+      rerunner: {
+        healLimit: 3,           // max heals per test (default: 3)
+        healMaxIterations: 3,   // max AI loop iterations per heal (default: 3)
+        recipes: {
+          // Custom healing recipes (CodeceptJS heal API)
+          waitForLoader: {
+            steps: ['amOnPage'],
+            fn: async () => {
+              return async ({ I }) => {
+                await I.waitForInvisible('.loader', 20);
+              };
+            },
+          },
+        },
+      },
+    },
+  },
+};
+```
+
+### Custom rules
+
+Healing prompt rules live in `rules/rerunner/` as markdown files:
+
+| File | Purpose |
+|------|---------|
+| `healing-approach.md` | Step-by-step diagnosis strategy |
+
+To override a rule, place a file with the same name in your project's `rules/rerunner/` directory.
+
+## Trace output
+
+Each rerun creates a trace directory under `output/states/rerun_<timestamp>/` with per-test artifacts:
+
+- `trace.md` — execution timeline with links to all artifacts
+- `*_aria.txt` — ARIA snapshot per step
+- `*_page.html` — full HTML per step
+- `*_screenshot.png` — screenshot per step
+- `*_console.json` — browser console logs per step
+
+The healer reads these files to diagnose failures.
+
+## After exploration
+
+After `/explore` or `npx explorbot explore`, Explorbot shows the generated test files with rerun suggestions:
+
+```
+Generated: test_management.js
+List tests: npx explorbot runs
+Re-run with healing: npx explorbot rerun <filename> [index]
+```