Installation & Setup

Prerequisites

• Node.js 20 or later
• @playwright/test ^1.50 (installed alongside Donobu as a peer dependency)
• A Donobu API key — the same key you use to run tests (see Quick Start for how to create one)

Quick setup with npx donobu init

The fastest way to set up a project is the init command. Run it in your project root:

npx donobu@latest init

init does the following:

1. Writes the .npmrc lines that point @donobu/* at Donobu's private registry, in the form your package manager understands.
2. Makes sure .gitignore covers .env.
3. Finds your Donobu API key in the environment or in the project's .env. Without a key, it stops and tells you what to do.
4. Installs @donobu/test as a dev dependency with your project's package manager.
5. Adds a prepare script that refreshes the Donobu agent skill on every install. An existing prepare script is left alone.
6. Installs the Donobu skill for coding agents (npx donobu skills install) and checks your key with npx donobu status.

You can run init again at any time. Use @latest, because a bare npx donobu may reuse an older cached copy. After init, add @playwright/test if your project does not have it yet, install Playwright's browsers with npx playwright install, and continue with "Configure playwright.config.ts" below.

To set up the project by hand instead, follow the steps below.

Configure private registry access

Set your API key as an environment variable so both npm and Donobu can read it:

export DONOBU_API_KEY=your_key_here

Then add an .npmrc file to your project root, pointing npm at the Donobu registry:

@donobu:registry=https://api.donobu.com/npm/
//api.donobu.com/npm/:_authToken=${DONOBU_API_KEY}

With pnpm, write the auth line as //api.donobu.com/npm/:_authToken=${DONOBU_API_KEY:-unset}. pnpm ignores the whole .npmrc when the variable is not set, and the fallback prevents that. npm, Yarn, and Bun do not support the fallback form, so use the plain form shown above with them.

Because the auth token is read from the DONOBU_API_KEY environment variable, this .npmrc contains no secret and is safe to commit. Make sure DONOBU_API_KEY is set in your shell before installing, and add it as a secret in CI (see CI/CD Integration).

Install

With the registry configured, install Donobu and Playwright:

npm install --save-dev @donobu/test @playwright/test

Then download Playwright's browser binaries:

npx playwright install

Configure playwright.config.ts

A minimal configuration that works well with Donobu:

import { defineConfig, devices } from '@donobu/test';

export default defineConfig({
  testDir: './tests',
  projects: [
    {
      name: 'chromium',
      use: { ...devices['Desktop Chromium'] },
    },
  ],
  timeout: 180_000, // AI-driven flows can take time — 3 minutes is a safe default
  use: {
    baseURL: 'http://localhost:3000',
    screenshot: 'on', // Capture screenshots for every test (used in reports and self-healing)
    video: 'on', // Capture video for every test
  },
  reporter: [
    ['list', { printSteps: true }],
    ['json', { outputFile: 'test-results/playwright-report.json' }],
  ],
});

Why 180 seconds?

A single page.ai() call may invoke many browser actions (clicks, inputs, navigation, scrolls) in sequence. Setting the timeout too low causes tests to time out during legitimate first runs before the result is cached.

Module systems

Donobu ships both ESM and CommonJS builds. Use whichever your project requires — no extra configuration is needed.

ESM (package.json with "type": "module"):

import { expect, test } from '@donobu/test';

CommonJS:

const { test, expect } = require('@donobu/test');

Verify the installation

Create a file tests/smoke.test.ts:

import { expect, test } from '@donobu/test';

test('donobu is installed', async ({ page }) => {
  expect(page.ai).toBeDefined();
});

Run it:

npx donobu test tests/smoke.test.ts

A passing test confirms the installation is working. See Quick Start for a first real test.