chore: add expect text/value into perform (microsoft#38520)

Author: pavelfeldman

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

@@ -94,6 +94,10 @@ export function serializeValue(value: any, handleSerializer: (value: any) => Han
   return innerSerializeValue(value, handleSerializer, { lastId: 0, visited: new Map() }, []);
 }
 
+export function serializePlainValue(arg: any): SerializedValue {
+  return serializeValue(arg, value => ({ fallThrough: value }));
+}
+
 function innerSerializeValue(value: any, handleSerializer: (value: any) => HandleOrValue, visitorInfo: VisitorInfo, accessChain: Array<string | number>): SerializedValue {
   const handle = handleSerializer(value);
   if ('fallThrough' in handle)

packages/playwright-core/src/server/agent/DEPS.list

@@ -2,5 +2,8 @@
 ../browserContext.ts
 ../page.ts
 ../progress.ts
+../utils/expectUtils.ts
 ../../mcpBundle.ts
+../../protocol/
 ../../utilsBundle.ts
+../../utils/isomorphic/

packages/playwright-core/src/server/agent/actionRunner.ts

@@ -14,10 +14,15 @@
  * limitations under the License.
  */
 
+import { serializeExpectedTextValues } from '../utils/expectUtils';
+import { serializePlainValue } from '../../protocol/serializers';
+
 import type * as actions from './actions';
+import type * as channels from '@protocol/channels';
 import type { Page } from '../page';
 import type { Progress } from '../progress';
 import type { NameValue } from '@protocol/channels';
+import type { ExpectResult } from '../frames';
 
 export async function runAction(progress: Progress, page: Page, action: actions.Action, secrets: NameValue[]) {
   const frame = page.mainFrame();
@@ -57,7 +62,35 @@ export async function runAction(progress: Progress, page: Page, action: actions.
       else
         await frame.uncheck(progress, action.selector, { ...strictTrue });
       break;
+    case 'expectVisible': {
+      const result = await frame.expect(progress, action.selector, { expression: 'to.be.visible', isNot: false }, 5000);
+      if (result.errorMessage)
+        throw new Error(result.errorMessage);
+      break;
+    }
+    case 'expectValue': {
+      let result: ExpectResult;
+      if (action.type === 'textbox' || action.type === 'combobox' || action.type === 'slider') {
+        const expectedText = serializeExpectedTextValues([action.value]);
+        result = await frame.expect(progress, action.selector, { expression: 'to.have.value', expectedText, isNot: false }, 5000);
+      } else if (action.type === 'checkbox' || action.type === 'radio') {
+        const expectedValue = serializeArgument({ checked: true });
+        result = await frame.expect(progress, action.selector, { expression: 'to.be.checked', expectedValue, isNot: false }, 5000);
+      } else {
+        throw new Error(`Unsupported element type: ${action.type}`);
+      }
+      if (result.errorMessage)
+        throw new Error(result.errorMessage);
+      break;
+    }
   }
 }
 
+export function serializeArgument(arg: any): channels.SerializedArgument {
+  return {
+    value: serializePlainValue(arg),
+    handles: []
+  };
+}
+
 const strictTrue =  { strict: true };

packages/playwright-core/src/server/agent/actions.ts

@@ -65,4 +65,16 @@ export type SetChecked = {
   checked: boolean;
 };
 
-export type Action = ClickAction | DragAction | HoverAction | SelectOptionAction | PressAction | PressSequentiallyAction | FillAction | SetChecked;
+export type ExpectVisible = {
+  method: 'expectVisible';
+  selector: string;
+};
+
+export type ExpectValue = {
+  method: 'expectValue';
+  selector: string;
+  type: 'textbox' | 'checkbox' | 'radio' | 'combobox' | 'slider';
+  value: string;
+};
+
+export type Action = ClickAction | DragAction | HoverAction | SelectOptionAction | PressAction | PressSequentiallyAction | FillAction | SetChecked | ExpectVisible | ExpectValue;

packages/playwright-core/src/server/agent/context.ts

@@ -43,13 +43,17 @@ export class Context {
   }
 
   async runActionsAndWait(action: actions.Action[]) {
-    await this.waitForCompletion(async () => {
-      for (const a of action) {
-        await runAction(this.progress, this.page, a, this.options?.secrets ?? []);
-        this.actions.push(a);
-      }
-    });
-    return await this.snapshotResult();
+    try {
+      await this.waitForCompletion(async () => {
+        for (const a of action) {
+          await runAction(this.progress, this.page, a, this.options?.secrets ?? []);
+          this.actions.push(a);
+        }
+      });
+      return await this.snapshotResult();
+    } catch (e) {
+      return await this.snapshotResult(e);
+    }
   }
 
   async waitForCompletion<R>(callback: () => Promise<R>): Promise<R> {
@@ -88,18 +92,29 @@ export class Context {
     return result;
   }
 
-  async snapshotResult(): Promise<loopTypes.ToolResult> {
+  async snapshotResult(error?: Error): Promise<loopTypes.ToolResult> {
     let { full } = await this.page.snapshotForAI(this.progress);
     full = this._redactText(full);
 
-    const text = [`# Page snapshot\n${full}`];
+    const text: string[] = [];
+    if (error)
+      text.push(`# Error\n${error.message}`);
+    else
+      text.push(`# Success`);
+
+    text.push(`# Page snapshot\n${full}`);
 
     return {
       _meta: {
         'dev.lowire/state': {
           'Page snapshot': full
         },
+        'dev.lowire/history': error ? [{
+          category: 'error',
+          content: error.message,
+        }] : [],
       },
+      isError: !!error,
       content: [{ type: 'text', text: text.join('\n\n') }],
     };
   }

packages/playwright-core/src/server/agent/tools.ts

@@ -15,6 +15,7 @@
  */
 
 import { z } from '../../mcpBundle';
+import { getByRoleSelector, getByTextSelector } from '../../utils/isomorphic/locatorUtils';
 
 import type zod from 'zod';
 import type * as loopTypes from '@lowire/loop';
@@ -253,6 +254,67 @@ const fillForm = defineTool({
   },
 });
 
+const expectVisible = defineTool({
+  schema: {
+    name: 'browser_expect_visible',
+    title: 'Expect element visible',
+    description: 'Expect element is visible on the page',
+    inputSchema: baseSchema.extend({
+      role: z.string().describe('ROLE of the element. Can be found in the snapshot like this: \`- {ROLE} "Accessible Name":\`'),
+      accessibleName: z.string().describe('ACCESSIBLE_NAME of the element. Can be found in the snapshot like this: \`- role "{ACCESSIBLE_NAME}"\`'),
+    }),
+  },
+
+  handle: async (context, params) => {
+    return await context.runActionAndWait({
+      method: 'expectVisible',
+      selector: getByRoleSelector(params.role, { name: params.accessibleName }),
+    });
+  },
+});
+
+const expectVisibleText = defineTool({
+  schema: {
+    name: 'browser_expect_visible_text',
+    title: 'Expect text visible',
+    description: `Expect text is visible on the page. Prefer ${expectVisible.schema.name} if possible.`,
+    inputSchema: baseSchema.extend({
+      text: z.string().describe('TEXT to expect. Can be found in the snapshot like this: \`- role "Accessible Name": {TEXT}\` or like this: \`- text: {TEXT}\`'),
+    }),
+  },
+
+  handle: async (context, params) => {
+    return await context.runActionAndWait({
+      method: 'expectVisible',
+      selector: getByTextSelector(params.text),
+    });
+  },
+});
+
+const expectValue = defineTool({
+  schema: {
+    name: 'browser_expect_value',
+    title: 'Expect value',
+    description: 'Expect element value',
+    inputSchema: baseSchema.extend({
+      type: z.enum(['textbox', 'checkbox', 'radio', 'combobox', 'slider']).describe('Type of the element'),
+      element: z.string().describe('Human-readable element description'),
+      ref: z.string().describe('Exact target element reference from the page snapshot'),
+      value: z.string().describe('Value to expect. For checkbox, use "true" or "false".'),
+    }),
+  },
+
+  handle: async (context, params) => {
+    const [selector] = await context.refSelectors([{ ref: params.ref, element: params.element }]);
+    return await context.runActionAndWait({
+      method: 'expectValue',
+      selector,
+      type: params.type,
+      value: params.value,
+    });
+  },
+});
+
 export default [
   snapshot,
   click,
@@ -262,4 +324,7 @@ export default [
   pressKey,
   type,
   fillForm,
+  expectVisible,
+  expectVisibleText,
+  expectValue,
 ];

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

@@ -90,7 +90,7 @@ export class NavigationAbortedError extends Error {
   }
 }
 
-type ExpectResult = { matches: boolean, received?: any, log?: string[], timedOut?: boolean, errorMessage?: string };
+export type ExpectResult = { matches: boolean, received?: any, log?: string[], timedOut?: boolean, errorMessage?: string };
 
 const kDummyFrameId = '<dummy>';
 

tests/library/perform-task.spec.ts

@@ -64,3 +64,23 @@ test.skip('extract task', async ({ page }) => {
     }).array()
   })));
 });
+
+test('page.perform expect value', async ({ page, server }) => {
+  await page.setContent(`
+    <script>
+    function onInput(event) {
+      if (!event.target.value.match(/^[^@]+@[^@]+$/))
+        document.getElementById('error').style.display = 'block';
+      else
+        document.getElementById('error').style.display = 'none';
+    }
+    </script>
+    <input type="email" name="email" placeholder="Email Address" oninput="onInput(event);"/>
+    <div id="error" style="color: red; display: none;">Error: Invalid email address</div>
+  `);
+  await page.perform(`
+    - Enter "bogus" into the email field
+    - Check that the value is in fact "bogus"
+    - Check that the error message is displayed
+  `);
+});

tests/library/perform-task.spec.ts-cache.json

@@ -43,5 +43,25 @@
         "text": "94043"
       }
     ]
+  },
+  "\n    - Enter \"bogus\" into the email field\n    - Check that the value is in fact \"bogus\"\n    - Check that the error message is displayed\n  ": {
+    "timestamp": 1765416520724,
+    "actions": [
+      {
+        "method": "fill",
+        "selector": "internal:role=textbox[name=\"Email Address\"i]",
+        "text": "bogus"
+      },
+      {
+        "method": "expectValue",
+        "selector": "internal:role=textbox[name=\"Email Address\"i]",
+        "type": "textbox",
+        "value": "bogus"
+      },
+      {
+        "method": "expectVisible",
+        "selector": "internal:text=\"Error: Invalid email address\"i"
+      }
+    ]
   }
 }