# Your First AI Test (Tutorial)

## Write your first AI-powered Playwright test using page.ai(), run it, and view the results in Donobu Studio.

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:

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

```bash
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](/content/docs/playwright/installation/index.html) for additional configuration options.

## Step 2: Write your first test
Create a test file at `tests/first-test.spec.ts`:

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

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

**note**  
When running tests as part of your regression suite, don't use the `--headed` argument. We're just adding that here so you can visually see the test executing. The default for Playwright is to run the tests in "headless" mode.

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

```text
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](/content/docs/playwright/donobu-studio/index.html) for more details.

## Step 5: Run again — cached execution
Run the same test again:

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

```text
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](/content/docs/playwright/caching/index.html) 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](/content/docs/playwright/tutorials/data-extraction/index.html) with `page.ai.extract()`
- Read about [self-healing tests](/content/docs/playwright/self-healing/index.html) that automatically fix themselves when the UI changes
- Set up [CI/CD integration](/content/docs/playwright/tutorials/ci-cd-pipeline/index.html) to run tests in your pipeline