donobu

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 a package manager (npm 8+, pnpm 10+, or yarn).
• 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

• 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.',
  );
});

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

• BASE64_GPT_CONFIG - Base64 JSON matching GptConfigSchema.
• DONOBU_API_KEY - use Donobu hosted models.
• Anthropic via AWS Bedrock (AWS_BEDROCK_MODEL_NAME, AWS_REGION, AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY).
• Anthropic direct (ANTHROPIC_API_KEY, optional ANTHROPIC_MODEL_NAME).
• Google Gemini (GOOGLE_GENERATIVE_AI_API_KEY, optional GOOGLE_GENERATIVE_AI_MODEL_NAME).
• 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