chore: move to page.agent({ params }) api (#38735)

Author: pavelfeldman

docs/src/api/class-browser.md

@@ -267,9 +267,6 @@ await browser.CloseAsync();
 ### option: Browser.newContext.storageStatePath = %%-csharp-java-context-option-storage-state-path-%%
 * since: v1.9
 
-### option: Browser.newContext.agent = %%-context-option-agent-%%
-* since: v1.58
-
 ## async method: Browser.newPage
 * since: v1.8
 - returns: <[Page]>

docs/src/api/class-page.md

@@ -544,17 +544,6 @@ sequence of events is `request`, `response` and `requestfinished`.
 Emitted when [response] status and headers are received for a request. For a successful response, the sequence of events
 is `request`, `response` and `requestfinished`.
 
-## event: Page.agentTurn
-* since: v1.58
-- argument: <[Object]>
-  - `role` <[string]>
-  - `message` <[string]>
-  - `usage` ?<[Object]>
-    - `inputTokens` <[int]>
-    - `outputTokens` <[int]>
-
-Emitted when the agent makes a turn.
-
 ## event: Page.webSocket
 * since: v1.9
 - argument: <[WebSocket]>
@@ -720,9 +709,42 @@ current working directory.
 
 Raw CSS content to be injected into frame.
 
-## property: Page.agent
+## async method: Page.agent
 * since: v1.58
-- type: <[PageAgent]>
+- returns: <[PageAgent]>
+
+Initialize page agent with the llm provider and cache.
+
+### option: Page.agent.cache
+* since: v1.58
+- `cache` <[Object]>
+  - `cacheFile` ?<[string]> Cache file to use/generate code for performed actions into. Cache is not used if not specified (default).
+  - `cacheOutFile` ?<[string]> When specified, generated entries are written into the `cacheOutFile` instead of updating the `cacheFile`.
+
+### option: Page.agent.maxTurns
+* since: v1.58
+- `maxTurns` <[int]>
+
+Maximum number of agentic turns to take per call. Defaults to 10.
+
+### option: Page.agent.maxTokens
+* since: v1.58
+- `maxTokens` ?<[int]>
+
+### option: Page.agent.provider
+* since: v1.58
+- `provider` <[Object]>
+  - `api` <[PageAgentAPI]<"openai"|"openai-compatible"|"anthropic"|"google">> API to use.
+  - `apiEndpoint` ?<[string]> Endpoint to use if different from default.
+  - `apiKey` <[string]> API key for the LLM provider.
+  - `model` <[string]> Model identifier within the provider. Required in non-cache mode.
+
+### option: Page.agent.secrets
+* since: v1.58
+- `secrets` ?<[Object]<[string], [string]>>
+
+Secrets to hide from the LLM.
+
 
 ## async method: Page.bringToFront
 * since: v1.8

docs/src/api/class-pageagent.md

@@ -1,6 +1,21 @@
 # class: PageAgent
 * since: v1.58
 
+## event: PageAgent.turn
+* since: v1.58
+- argument: <[Object]>
+  - `role` <[string]>
+  - `message` <[string]>
+  - `usage` ?<[Object]>
+    - `inputTokens` <[int]>
+    - `outputTokens` <[int]>
+
+Emitted when the agent makes a turn.
+
+## async method: PageAgent.dispose
+* since: v1.58
+
+Dispose this agent.
 
 ## async method: PageAgent.expect
 * since: v1.58
@@ -10,7 +25,7 @@ Expect certain condition to be met.
 **Usage**
 
 ```js
-await page.agent.expect('"0 items" to be reported');
+await agent.expect('"0 items" to be reported');
 ```
 
 ### param: PageAgent.expect.expectation
@@ -36,7 +51,7 @@ Extract information from the page using the agentic loop, return it in a given Z
 **Usage**
 
 ```js
-await page.agent.extract('List of items in the cart', z.object({
+await agent.extract('List of items in the cart', z.object({
   title: z.string().describe('Item title to extract'),
   price: z.string().describe('Item price to extract'),
 }).array());
@@ -69,7 +84,7 @@ Perform action using agentic loop.
 **Usage**
 
 ```js
-await page.agent.perform('Click submit button');
+await agent.perform('Click submit button');
 ```
 
 ### param: PageAgent.perform.task

docs/src/api/params.md

@@ -370,40 +370,6 @@ It makes the execution of the tests non-deterministic.
 Emulates consistent window screen size available inside web page via `window.screen`. Is only used when the
 [`option: viewport`] is set.
 
-## context-option-agent
-- `agent` <[Object]>
-  - `api` ?<[string]> API to use, `openapi`, `google` or `anthropic`. Required in non-cache mode.
-  - `apiEndpoint` ?<[string]> Endpoint to use if different from default.
-  - `apiKey` ?<[string]> API key for the LLM provider.
-  - `model` ?<[string]> Model identifier within the provider. Required in non-cache mode.
-  - `cacheFile` ?<[string]> Cache file to use/generate code for performed actions into. Cache is not used if not specified (default).
-  - `cacheOutFile` ?<[string]> When specified, generated entries are written into the `cacheOutFile` instead of updating the `cacheFile`.
-  - `secrets` ?<[Object]<[string], [string]>> Secrets to hide from the LLM.
-  - `maxTurns` ?<[int]> Maximum number of agentic turns to take per call. Defaults to 10.
-  - `maxTokens` ?<[int]> Maximum number of tokens to consume per call. The agentic loop will stop after input + output tokens exceed this value. Defaults on unlimited.
-
-Agent settings for [`property: Page.agent`].
-
-## page-agent-api
-* since: v1.58
-- `api` <[string]>
-
-API to use, `openapi`, `google` or `anthropic`. Required in non-cache mode.
-
-## page-agent-api-endpoint
-* since: v1.58
-- `apiEndpoint` <[string]>
-
-Endpoint to use if different from default.
-
-## page-agent-api-key
-* since: v1.58
-- `apiKey` <[string]>
-
-API key for the LLM provider.
-
-API version if relevant.
-
 ## page-agent-cache-key
 * since: v1.58
 - `cacheKey` <[string]>
@@ -425,9 +391,6 @@ Defaults to context-wide value specified in `agent` property.
 Maximum number of agentic turns during this call, defaults to context-wide value specified in `agent` property.
 
 ## page-agent-call-options-v1.58
-- %%-page-agent-api-%%
-- %%-page-agent-api-key-%%
-- %%-page-agent-api-endpoint-%%
 - %%-page-agent-cache-key-%%
 - %%-page-agent-max-tokens-%%
 - %%-page-agent-max-turns-%%

docs/src/test-api/class-fixtures.md

@@ -18,6 +18,10 @@ Given the test above, Playwright Test will set up the `page` fixture before runn
 
 Playwright Test comes with builtin fixtures listed below, and you can add your own fixtures as well. Playwright Test also [provides options][TestOptions] to  configure [`property: Fixtures.browser`], [`property: Fixtures.context`] and [`property: Fixtures.page`].
 
+## property: Fixtures.agent
+* since: v1.58
+- type: <[PageAgent]>
+
 ## property: Fixtures.browser
 * since: v1.10
 - type: <[Browser]>

docs/src/test-api/class-fullconfig.md

@@ -108,7 +108,7 @@ Base directory for all relative paths used in the reporters.
 * since: v1.58
 - type: <['RunAgentsMode]<"all"|"missing"|"none">>
 
-Whether to run LLM agent for [`property: Page.agent`]:
+Whether to run LLM agent for [PageAgent]:
 * "all" disregards existing cache and performs all actions via LLM
 * "missing" only performs actions that don't have generated cache actions
 * "none" does not talk to LLM at all, relies on the cached actions (default)

docs/src/test-api/class-testconfig.md

@@ -518,7 +518,7 @@ export default defineConfig({
 * since: v1.58
 - type: ?<['RunAgentsMode]<"all"|"missing"|"none">>
 
-Whether to run LLM agent for [`property: Page.agent`]:
+Whether to run LLM agent for [PageAgent]:
 * "all" disregards existing cache and performs all actions via LLM
 * "missing" only performs actions that don't have generated cache actions
 * "none" does not talk to LLM at all, relies on the cached actions (default)

docs/src/test-api/class-testoptions.md

@@ -46,10 +46,12 @@ export default defineConfig({
 });
 ```
 
-## property: TestOptions.agent
+## property: TestOptions.agentOptions
 * since: v1.58
 - type: <[Object]>
-  - `provider` ?<[string]> LLM provider to use. Required in non-cache mode.
+  - `api` ?<[string]> LLM provider to use. Required in non-cache mode.
+  - `apiKey` ?<[string]> Key for the LLM provider.
+  - `apiEndpoint` ?<[string]> LLM provider endpoint.
   - `model` ?<[string]> Model identifier within the provider. Required in non-cache mode.
   - `cachePathTemplate` ?<[string]> Cache file template to use/generate code for performed actions into.
   - `maxTurns` ?<[int]> Maximum number of agentic turns to take per call. Defaults to 10.

examples/todomvc/tests/fixtures.ts

@@ -5,6 +5,12 @@ import { test as baseTest } from '@playwright/test';
 export { expect } from '@playwright/test';
 
 export const test = baseTest.extend({
+  agentOptions: {
+    api: 'anthropic',
+    apiKey: process.env.AZURE_SONNET_API_KEY!,
+    apiEndpoint: process.env.AZURE_SONNET_ENDPOINT!,
+    model: 'claude-sonnet-4-5',
+  },
   page: async ({ page }, use) => {
     await page.goto('https://demo.playwright.dev/todomvc');
     await use(page);

examples/todomvc/tests/perform/completing-todos/should-complete-multiple-todos.spec.ts

@@ -1,27 +1,18 @@
 import { test } from '../../fixtures';
 
-test.use({
-  agent: {
-    api: 'anthropic',
-    apiKey: process.env.AZURE_SONNET_API_KEY!,
-    apiEndpoint: process.env.AZURE_SONNET_ENDPOINT!,
-    model: 'claude-sonnet-4-5',
-  }
-});
-
-test('should complete multiple todos', async ({ page }) => {
-  await page.agent.expect(`The page loads with an empty todo list`);
+test('should complete multiple todos', async ({ agent }) => {
+  await agent.expect(`The page loads with an empty todo list`);
 
-  await page.agent.perform(`Add three todos: 'Buy milk', 'Walk dog', 'Finish report'`);
-  await page.agent.expect(`All three todos are visible`);
-  await page.agent.expect(`Counter shows '3 items left'`);
+  await agent.perform(`Add three todos: 'Buy milk', 'Walk dog', 'Finish report'`);
+  await agent.expect(`All three todos are visible`);
+  await agent.expect(`Counter shows '3 items left'`);
 
-  await page.agent.perform(`Complete the first todo by clicking its checkbox`);
-  await page.agent.expect(`First todo is marked as complete`);
-  await page.agent.expect(`Counter shows '2 items left'`);
+  await agent.perform(`Complete the first todo by clicking its checkbox`);
+  await agent.expect(`First todo is marked as complete`);
+  await agent.expect(`Counter shows '2 items left'`);
 
-  await page.agent.perform(`Complete the third todo by clicking its checkbox`);
-  await page.agent.expect(`Third todo is marked as complete`);
-  await page.agent.expect(`Counter shows '1 item left'`);
-  await page.agent.expect(`The 'Clear completed' button appears`);
+  await agent.perform(`Complete the third todo by clicking its checkbox`);
+  await agent.expect(`Third todo is marked as complete`);
+  await agent.expect(`Counter shows '1 item left'`);
+  await agent.expect(`The 'Clear completed' button appears`);
 });