donobu

As of July 4, 2026, future updates to the Donobu SDK are private. See https://www.donobu.com/docs/playwright/installation

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.

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

• 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).

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

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.).

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

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

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

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

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:

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