donobu - npm

npm

Search<br>Sign UpSign In

donobu

5.63.1 • Public • Published 4 hours ago<br>Readme<br>Code Beta<br>15 Dependencies<br>1 Dependents<br>298 Versions<br>Notice

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

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

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<br>Description

await page.ai(instruction, opts?)<br>Launches an autonomous Donobu flow that can call browser tools.

await page.ai.assert(assertion, opts?)<br>AI assertion against DOM text, screenshot, title, and URL.

await page.ai.extract(schema, opts?)<br>Produce JSON data shaped by a Zod schema using screenshot + history.

Every invocation of page.ai() is cached in /.cache-lock/.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/.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:<br>test('uses secret', async ({ page }, testInfo) => {<br>await page.ai('Log in using {{$.env.MY_SECRET}} credentials', {<br>envVars: ['SOME_OTHER_SECRET'],<br>});<br>});

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<br>What it does

npx donobu test [playwright args]<br>Runs Playwright tests with Donobu fixtures, triage, optional auto-heal, and Page.AI caching controls.

npx donobu test --auto-heal<br>After failures, generate treatment plans and automatically retry tests whose plans recommend it.

npx donobu test --no-triage<br>Skip evidence gathering (faster but no treatment plans).

npx donobu test --triage-output-dir ./artifacts<br>Persist evidence outside test-results/donobu-triage.

npx donobu test --clear-ai-cache<br>Clear Page.AI cache before every act() invocation for the run.

npx donobu heal --plan path/to/plan.json<br>Re-run a previously generated treatment plan with matching Playwright args.

npx playwright-json-to-markdown report.json<br>Convert Playwright JSON reports into human-friendly Markdown.

npx playwright-json-to-slack-json report.json<br>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/-/.

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