explorbot 0.2.3 → 0.2.4

package/docs/reference/scripting.md

@@ -0,0 +1,303 @@
+# Building Custom Scripts
+
+Use Explorbot programmatically to build testing pipelines. This guide shows how to write scripts that run without the TUI.
+
+Explorbot runs on **Bun**. Importing `explorbot` resolves to the TypeScript source under Bun and to the compiled `dist/` build under Node.js, and the package ships type declarations either way — so run your scripts with `bun run`. The package exposes a single entry point:
+
+```typescript
+import { ExplorBot, Plan, Test } from 'explorbot';
+```
+
+Available exports: `ExplorBot`, `Plan`, `Test`, `TestResult`, `TestStatus`, plus the types `ExplorBotOptions`, `WebPageState`, and `ExplorbotConfig`.
+
+## Basic Setup
+
+```typescript
+import { ExplorBot } from 'explorbot';
+
+const bot = new ExplorBot({
+  path: '.',              // Path to explorbot.config.js
+  from: '/dashboard',     // Starting URL
+  verbose: true,          // Enable debug logging
+  show: true,             // Show browser window (false for headless)
+  incognito: true,        // Don't save/load experience files
+});
+
+await bot.start();
+// ... do stuff ...
+await bot.stop();
+```
+
+### Options
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `path` | string | Path to directory containing `explorbot.config.js` |
+| `from` | string | Starting URL path (e.g., `/login`, `/dashboard`) |
+| `verbose` | boolean | Enable debug logging |
+| `show` | boolean | Show browser window (default: false) |
+| `headless` | boolean | Run in headless mode |
+| `incognito` | boolean | Don't persist experience files |
+
+## Navigation
+
+```typescript
+// Visit a page
+await bot.visit('/settings');
+
+// Get current page state
+const state = bot.getCurrentState();
+console.log(state.url);
+console.log(state.title);
+```
+
+## Research
+
+Analyze a page to read its UI:
+
+```typescript
+const state = bot.getCurrentState();
+const research = await bot.agentResearcher().research(state);
+
+console.log(research);
+// Contains: interactive elements, forms, navigation, etc.
+```
+
+Research with options:
+
+```typescript
+await bot.agentResearcher().research(state, {
+  screenshot: true,    // Capture screenshot for vision analysis
+  force: true,         // Re-research even if cached
+  data: true,          // Extract structured data (tables, lists)
+});
+```
+
+## Planning
+
+Generate test scenarios automatically. `bot.plan()` researches the current page, generates a plan, tracks it as the current plan, and saves it to `output/plans/`:
+
+```typescript
+// Plan tests for current page
+const plan = await bot.plan();
+
+console.log(plan.title);
+console.log(plan.tests.map(t => t.scenario));
+// ["Verify login with valid credentials", "Test password validation", ...]
+```
+
+Plan with focus:
+
+```typescript
+// Focus on specific feature
+const plan = await bot.plan('checkout flow');
+// Or from CLI: explorbot plan /checkout --focus "checkout flow"
+```
+
+## Creating Tests Manually
+
+Define your own test scenarios:
+
+```typescript
+import { Plan, Test } from 'explorbot';
+
+const plan = new Plan('User Authentication');
+plan.url = '/login';
+
+const test = new Test(
+  'Verify login with valid credentials',  // Scenario name
+  'high',                                   // Priority: critical, important, high, normal, low
+  [                                         // Expected outcomes
+    'Username field accepts input',
+    'Password field accepts input',
+    'Login button submits form',
+    'User is redirected to dashboard',
+  ],
+  '/login'                                  // Starting URL
+);
+
+plan.addTest(test);
+```
+
+## Running Tests
+
+Execute tests using the Tester agent:
+
+```typescript
+const tester = bot.agentTester();
+
+// Run a single test
+await tester.test(test);
+
+// Check results
+console.log(test.isSuccessful);  // true/false
+console.log(test.hasFailed);     // true/false
+console.log(test.getPrintableNotes());
+```
+
+Run all tests in a plan:
+
+```typescript
+for (const test of plan.tests) {
+  await tester.test(test);
+
+  console.log(`${test.scenario}: ${test.isSuccessful ? 'PASSED' : 'FAILED'}`);
+  test.getPrintableNotes().forEach(note => console.log(`  ${note}`));
+}
+```
+
+## Full Exploration Cycle
+
+Combine research, planning, and testing. `bot.plan()` already researches the current page, so a full cycle is a plan followed by a test run:
+
+```typescript
+await bot.visit('/dashboard');
+
+// Research the page and generate a plan
+const plan = await bot.plan('user settings');
+
+// Run every generated test
+const tester = bot.agentTester();
+for (const test of plan.tests) {
+  await tester.test(test);
+}
+```
+
+For turnkey autonomous exploration — invent scenarios and run them in a loop, unattended — use the CLI:
+
+```bash
+explorbot explore /dashboard --focus "user settings"
+```
+
+## Accessing Results
+
+```typescript
+// Get the current plan
+const plan = bot.getCurrentPlan();
+
+// Check completion
+console.log(plan.isComplete);     // All tests finished
+console.log(plan.allSuccessful);  // All tests passed
+console.log(plan.allFailed);      // All tests failed
+
+// Get pending tests
+const pending = plan.getPendingTests();
+
+// Iterate results
+for (const test of plan.tests) {
+  console.log({
+    scenario: test.scenario,
+    priority: test.priority,
+    status: test.status,        // pending, in_progress, done
+    result: test.result,        // passed, failed, null
+    summary: test.summary,
+    generatedCode: test.generatedCode,  // CodeceptJS code
+  });
+}
+```
+
+## Saving Plans
+
+```typescript
+// Save current plan to markdown
+const path = bot.savePlan();
+// Saved to: output/plans/user-authentication.md
+
+// Save with custom filename
+bot.savePlan('my-custom-plan.md');
+
+// Load a saved plan
+const loaded = bot.loadPlan('my-custom-plan.md');
+```
+
+## Complete Example
+
+```typescript
+#!/usr/bin/env bun
+
+import { ExplorBot, Plan, Test } from 'explorbot';
+
+async function runTests() {
+  const bot = new ExplorBot({
+    path: '.',
+    from: '/login',
+    show: process.env.SHOW === 'true',
+  });
+
+  await bot.start();
+
+  // Navigate and research
+  const state = bot.getCurrentState();
+  await bot.agentResearcher().research(state);
+
+  // Create a test plan
+  const plan = new Plan('Login Flow');
+  plan.url = '/login';
+
+  plan.addTest(new Test(
+    'Login with valid credentials',
+    'high',
+    ['User sees dashboard after login'],
+    '/login'
+  ));
+
+  plan.addTest(new Test(
+    'Login with invalid password',
+    'normal',
+    ['Error message is displayed'],
+    '/login'
+  ));
+
+  // Run tests
+  const tester = bot.agentTester();
+
+  for (const test of plan.tests) {
+    await tester.test(test);
+  }
+
+  // Report results
+  const passed = plan.tests.filter(t => t.isSuccessful).length;
+  const failed = plan.tests.filter(t => t.hasFailed).length;
+
+  console.log(`\nResults: ${passed} passed, ${failed} failed`);
+
+  for (const test of plan.tests) {
+    const icon = test.isSuccessful ? '✓' : '✗';
+    console.log(`${icon} ${test.scenario}`);
+  }
+
+  await bot.stop();
+
+  // Exit with error code if any test failed
+  process.exit(failed > 0 ? 1 : 0);
+}
+
+runTests();
+```
+
+## Running in CI
+
+```bash
+# Run script
+bun run ./scripts/my-tests.ts
+
+# Show browser for debugging
+SHOW=true bun run ./scripts/my-tests.ts
+```
+
+Example GitHub Actions workflow:
+
+```yaml
+- name: Run Explorbot tests
+  env:
+    GROQ_API_KEY: ${{ secrets.GROQ_API_KEY }}
+  run: bun run ./scripts/smoke-tests.ts
+```
+
+## Tips
+
+1. Set `incognito: true` in CI for a clean state.
+2. Set `show: true` during development to watch the browser.
+3. Start small. Test one scenario before you build full suites.
+4. Save plans. Load them later to re-run the same tests.
+5. Check `generatedCode`. Tests produce reusable CodeceptJS code.