# page.ai.assert()

## Assert a natural-language condition about the current page, with optional retries for dynamic UIs.

Asserts that a natural-language condition about the current page holds true. If the condition is not met, the method throws and the test fails.

## Signature

```ts
page.ai.assert(
  assertion: string,
  options?: {
    retries?: number;
    retryDelaySeconds?: number;
    gptClient?: GptClient | LanguageModel;
  }
): Promise<void>
```

## Parameters

| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| `assertion` | `string` | — | Plain-English description of the condition to check |
| `options.retries` | `number` | `0` | How many times to retry the assertion if it initially fails. Useful for dynamic UIs that need time to settle. |
| `options.retryDelaySeconds` | `number` | `0` | Seconds to wait between retry attempts |
| `options.gptClient` | `GptClient | LanguageModel` | Project default | Override the AI provider for this call |

## How it works

The AI evaluates the assertion against:

- The current page URL and title
- A viewport screenshot
- The page's text content

Each retry captures a fresh screenshot and page context, giving animations and async updates time to complete.

## Basic usage

```ts
import { test } from 'donobu';

test('checkout confirmation', async ({ page }) => {
  await page.goto('https://shop.example.com/cart');
  await page.ai('Add the first item to the cart and purchase the item');

await page.ai.assert('An order confirmation message is visible');
});
```

## With retries

```ts
await page.ai.assert(
  'The loading spinner has disappeared and content is visible',
  {
    retries: 5,
    retryDelaySeconds: 2,
  },
);
```

## When to use `page.ai.assert` vs. Playwright's `expect`

| Use `page.ai.assert` when… | Use Playwright's `expect` when… |
| --- | --- |
| The condition is subjective or involves understanding the page layout | You are checking an exact text string, number, or URL |
| The relevant information spans multiple elements | You already have a locator for the element you want to check |
| You want retries without writing a `waitFor` loop | You need to check a computed value extracted by `page.ai.extract` |

```ts
// Good use of page.ai.assert — subjective layout condition
await page.ai.assert('The sidebar navigation is collapsed on mobile');

// Better as expect — exact string check
await expect(page.locator('h1')).toHaveText('Welcome back');
```

## Throws

Throws `ToolCallFailedException` if the assertion fails after all retries are exhausted. This exception carries the following properties:

| Property | Type | Description |
| --- | --- | --- |
| `toolName` | `string` | The name of the tool that failed (will be `'assert'`) |
| `result` | `ToolCallResult` | The full result object from the failed assertion |
| `message` | `string` | A human-readable description including the serialised result |

`ToolCallResult` has an `isSuccessful` field (which will be `false`) and a `forLlm` string field that contains a description of what the assertion checked and why it failed.