chore: resolve locator helper for mcp

Author: pavelfeldman

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

@@ -249,9 +249,8 @@ export class Locator implements api.Locator {
     return await this._frame._queryCount(this._selector);
   }
 
-  async _generateLocatorString(): Promise<string | null> {
-    const { value } = await this._frame._channel.generateLocatorString({ selector: this._selector });
-    return value === undefined ? null : value;
+  async _resolveLocator(options: { sdkLanguage?: channels.SDKLanguage } = {}): Promise<{ resolvedSelector: string, sourceCode: string }> {
+    return await this._frame._channel.resolveLocator({ selector: this._selector, sdkLanguage: options.sdkLanguage });
   }
 
   async getAttribute(name: string, options?: TimeoutOptions): Promise<string | null> {

packages/playwright-core/src/protocol/validator.ts

@@ -213,6 +213,7 @@ scheme.FormField = tObject({
     buffer: tBinary,
   })),
 });
+scheme.SDKLanguage = tEnum(['javascript', 'python', 'java', 'csharp']);
 scheme.APIRequestContextInitializer = tObject({
   tracing: tChannel(['Tracing']),
 });
@@ -367,7 +368,7 @@ scheme.LocalUtilsGlobToRegexResult = tObject({
 });
 scheme.RootInitializer = tOptional(tObject({}));
 scheme.RootInitializeParams = tObject({
-  sdkLanguage: tEnum(['javascript', 'python', 'java', 'csharp']),
+  sdkLanguage: tType('SDKLanguage'),
 });
 scheme.RootInitializeResult = tObject({
   playwright: tChannel(['Playwright']),
@@ -456,7 +457,7 @@ scheme.DebugControllerPausedEvent = tObject({
 });
 scheme.DebugControllerInitializeParams = tObject({
   codegenId: tString,
-  sdkLanguage: tEnum(['javascript', 'python', 'java', 'csharp']),
+  sdkLanguage: tType('SDKLanguage'),
 });
 scheme.DebugControllerInitializeResult = tOptional(tObject({}));
 scheme.DebugControllerSetReportStateChangedParams = tObject({
@@ -1659,11 +1660,13 @@ scheme.FrameFrameElementParams = tOptional(tObject({}));
 scheme.FrameFrameElementResult = tObject({
   element: tChannel(['ElementHandle']),
 });
-scheme.FrameGenerateLocatorStringParams = tObject({
+scheme.FrameResolveLocatorParams = tObject({
   selector: tString,
+  sdkLanguage: tOptional(tType('SDKLanguage')),
 });
-scheme.FrameGenerateLocatorStringResult = tObject({
-  value: tOptional(tString),
+scheme.FrameResolveLocatorResult = tObject({
+  resolvedSelector: tString,
+  sourceCode: tString,
 });
 scheme.FrameHighlightParams = tObject({
   selector: tString,

packages/playwright-core/src/server/dispatchers/frameDispatcher.ts

@@ -178,8 +178,8 @@ export class FrameDispatcher extends Dispatcher<Frame, channels.FrameChannel, Br
     return { value: await this._frame.innerHTML(progress, params.selector, params) };
   }
 
-  async generateLocatorString(params: channels.FrameGenerateLocatorStringParams, progress: Progress): Promise<channels.FrameGenerateLocatorStringResult> {
-    return { value: await this._frame.generateLocatorString(progress, params.selector) };
+  async resolveLocator(params: channels.FrameResolveLocatorParams, progress: Progress): Promise<channels.FrameResolveLocatorResult> {
+    return await this._frame.resolveLocator(progress, params);
   }
 
   async getAttribute(params: channels.FrameGetAttributeParams, progress: Progress): Promise<channels.FrameGetAttributeResult> {

packages/playwright-core/src/server/frames.ts

@@ -1179,16 +1179,16 @@ export class Frame extends SdkObject {
     dom.assertDone(await this._retryWithProgressIfNotConnected(progress, selector, options.strict, true /* performActionPreChecks */, handle => handle._blur(progress)));
   }
 
-  async generateLocatorString(progress: Progress, selector: string): Promise<string | undefined> {
-    const element = await progress.race(this.selectors.query(selector));
+  async resolveLocator(progress: Progress, params: { selector: string, sdkLanguage?: channels.SDKLanguage }): Promise<{ resolvedSelector: string, sourceCode: string }> {
+    const element = await progress.race(this.selectors.query(params.selector));
     if (!element)
-      throw new Error(`No element matching ${this._asLocator(selector)}`);
+      throw new Error(`No element matching ${params.selector}`);
 
     const generated = await progress.race(element.evaluateInUtility(async ([injected, node]) => {
       return injected.generateSelectorSimple(node as unknown as Element);
     }, {}));
     if (!generated)
-      throw new Error(`Unable to generate locator for ${this._asLocator(selector)}`);
+      throw new Error(`Unable to generate locator for ${params.selector}`);
 
     let frame: Frame | null = element._frame;
     const result = [generated];
@@ -1200,12 +1200,14 @@ export class Frame extends SdkObject {
         }, {}));
         frameElement.dispose();
         if (generated === 'error:notconnected' || !generated)
-          throw new Error(`Unable to generate locator for ${this._asLocator(selector)}`);
+          throw new Error(`Unable to generate locator for ${params.selector}`);
         result.push(generated);
       }
       frame = frame.parentFrame();
     }
-    return asLocator(this._page.browserContext._browser.sdkLanguage(), result.reverse().join(' >> internal:control=enter-frame >> '));
+    const resolvedSelector = result.reverse().join(' >> internal:control=enter-frame >> ');
+    const sourceCode = asLocator(params.sdkLanguage ?? this._page.browserContext._browser.sdkLanguage(), resolvedSelector);
+    return { resolvedSelector, sourceCode };
   }
 
   async textContent(progress: Progress, selector: string, options: types.QueryOnSelectorOptions, scope?: dom.ElementHandle): Promise<string | null> {

packages/playwright-core/src/utils/isomorphic/protocolMetainfo.ts

@@ -155,7 +155,7 @@ export const methodMetainfo = new Map<string, { internal?: boolean, title?: stri
   ['Frame.fill', { title: 'Fill "{value}"', slowMo: true, snapshot: true, pausesBeforeInput: true, }],
   ['Frame.focus', { title: 'Focus', slowMo: true, snapshot: true, }],
   ['Frame.frameElement', { internal: true, }],
-  ['Frame.generateLocatorString', { internal: true, }],
+  ['Frame.resolveLocator', { internal: true, }],
   ['Frame.highlight', { internal: true, }],
   ['Frame.getAttribute', { internal: true, snapshot: true, }],
   ['Frame.goto', { title: 'Navigate to "{url}"', slowMo: true, snapshot: true, }],

packages/protocol/src/channels.d.ts

@@ -347,6 +347,7 @@ export type FormField = {
   },
 };
 
+export type SDKLanguage = 'javascript' | 'python' | 'java' | 'csharp';
 // ----------- APIRequestContext -----------
 export type APIRequestContextInitializer = {
   tracing: TracingChannel,
@@ -608,7 +609,7 @@ export interface RootChannel extends RootEventTarget, Channel {
   initialize(params: RootInitializeParams, progress?: Progress): Promise<RootInitializeResult>;
 }
 export type RootInitializeParams = {
-  sdkLanguage: 'javascript' | 'python' | 'java' | 'csharp',
+  sdkLanguage: SDKLanguage,
 };
 export type RootInitializeOptions = {
 
@@ -769,7 +770,7 @@ export type DebugControllerPausedEvent = {
 };
 export type DebugControllerInitializeParams = {
   codegenId: string,
-  sdkLanguage: 'javascript' | 'python' | 'java' | 'csharp',
+  sdkLanguage: SDKLanguage,
 };
 export type DebugControllerInitializeOptions = {
 
@@ -2649,7 +2650,7 @@ export interface FrameChannel extends FrameEventTarget, Channel {
   fill(params: FrameFillParams, progress?: Progress): Promise<FrameFillResult>;
   focus(params: FrameFocusParams, progress?: Progress): Promise<FrameFocusResult>;
   frameElement(params?: FrameFrameElementParams, progress?: Progress): Promise<FrameFrameElementResult>;
-  generateLocatorString(params: FrameGenerateLocatorStringParams, progress?: Progress): Promise<FrameGenerateLocatorStringResult>;
+  resolveLocator(params: FrameResolveLocatorParams, progress?: Progress): Promise<FrameResolveLocatorResult>;
   highlight(params: FrameHighlightParams, progress?: Progress): Promise<FrameHighlightResult>;
   getAttribute(params: FrameGetAttributeParams, progress?: Progress): Promise<FrameGetAttributeResult>;
   goto(params: FrameGotoParams, progress?: Progress): Promise<FrameGotoResult>;
@@ -2905,14 +2906,16 @@ export type FrameFrameElementOptions = {};
 export type FrameFrameElementResult = {
   element: ElementHandleChannel,
 };
-export type FrameGenerateLocatorStringParams = {
+export type FrameResolveLocatorParams = {
   selector: string,
+  sdkLanguage?: SDKLanguage,
 };
-export type FrameGenerateLocatorStringOptions = {
-
+export type FrameResolveLocatorOptions = {
+  sdkLanguage?: SDKLanguage,
 };
-export type FrameGenerateLocatorStringResult = {
-  value?: string,
+export type FrameResolveLocatorResult = {
+  resolvedSelector: string,
+  sourceCode: string,
 };
 export type FrameHighlightParams = {
   selector: string,

packages/protocol/src/protocol.yml

@@ -357,6 +357,14 @@ FormField:
         mimeType: string?
         buffer: binary
 
+SDKLanguage:
+  type: enum
+  literals:
+  - javascript
+  - python
+  - java
+  - csharp
+
 APIRequestContext:
   type: interface
 
@@ -774,13 +782,7 @@ Root:
     initialize:
       internal: true
       parameters:
-        sdkLanguage:
-          type: enum
-          literals:
-          - javascript
-          - python
-          - java
-          - csharp
+        sdkLanguage: SDKLanguage
       returns:
         playwright: Playwright
 
@@ -883,13 +885,7 @@ DebugController:
       internal: true
       parameters:
         codegenId: string
-        sdkLanguage:
-          type: enum
-          literals:
-          - javascript
-          - python
-          - java
-          - csharp
+        sdkLanguage: SDKLanguage
 
     setReportStateChanged:
       internal: true
@@ -2307,12 +2303,14 @@ Frame:
       returns:
         element: ElementHandle
 
-    generateLocatorString:
+    resolveLocator:
       internal: true
       parameters:
         selector: string
+        sdkLanguage: SDKLanguage?
       returns:
-        value: string?
+        resolvedSelector: string
+        sourceCode: string
 
     highlight:
       internal: true

tests/page/page-aria-snapshot-ai.spec.ts

@@ -89,21 +89,21 @@ it('should stitch all frame snapshots', async ({ page, server }) => {
   expect(href3).toBe(server.PREFIX + '/frames/frame.html');
 
   {
-    const locator = await (page.locator('aria-ref=e1') as any)._generateLocatorString();
-    expect(locator).toBe(`locator('body')`);
+    const { sourceCode } = await (page.locator('aria-ref=e1') as any)._resolveLocator();
+    expect(sourceCode).toBe(`locator('body')`);
   }
   {
-    const locator = await (page.locator('aria-ref=f3e2') as any)._generateLocatorString();
-    expect(locator).toBe(`locator('iframe[name="2frames"]').contentFrame().locator('iframe[name="dos"]').contentFrame().getByText('Hi, I\\'m frame')`);
+    const { sourceCode } = await (page.locator('aria-ref=f3e2') as any)._resolveLocator();
+    expect(sourceCode).toBe(`locator('iframe[name="2frames"]').contentFrame().locator('iframe[name="dos"]').contentFrame().getByText('Hi, I\\'m frame')`);
   }
   {
     // Should tolerate .describe().
-    const locator = await (page.locator('aria-ref=f2e2').describe('foo bar') as any)._generateLocatorString();
-    expect(locator).toBe(`locator('iframe[name=\"2frames\"]').contentFrame().locator('iframe[name=\"uno\"]').contentFrame().getByText('Hi, I\\'m frame')`);
+    const { sourceCode } = await (page.locator('aria-ref=f2e2').describe('foo bar') as any)._resolveLocator();
+    expect(sourceCode).toBe(`locator('iframe[name=\"2frames\"]').contentFrame().locator('iframe[name=\"uno\"]').contentFrame().getByText('Hi, I\\'m frame')`);
   }
   {
-    const error = await (page.locator('aria-ref=e1000') as any)._generateLocatorString().catch(e => e);
-    expect(error.message).toContain(`No element matching locator('aria-ref=e1000')`);
+    const error = await (page.locator('aria-ref=e1000') as any)._resolveLocator().catch(e => e);
+    expect(error.message).toContain(`No element matching aria-ref=e1000`);
   }
 });