Implementation:Microsoft Playwright Agent Expect

Knowledge Sources	Playwright Playwright AI Testing
Domains	AI_Testing, Browser_Automation, Test_Assertions
Last Updated	2026-02-11 00:00 GMT

Overview

Concrete API for verifying expected page states using natural language assertions powered by an AI agent, provided by the Playwright library.

Description

The agent.expect() method accepts a natural language expectation string and uses the LLM to determine whether the current page state satisfies that expectation. Unlike agent.perform(), which executes browser actions, expect() is a read-only verification method: it observes the page through accessibility snapshots and evaluates the expectation using 6 specialized assertion tools.

The method resolves its timeout through a priority chain: per-call options.timeout, then the agent-level _expectTimeout, then a default of 5000ms. If the expectation cannot be verified within the timeout, the method throws an assertion error.

The LLM receives the expectation string along with the current page snapshot, then selects and invokes appropriate verification tools. It may invoke multiple tools to verify a compound expectation (e.g., "the page shows the user's name and their email address" might trigger both an expect_visible_text and a expect_value check).

On success, the method resolves its returned Promise. On failure, it throws an error with details about which aspect of the expectation was not met.

Usage

Use agent.expect() when:

• You need to assert page state using natural language descriptions
• You want assertions that are resilient to DOM structure changes
• You are verifying complex page states that would require multiple traditional expect() calls
• You want self-documenting test assertions readable by non-technical team members

Code Reference

Source Location

• Repository: playwright
• File: packages/playwright-core/src/client/pageAgent.ts:L39-42 (client-side proxy)
• File: packages/playwright-core/src/server/agent/pageAgent.ts:L59-75 (server-side implementation)

Signature

agent.expect(
  expectation: string,
  options?: {
    cacheKey?: string;
    maxActions?: number;
    maxTokens?: number;
    timeout?: number;  // defaults to _expectTimeout, then 5000ms
  }
): Promise<void>

Import

// expect() is a method on PageAgent, obtained via page.agent() or the agent fixture
import { test } from '@playwright/test';

test('verify page state', async ({ agent }) => {
  await agent.expect('The welcome message is visible');
});

I/O Contract

Inputs

Name	Type	Required	Description
expectation	string	Yes	Natural language description of the expected page state
options.cacheKey	string	No	Cache key for storing/replaying LLM responses
options.maxActions	number	No	Maximum number of verification actions the agent may execute
options.maxTokens	number	No	Maximum total tokens the agent may consume for this verification
options.timeout	number	No	Timeout in milliseconds (defaults to _expectTimeout, then 5000ms)

Outputs

Name	Type	Description
(resolved)	Promise<void>	Resolves successfully when the expectation is verified
(rejected)	Error	Throws an assertion error when the expectation is not met

Available Assertion Tools

The agent has access to 6 read-only verification tools during expect():

Tool Name	What It Verifies	Example
browser_expect_visible	An element matching a description is visible	"the submit button is visible"
browser_expect_visible_text	Specific text content is visible on the page	"the text 'Welcome back, Alice' is shown"
browser_expect_value	An input field contains a specific value	"the email field contains test@example.com"
browser_expect_list_visible	A list of items matches expected content	"the navigation menu contains Home, About, Contact"
browser_expect_url	The current page URL matches a pattern	"the URL contains /dashboard"
browser_expect_title	The page title matches an expected value	"the page title is 'Dashboard - MyApp'"

Usage Examples

Basic Example

import { test } from '@playwright/test';

test('verify login success', async ({ agent }) => {
  await agent.perform('Log in with username "alice" and password "secret123"');

  // Verify the expected post-login state
  await agent.expect('The dashboard page is displayed with a welcome message for Alice');
  await agent.expect('The navigation bar shows a "Logout" button');
  await agent.expect('The URL contains "/dashboard"');
});

Example with Timeout

import { test } from '@playwright/test';

test('verify async content loads', async ({ agent }) => {
  await agent.perform('Navigate to the reports page');

  // Allow extra time for data to load
  await agent.expect('The sales report table is visible with at least 5 rows of data', {
    timeout: 15000,
  });
});

Example with Compound Expectations

import { test } from '@playwright/test';

test('verify order confirmation page', async ({ agent }) => {
  // ... perform checkout steps ...

  await agent.expect(
    'The order confirmation page shows: an order number, ' +
    'the shipping address matches "123 Main St", ' +
    'and the total amount is displayed'
  );
});

Example Showing Failure Behavior

import { test } from '@playwright/test';

test('expect throws on unmet expectation', async ({ agent }) => {
  await agent.perform('Navigate to an empty shopping cart');

  // This will throw because the cart is empty
  try {
    await agent.expect('The cart contains at least one item');
  } catch (error) {
    console.log('Assertion failed as expected:', error.message);
  }
});

Related Pages

Implements Principle

• Principle:Microsoft_Playwright_Verify_Expectations_with_Agent