donobu/README.md

Create browser automations with an LLM agent and replay them as Playwright scripts.

# 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

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

## Quick Start

1. **Author a test using the Donobu fixture**

```ts
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**

```bash
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:
  ```ts
  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>