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)

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}

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.