feat(api): open api needed for mcp (#39646)

Author: pavelfeldman

docs/src/api/class-browser.md

@@ -158,6 +158,14 @@ System.Console.WriteLine(browser.Contexts.Count); // prints "1"
 
 Indicates that the browser is connected.
 
+## method: Browser.launchOptions
+* since: v1.59
+* langs: js
+- returns: <[Object]>
+
+Returns the launch options that were used to launch this browser. The return type matches the options
+accepted by [`method: BrowserType.launch`].
+
 ## async method: Browser.newBrowserCDPSession
 * since: v1.11
 - returns: <[CDPSession]>
@@ -382,6 +390,14 @@ This API controls [Chromium Tracing](https://www.chromium.org/developers/how-tos
 
 Returns the buffer with trace data.
 
+## method: Browser.userDataDir
+* since: v1.59
+* langs: js
+- returns: <[null]|[string]>
+
+Returns the user data directory that the browser was launched with, or `null` if the browser was
+launched without a persistent context.
+
 ## method: Browser.version
 * since: v1.8
 - returns: <[string]>

docs/src/api/class-browsercontext.md

@@ -968,6 +968,12 @@ Here are some permissions that may be supported by some browsers:
 
 The [origin] to grant permissions to, e.g. "https://example.com".
 
+## method: BrowserContext.isClosedOrClosing
+* since: v1.59
+- returns: <[boolean]>
+
+Indicates that the browser context is in the process of closing or has already been closed.
+
 ## async method: BrowserContext.newCDPSession
 * since: v1.11
 - returns: <[CDPSession]>

docs/src/api/class-locator.md

@@ -1803,6 +1803,12 @@ var banana = await page.GetByRole(AriaRole.Listitem).Last(1);
 ### option: Locator.locator.hasNotText = %%-locator-option-has-not-text-%%
 * since: v1.33
 
+## async method: Locator.normalize
+* since: v1.59
+- returns: <[Locator]>
+
+Returns a new locator that uses best practices for referencing the matched element, prioritizing test ids,
+aria roles, and other user-facing attributes over CSS selectors. This is useful for converting implementation-detail selectors into more resilient, human-readable locators.
 
 ## method: Locator.nth
 * since: v1.14

docs/src/api/class-page.md

@@ -4212,6 +4212,24 @@ Page width in pixels.
 
 Page height in pixels.
 
+## async method: Page.snapshotForAI
+* since: v1.59
+- returns: <[Object]>
+  - `full` <[string]> Full accessibility snapshot of the page.
+  - `incremental` ?<[string]> Incremental snapshot containing only changes since the last tracked snapshot, when using the [`option: Page.snapshotForAI.track`] option.
+
+Returns an accessibility snapshot of the page optimized for AI consumption.
+
+### option: Page.snapshotForAI.timeout = %%-input-timeout-%%
+* since: v1.59
+
+### option: Page.snapshotForAI.track
+* since: v1.59
+- `track` <[string]>
+
+When specified, enables incremental snapshots. Subsequent calls with the same track name will return
+an incremental snapshot containing only changes since the last call.
+
 ## async method: Page.tap
 * since: v1.8
 * discouraged: Use locator-based [`method: Locator.tap`] instead. Read more about [locators](../locators.md).

docs/src/api/class-tracing.md

@@ -176,6 +176,14 @@ and by ':' on other platforms).
 
 Trace name to be shown in the Trace Viewer.
 
+### option: Tracing.start.live
+* since: v1.59
+- `live` <[boolean]>
+
+When enabled, the trace is written to an unarchived file that is updated in real time as actions occur,
+instead of caching changes and archiving them into a zip file at the end. This is useful for live trace
+viewing during test execution.
+
 ## async method: Tracing.startChunk
 * since: v1.15
 

packages/playwright-client/types/types.d.ts

@@ -4533,6 +4533,29 @@ export interface Page {
     height: number;
   }): Promise<void>;
 
+  /**
+   * Returns an accessibility snapshot of the page optimized for AI consumption.
+   * @param options
+   */
+  snapshotForAI(options?: {
+    /**
+     * When specified, enables incremental snapshots. Subsequent calls with the same track name will return an incremental
+     * snapshot containing only changes since the last call.
+     */
+    track?: string;
+  }): Promise<{
+    /**
+     * Full accessibility snapshot of the page.
+     */
+    full: string;
+
+    /**
+     * Incremental snapshot containing only changes since the last tracked snapshot, when using the
+     * [`track`](https://playwright.dev/docs/api/class-page#page-snapshot-for-ai-option-track) option.
+     */
+    incremental?: string;
+  }>;
+
   /**
    * **NOTE** Use locator-based [locator.tap([options])](https://playwright.dev/docs/api/class-locator#locator-tap) instead. Read
    * more about [locators](https://playwright.dev/docs/locators).
@@ -9096,6 +9119,11 @@ export interface BrowserContext {
     origin?: string;
   }): Promise<void>;
 
+  /**
+   * Indicates that the browser context is in the process of closing or has already been closed.
+   */
+  isClosedOrClosing(): boolean;
+
   /**
    * **NOTE** CDP sessions are only supported on Chromium-based browsers.
    *
@@ -9801,6 +9829,12 @@ export interface Browser {
    */
   isConnected(): boolean;
 
+  /**
+   * Returns the launch options that were used to launch this browser. The return type matches the options accepted by
+   * [browserType.launch([options])](https://playwright.dev/docs/api/class-browsertype#browser-type-launch).
+   */
+  launchOptions(): Object;
+
   /**
    * **NOTE** CDP Sessions are only supported on Chromium-based browsers.
    *
@@ -10358,6 +10392,12 @@ export interface Browser {
    */
   stopTracing(): Promise<Buffer>;
 
+  /**
+   * Returns the user data directory that the browser was launched with, or `null` if the browser was launched without a
+   * persistent context.
+   */
+  userDataDir(): null|string;
+
   /**
    * Returns the browser version.
    */
@@ -14150,6 +14190,13 @@ export interface Locator {
     hasText?: string|RegExp;
   }): Locator;
 
+  /**
+   * Returns a new locator that uses best practices for referencing the matched element, prioritizing test ids, aria
+   * roles, and other user-facing attributes over CSS selectors. This is useful for converting implementation-detail
+   * selectors into more resilient, human-readable locators.
+   */
+  normalize(): Promise<Locator>;
+
   /**
    * Returns locator to the n-th matching element. It's zero based, `nth(0)` selects the first element.
    *
@@ -21830,6 +21877,13 @@ export interface Tracing {
    * @param options
    */
   start(options?: {
+    /**
+     * When enabled, the trace is written to an unarchived file that is updated in real time as actions occur, instead of
+     * caching changes and archiving them into a zip file at the end. This is useful for live trace viewing during test
+     * execution.
+     */
+    live?: boolean;
+
     /**
      * If specified, intermediate trace files are going to be saved into the files with the given name prefix inside the
      * [`tracesDir`](https://playwright.dev/docs/api/class-browsertype#browser-type-launch-option-traces-dir) directory

packages/playwright-core/src/client/browser.ts

@@ -34,8 +34,8 @@ export class Browser extends ChannelOwner<channels.BrowserChannel> implements ap
   private _closedPromise: Promise<void>;
   _shouldCloseConnectionOnClose = false;
   _browserType!: BrowserType;
-  _options: LaunchOptions = {};
-  _userDataDir: string | undefined;
+  private _options: LaunchOptions = {};
+  private _userDataDir: string | undefined;
   readonly _name: string;
   readonly _browserName: 'chromium' | 'webkit' | 'firefox';
   private _path: string | undefined;
@@ -152,6 +152,14 @@ export class Browser extends ChannelOwner<channels.BrowserChannel> implements ap
     return this._isConnected;
   }
 
+  launchOptions(): LaunchOptions {
+    return this._options;
+  }
+
+  userDataDir(): string | null {
+    return this._userDataDir ?? null;
+  }
+
   async newBrowserCDPSession(): Promise<api.CDPSession> {
     return CDPSession.from((await this._channel.newBrowserCDPSession()).session);
   }

packages/playwright-core/src/client/browserContext.ts

@@ -75,7 +75,7 @@ export class BrowserContext extends ChannelOwner<channels.BrowserContextChannel>
 
   readonly _serviceWorkers = new Set<Worker>();
   private _harRecorders = new Map<string, { path: string, content: 'embed' | 'attach' | 'omit' | undefined }>();
-  _closingStatus: 'none' | 'closing' | 'closed' = 'none';
+  private _closingStatus: 'none' | 'closing' | 'closed' = 'none';
   private _closeReason: string | undefined;
   private _harRouters: HarRouter[] = [];
   private _onRecorderEventSink: RecorderEventSink | undefined;
@@ -231,7 +231,7 @@ export class BrowserContext extends ChannelOwner<channels.BrowserContextChannel>
     const routeHandlers = this._routes.slice();
     for (const routeHandler of routeHandlers) {
       // If the page or the context was closed we stall all requests right away.
-      if (page?._closeWasCalled || this._closingStatus !== 'none')
+      if (page?._closeWasCalled || this.isClosedOrClosing())
         return;
       if (!routeHandler.matches(route.request().url()))
         continue;
@@ -293,6 +293,10 @@ export class BrowserContext extends ChannelOwner<channels.BrowserContextChannel>
     return [...this._pages];
   }
 
+  isClosedOrClosing(): boolean {
+    return this._closingStatus !== 'none';
+  }
+
   async newPage(): Promise<Page> {
     if (this._ownerPage)
       throw new Error('Please use browser.newContext()');
@@ -511,7 +515,7 @@ export class BrowserContext extends ChannelOwner<channels.BrowserContextChannel>
   }
 
   async close(options: { reason?: string } = {}): Promise<void> {
-    if (this._closingStatus !== 'none')
+    if (this.isClosedOrClosing())
       return;
     this._closeReason = options.reason;
     this._closingStatus = 'closing';

packages/playwright-core/src/client/eventEmitter.ts

@@ -24,12 +24,6 @@
 
 import type { EventEmitter as EventEmitterType } from 'events';
 import type { Platform } from './platform';
-import type { Disposable } from './disposable';
-
-type EventEmitterLike = {
-  on(eventName: string | symbol, handler: (...args: any[]) => unknown): unknown;
-  removeListener(eventName: string | symbol, handler: (...args: any[]) => unknown): unknown;
-};
 
 type EventType = string | symbol;
 type Listener = (...args: any[]) => any;
@@ -402,17 +396,3 @@ function unwrapListeners(arr: Listener[]): Listener[] {
 function wrappedListener(l: Listener): Listener {
   return (l as any).listener;
 }
-
-class EventsHelper {
-  static addEventListener(
-    emitter: EventEmitterLike,
-    eventName: (string | symbol),
-    handler: (...args: any[]) => any): Disposable {
-    emitter.on(eventName, handler);
-    return {
-      dispose: async () => { emitter.removeListener(eventName, handler); }
-    };
-  }
-}
-
-export const eventsHelper = EventsHelper;

packages/playwright-core/src/client/frame.ts

@@ -200,11 +200,6 @@ export class Frame extends ChannelOwner<channels.FrameChannel> implements api.Fr
     return parseResult(result.value);
   }
 
-  async _evaluateFunction(functionDeclaration: string) {
-    const result = await this._channel.evaluateExpression({ expression: functionDeclaration, isFunction: true, arg: serializeArgument(undefined) });
-    return parseResult(result.value);
-  }
-
   async _evaluateExposeUtilityScript<R, Arg>(pageFunction: structs.PageFunction<Arg, R>, arg?: Arg): Promise<R> {
     assertMaxArguments(arguments.length, 2);
     const result = await this._channel.evaluateExpression({ expression: String(pageFunction), isFunction: typeof pageFunction === 'function', arg: serializeArgument(arg) });