Donobu SDK

Create, run, and heal AI-assisted Playwright flows with a single dependency. The donobu package ships the Playwright fixture, Page.AI orchestration layer, CLI wrapper, failure triage, and plugin system to comprehensively test websites.

Highlights

• Typed Playwright fixture - import { test } from 'donobu' to extend Playwright with page.ai helpers, smart selectors, and persistence.
• Autonomous Page.AI - run page.ai() with optional Zod schemas, cached tool-call replays, custom tool allow-lists, and env-var controls.
• Prebuilt tools - call keyboard, mouse, accessibility, cookie, and analysis tools via friendly wrappers (page.runAccessibilityTest, etc).
• Failure triage & auto-heal - npx donobu test --auto-heal captures screenshots, GPT reasoning, structured treatment plans, and can re-run fixes automatically.

Prerequisites

• Node.js 18+ and npm 8+.
• Playwright browsers (npx playwright install).
• At least one LLM credential (OpenAI, Anthropic, Google Gemini, AWS Bedrock, or Donobu API).

Installation

npm install --save-dev donobu @playwright/test
npx playwright install        # downloads browsers if needed

Quick Start

1. Author a test using the Donobu fixture

import { test } from 'donobu';

test('Test for https://www.starbucks.com', async ({ page }) => {
  await page.goto('https://www.starbucks.com');
  await page.ai('Go to the featured menu page');
  await page.ai.assert(
    `Assert that the featured menu page has a seasonally appropriate vibe for ${new Date()}`,
  );
  await page.ai('Find a Starbucks store in Stowe, Vermont');
  await page.ai.assert(
    'Assert that a store in Stowe, Vermont is found and the map shows Mt. Mansfield close by.',
  );
});

2. Run the test with Page.AI enabled

OPENAI_API_KEY=sk-*** npx donobu test

npx donobu test proxies Playwright while wiring Donobu-specific env vars (triage directories, Page.AI cache clearing, auto-heal retries, etc.).

Page.AI API Surface

| Method | Description | | ---------------------------------------- | -------------------------------------------------------------------- | | await page.ai(instruction, opts?) | Launches an autonomous Donobu flow that can call browser tools. | | await page.ai.assert(assertion, opts?) | AI assertion against DOM text, screenshot, title, and URL. | | await page.ai.extract(schema, opts?) | Produce JSON data shaped by a Zod schema using screenshot + history. |

• Every invocation of page.ai() is cached in <spec directory>/.cache-lock/<spec-file>.cache.js. Run npx donobu test --clear-ai-cache to regenerate the cache.

Page.AI Caching, Env Vars, and Secrets

• Per-spec cache: Page.AI cache entries are saved next to the spec inside .cache-lock/<spec-file>.cache.js. Commit them to stabilise selectors or delete to regenerate.
• CLI toggles: --clear-ai-cache (or DONOBU_PAGE_AI_CLEAR_CACHE=1) clears cache before each page.ai.act.
• Allow specific env vars by explicitly referencing them by name in the page.ai() instruction or by passing them as options:

  test('uses secret', async ({ page }, testInfo) => {
    await page.ai('Log in using {{$.env.MY_SECRET}} credentials', {
      envVars: ['SOME_OTHER_SECRET'],
    });
  });

  In the above example, the page.ai agent will have access to the MY_SECRET and SOME_OTHER_SECRET env vars.

CLI Usage

npx donobu mirrors Playwright subcommands and adds Donobu-specific tooling.

| Command | What it does | | ------------------------------------------------- | ----------------------------------------------------------------------------------------------------- | | npx donobu test [playwright args] | Runs Playwright tests with Donobu fixtures, triage, optional auto-heal, and Page.AI caching controls. | | npx donobu test --auto-heal | After failures, generate treatment plans and automatically retry tests whose plans recommend it. | | npx donobu test --no-triage | Skip evidence gathering (faster but no treatment plans). | | npx donobu test --triage-output-dir ./artifacts | Persist evidence outside test-results/donobu-triage. | | npx donobu test --clear-ai-cache | Clear Page.AI cache before every act() invocation for the run. | | npx donobu heal --plan path/to/plan.json | Re-run a previously generated treatment plan with matching Playwright args. | | npx playwright-json-to-markdown report.json | Convert Playwright JSON reports into human-friendly Markdown. | | npx playwright-json-to-slack-json report.json | Produce Slack-ready payloads from Playwright reports. |

Failure Evidence & Auto-Heal

• During donobu test, failure evidence (flow metadata, screenshots, DOM dumps, GPT summaries) is stored under test-results/donobu-triage/<timestamp>-<runId>/.
• triageTestFailure builds a structured treatment plan containing failure reason, remediation steps, and automation directives. Plans are written next to the evidence (prefixed with treatment-plan-).
• Passing --auto-heal lets Donobu run an autonomous flow that attempts to fix selectors/code. Successful fixes attach regenerated tests (fixed-test.ts) and annotate runs with @self-healed.

GPT Configuration

Donobu selects a GPT backend in the following priority order:

1. BASE64_GPT_CONFIG - Base64 JSON matching GptConfigSchema.
2. DONOBU_API_KEY - use Donobu hosted models.
3. Anthropic via AWS Bedrock (AWS_BEDROCK_MODEL_NAME, AWS_REGION, AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY).
4. Anthropic direct (ANTHROPIC_API_KEY, optional ANTHROPIC_MODEL_NAME).
5. Google Gemini (GOOGLE_GENERATIVE_AI_API_KEY, optional GOOGLE_GENERATIVE_AI_MODEL_NAME).
6. OpenAI (OPENAI_API_KEY, optional OPENAI_API_MODEL_NAME).

Additional runtime env vars:

| Env var | Purpose | | ------------------------------------------------ | ---------------------------------------------------------------- | | DONOBU_PAGE_AI_CLEAR_CACHE | Force cache invalidation for every page.ai() call. | | BASE_WORKING_DIR | Override the platform-specific Donobu data directory. | | BROWSERBASE_API_KEY / BROWSERBASE_PROJECT_ID | Run flows inside BrowserBase sessions instead of local Chromium. |

Additional Resources

• Example flows and generated tests: https://github.com/donobu-inc/playwright-flows
• Support: https://donobu.com