Your First AI Test (Tutorial)

In this tutorial, you'll write a simple Playwright test that uses page.ai() to automate a browser task in plain English, run it, and view the results in Donobu Studio.

Prerequisites

• Node.js 20 or higher
• Donobu Studio installed and running with at least one LLM provider key configured

Step 0 (optional): Create a new project from scratch

If you already have a Playwright project, skip to Step 1.

Otherwise, set up a fresh project:

mkdir my-donobu-tests
cd my-donobu-tests
npm init -y
npm install donobu
npx playwright install

This gives you a minimal Node.js project with donobu (which includes Playwright) and the browsers needed to run tests. You're ready to write your first test — skip to Step 2.

Step 1: Add Donobu to an existing Playwright project

In your existing project directory, install the donobu package:

npm install donobu

That's it — donobu wraps Playwright, so you don't need to change your Playwright installation or browser setup. Your existing playwright.config.ts and tests continue to work as before. See the Installation guide for additional configuration options.

Step 2: Write your first test

Create a test file at tests/first-test.spec.ts:

import { expect, test } from 'donobu';

test.setTimeout(60_000);
test('search Hacker News for Donobu article', async ({ page }) => {
  await page.goto('https://news.ycombinator.com');

  await page.ai(
    'Scroll down to find the search box and then do a search for "mac app for web testing". Navigate to the first result.',
  );

  // Use a standard Playwright assertion to verify we landed on the right article
  await expect(page.locator('body')).toContainText('Donobu');
});

Notice the key differences from standard Playwright:

1. Import from donobu instead of @playwright/test.
2. Use page.ai() with a plain-English instruction instead of writing every click and input manually.
3. Standard Playwright assertions still work alongside page.ai().

Also note that we're increasing the timeout for our test, since the AI-powered steps can take some time. But subsequent executions will be a lot faster, thanks to our caching technology.

Step 3: Run the test

npx donobu test tests/first-test.spec.ts --headed

You'll see Donobu:

1. Launch a browser
2. Navigate to Hacker News
3. Use the AI to figure out how to search and navigate to the article
4. Execute each step (type in the search box, click the result, etc.)
5. Run the Playwright assertion to verify the page content

Running 1 test using 1 worker
tests/first-test.spec.ts:4:5 › search Hacker News for Donobu article
### some debugging info from Donobu ###
  1 passed (40.1s)

Step 4: View results in Donobu Studio

Open Donobu Studio and navigate to View Flows. You'll see a new flow with the name of your test file name and description: "tests/first-test.spec.ts > search Hacker News for Donobu article".

Click on it to see:

• The step-by-step timeline of actions the AI took
• A screenshot after each action

See Viewing Extension Results in Studio for more details.

Step 5: Run again — cached execution

Run the same test again:

npx donobu test tests/first-test.spec.ts

This time, the test runs much faster. Donobu cached the AI's action sequence from the first run and replays it deterministically — no AI calls needed.

Running 1 test using 1 worker
tests/first-test.spec.ts:4:5 › search Hacker News for Donobu article
### some debugging info from Donobu ###
  1 passed (8.7s)

See Caching for more details on how caching works.

What you learned

• page.ai(instruction) lets you write test steps in plain English
• Import from donobu instead of @playwright/test — everything else stays the same
• npx donobu test runs your tests (supports all Playwright CLI flags)
• Results sync to Studio automatically for local runs
• Caching makes subsequent runs fast and cost-free

What to try next

• Learn about structured data extraction with page.ai.extract()
• Read about self-healing tests that automatically fix themselves when the UI changes
• Set up CI/CD integration to run tests in your pipeline