Implementation:Microsoft Playwright Agent Fixture

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

Overview

Concrete fixture extension for integrating AI-powered agents into Playwright Test, provided by the Playwright library.

Description

The agent fixture in Playwright Test extends the base test object with two fixtures: agentOptions (a configurable option fixture) and agent (an auto-resolved fixture that creates a PageAgent). Together, they allow any Playwright test to request an AI agent simply by including agent in its parameter list.

The agentOptions fixture is declared as an option (using { option: true }), which means it can be overridden in playwright.config.ts at the project level or in individual test files using test.use().

The agent fixture depends on the page fixture and agentOptions fixture. It:

1. Resolves the cache path from a template (default: {testDir}/{testFilePath}-cache.json) using test metadata
2. Determines the execution mode from the --run-agents CLI flag
3. Creates a PageAgent via page.agent() with the resolved configuration
4. Yields the agent to the test via use(agent)
5. After the test: if the agent recorded any turns, attaches an agent-usage JSON artifact to the test report
6. On test pass: propagates the cache to disk for future replay

Usage

Use the agent fixture when:

• Writing Playwright tests that need AI-driven browser automation
• You want automatic cache management and artifact collection
• You need consistent agent configuration across an entire test project
• You want to leverage the --run-agents CLI flag for execution mode control

Code Reference

Source Location

• Repository: playwright
• File: packages/playwright/src/index.ts:L155 (agentOptions option fixture)
• File: packages/playwright/src/index.ts:L458-497 (agent fixture implementation)

Signature

// Option fixture for configuring the agent
test.extend({
  agentOptions: [({}, use) => use(undefined), { option: true }],

  agent: async ({ page, agentOptions }, use, testInfo) => {
    // Resolve cache path from template
    // Create agent via page.agent(resolvedOptions)
    // yield agent to test
    // After test: attach usage artifacts, persist cache on pass
  },
});

Import

// The agent fixture is included in the standard Playwright test export
import { test, expect } from '@playwright/test';

// The agent is available as a test parameter
test('my ai test', async ({ agent }) => {
  await agent.perform('Navigate to the login page');
});

I/O Contract

Inputs

Name	Type	Required	Description
page	Page	Yes (auto-injected)	The Playwright Page fixture providing the browser page instance
agentOptions	undefined	No	Configuration object with provider, limits, secrets, cachePathTemplate, and systemPrompt
agentOptions.provider	ProviderConfig	No	LLM provider configuration (api, apiKey, model, apiEndpoint, apiTimeout)
agentOptions.limits	LimitsConfig	No	Operational limits (maxTokens, maxActions, maxActionRetries)
agentOptions.secrets	{ name: string; value: string }[]	No	Sensitive values passed to the agent securely
agentOptions.cachePathTemplate	string	No	Template for cache file path (default: {testDir}/{testFilePath}-cache.json)
agentOptions.systemPrompt	string	No	Custom system prompt for the agent
testInfo	TestInfo	Yes (auto-injected)	Playwright TestInfo object providing test metadata, artifact paths, and status

Outputs

Name	Type	Description
agent	PageAgent	A fully configured PageAgent instance ready for use in the test
agent-usage artifact	JSON attachment	After test: JSON artifact with turns, inputTokens, outputTokens (attached if turns > 0)
cache file	JSON file	On test pass: persisted cache file for replaying LLM responses without network calls

Usage Examples

Basic Example

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

test('user can add item to cart', async ({ agent }) => {
  await agent.perform('Navigate to https://demo-store.example.com');
  await agent.perform('Search for "wireless headphones"');
  await agent.perform('Click "Add to Cart" on the first product');
  await agent.expect('The cart badge shows 1 item');
});

Configuring Agent Options in playwright.config.ts

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

export default defineConfig({
  use: {
    agentOptions: {
      provider: {
        api: 'openai',
        apiKey: process.env.OPENAI_API_KEY,
        model: 'gpt-4o',
      },
      limits: {
        maxActions: 20,
        maxTokens: 100000,
      },
      cachePathTemplate: '{testDir}/.cache/{testFilePath}-cache.json',
    },
  },
});

Overriding Options Per Test File

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

// Use a different model for this test file
test.use({
  agentOptions: {
    provider: {
      api: 'anthropic',
      apiKey: process.env.ANTHROPIC_API_KEY,
      model: 'claude-sonnet-4-20250514',
    },
    limits: {
      maxActions: 30,
    },
    secrets: [
      { name: 'ADMIN_PASSWORD', value: process.env.ADMIN_PASSWORD },
    ],
  },
});

test('admin can manage users', async ({ agent }) => {
  await agent.perform('Log in as admin with password ADMIN_PASSWORD');
  await agent.perform('Navigate to the user management page');
  await agent.expect('The user list is visible with at least one user');
});

Running Tests with Different Agent Modes

# Run using cache only (no LLM calls, default mode)
npx playwright test --run-agents=none

# Run with LLM for uncached tasks only
npx playwright test --run-agents=missing

# Always use LLM (regenerate all caches)
npx playwright test --run-agents=all

Related Pages

Implements Principle

• Principle:Microsoft_Playwright_Create_Test_with_Agent_Fixture