# Introduction

## What the Donobu Playwright Extension is and how it extends Playwright with AI-driven test automation and self-healing capabilities.

The Donobu Playwright Extension is a drop-in extension for [Playwright](https://playwright.dev/) that adds AI-driven test automation to your existing test suite. It augments the standard Playwright `Page` object with new methods — most importantly `page.ai()` — that let you write browser tests in plain English rather than hand-coding every click, input, and assertion.

## What problem does it solve?

Standard Playwright tests are brittle: a renamed button, a new modal, or a restructured form can break a dozen tests at once. Maintaining a large Playwright suite often means spending as much time updating tests as writing new ones.

Donobu addresses this in two ways:

1. **AI-Driven Execution** — Instead of prescribing every step, you describe the goal. The AI figures out how to accomplish it using the current state of the page.
2. **Self-Healing** — When a test breaks due to a UI change, Donobu can automatically generate a new action sequence and update the test cache, so the next run passes without manual intervention.

## How it relates to standard Playwright

Donobu is **not a replacement for Playwright** — it is an extension. You still write Playwright tests, use Playwright's `expect` library, and configure `playwright.config.ts`. The only difference is your `test` import, how you run your tests, and a richer `page` object.

```ts
// Before
import { test, expect } from '@playwright/test';

// After — everything else stays the same
import { test, expect } from 'donobu';
```

To run your tests, use `npx donobu test` instead of `npx playwright test`. All Playwright CLI arguments are supported, and Donobu adds its own — see the [CLI Reference](/content/docs/playwright/cli/index.html) for details.

All standard Playwright APIs remain available. Donobu adds new methods on top; it does not remove or break existing ones.

## Key capabilities

| Capability | What it does |
| --- | --- |
| `page.ai(instruction)` | Runs an autonomous AI flow that navigates and interacts with the browser to fulfil a plain-English goal |
| `page.ai(instruction, { schema })` | Same as above, but returns structured data validated against a [Zod](https://zod.dev/) schema |
| `page.ai.assert(condition)` | Asserts a natural-language condition about the current page state |
| `page.ai.extract(schema)` | Reads structured data from the current page without running a full autonomous flow; `schema` is a [Zod](https://zod.dev/) schema |
| `page.find(selector, { failover })` | Smart locator that tries backup selectors automatically if the primary one fails |
| `page.changeTab(url)` | Switches focus to another open tab while keeping the same AI flow context |
| `page.runAccessibilityTest()` | Runs an axe-core accessibility audit and returns structured results |
| Caching | First-run AI decisions are cached and replayed on subsequent runs, making them fast and cost-free. |
| Self-healing | Detects broken tests and repairs them automatically by regenerating the cached action sequence.

## Viewing results in Donobu Studio

Every test run produces a **flow** that is automatically synced to [Donobu Studio](/content/docs/studio/index.html) when running locally. You can use Studio to inspect the step-by-step action timeline, review screenshots, and diagnose failures. See [Viewing Extension Results in Studio](/content/docs/playwright/donobu-studio/index.html) for details on how test names map to flow names and other Extension-specific behavior.

## When to use Donobu vs. plain Playwright

Use plain Playwright assertions and locators when you are testing a specific, stable UI contract (e.g. verifying an exact error message or a computed value). Use `page.ai` for higher-level flows — multi-step user journeys, forms with variable structure, or any interaction that would otherwise require frequent test maintenance.