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

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

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

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`

// 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.