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:

import { ExplorBot, Plan, Test } from 'explorbot';

Available exports: ExplorBot, Plan, Test, TestResult, TestStatus, plus the types ExplorBotOptions, WebPageState, and ExplorbotConfig.

Basic Setup

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

// 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:

const state = bot.getCurrentState();
const research = await bot.agentResearcher().research(state);

console.log(research);
// Contains: interactive elements, forms, navigation, etc.

Research with options:

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/:

// 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:

// 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:

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:

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:

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:

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:

explorbot explore /dashboard --focus "user settings"

Accessing Results

// 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

// 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

#!/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

# Run script
bun run ./scripts/my-tests.ts

# Show browser for debugging
SHOW=true bun run ./scripts/my-tests.ts

Example GitHub Actions workflow:

- name: Run Explorbot tests
  env:
    GROQ_API_KEY: ${{ secrets.GROQ_API_KEY }}
  run: bun run ./scripts/smoke-tests.ts

Tips

Set incognito: true in CI for a clean state.
Set show: true during development to watch the browser.
Start small. Test one scenario before you build full suites.
Save plans. Load them later to re-run the same tests.
Check generatedCode. Tests produce reusable CodeceptJS code.