fix: support any-match text arrays in wait_for

Implements wait_for text as string | string[] and resolves when any candidate appears.

Adds schema/tests/docs updates for #916.

Author: ashutoshpw

docs/tool-reference.md

@@ -191,11 +191,11 @@
 
 ### `wait_for`
 
-**Description:** Wait for the specified text to appear on the selected page.
+**Description:** Wait for the specified text to appear on the selected page. You can provide a single text value or a list of texts; the tool resolves when any text appears.
 
 **Parameters:**
 
-- **text** (string) **(required)**: Text to appear on the page
+- **text** (string | array of string) **(required)**: Text to appear on the page, or a non-empty list of texts. Resolves when any value appears.
 - **timeout** (integer) _(optional)_: Maximum wait time in milliseconds. If set to 0, the default timeout will be used.
 
 ---

scripts/generate-docs.ts

@@ -74,6 +74,7 @@ interface ZodDef {
   checks?: ZodCheck[];
   values?: string[];
   type?: ZodSchema;
+  options?: ZodSchema[];
   innerType?: ZodSchema;
   schema?: ZodSchema;
   defaultValue?: () => unknown;
@@ -294,6 +295,22 @@ function getZodTypeInfo(schema: ZodSchema): TypeInfo {
         result.items = getZodTypeInfo(def.type);
       }
       break;
+    case 'ZodUnion':
+      if (def.options?.length) {
+        result.type = def.options
+          .map(option => {
+            const optionInfo = getZodTypeInfo(option);
+            if (optionInfo.type === 'array') {
+              const itemType = optionInfo.items?.type ?? 'unknown';
+              return `array of ${itemType}`;
+            }
+            return optionInfo.type;
+          })
+          .join(' | ');
+      } else {
+        result.type = 'unknown';
+      }
+      break;
     default:
       result.type = 'unknown';
   }

src/McpContext.ts

@@ -881,15 +881,25 @@ export class McpContext implements Context {
     return this.#networkCollector.getIdForResource(request);
   }
 
-  waitForTextOnPage(text: string, timeout?: number): Promise<Element> {
+  waitForTextOnPage(
+    text: string | string[],
+    timeout?: number,
+  ): Promise<Element> {
     const page = this.getSelectedPage();
     const frames = page.frames();
+    const texts = Array.isArray(text) ? text : [text];
+
+    if (texts.length === 0) {
+      throw new Error('At least one text value is required.');
+    }
 
     let locator = this.#locatorClass.race(
-      frames.flatMap(frame => [
-        frame.locator(`aria/${text}`),
-        frame.locator(`text/${text}`),
-      ]),
+      frames.flatMap(frame =>
+        texts.flatMap(value => [
+          frame.locator(`aria/${value}`),
+          frame.locator(`text/${value}`),
+        ]),
+      ),
     );
 
     if (timeout) {

src/tools/ToolDefinition.ts

@@ -144,7 +144,10 @@ export type Context = Readonly<{
     action: () => Promise<unknown>,
     options?: {timeout?: number},
   ): Promise<void>;
-  waitForTextOnPage(text: string, timeout?: number): Promise<Element>;
+  waitForTextOnPage(
+    text: string | string[],
+    timeout?: number,
+  ): Promise<Element>;
   getDevToolsData(): Promise<DevToolsData>;
   /**
    * Returns a reqid for a cdpRequestId.

src/tools/snapshot.ts

@@ -43,13 +43,17 @@ in the DevTools Elements panel (if any).`,
 
 export const waitFor = defineTool({
   name: 'wait_for',
-  description: `Wait for the specified text to appear on the selected page.`,
+  description: `Wait for the specified text to appear on the selected page. You can provide a single text value or a list of texts; the tool resolves when any text appears.`,
   annotations: {
     category: ToolCategory.NAVIGATION,
     readOnlyHint: true,
   },
   schema: {
-    text: zod.string().describe('Text to appear on the page'),
+    text: zod
+      .union([zod.string(), zod.array(zod.string()).nonempty()])
+      .describe(
+        'Text to appear on the page, or a non-empty list of texts. Resolves when any value appears.',
+      ),
     ...timeoutSchema,
   },
   handler: async (request, response, context) => {
@@ -58,9 +62,15 @@ export const waitFor = defineTool({
       request.params.timeout,
     );
 
-    response.appendResponseLine(
-      `Element with text "${request.params.text}" found.`,
-    );
+    if (Array.isArray(request.params.text)) {
+      response.appendResponseLine(
+        `Element matching one of ${JSON.stringify(request.params.text)} found.`,
+      );
+    } else {
+      response.appendResponseLine(
+        `Element with text "${request.params.text}" found.`,
+      );
+    }
 
     response.includeSnapshot();
   },

tests/tools/snapshot.test.ts

@@ -20,6 +20,15 @@ describe('snapshot', () => {
     });
   });
   describe('browser_wait_for', () => {
+    it('accepts string or non-empty array text input', () => {
+      assert.equal(waitFor.schema.text.safeParse('Hello').success, true);
+      assert.equal(
+        waitFor.schema.text.safeParse(['Hello', 'World']).success,
+        true,
+      );
+      assert.equal(waitFor.schema.text.safeParse([]).success, false);
+    });
+
     it('should work', async () => {
       await withMcpContext(async (response, context) => {
         const page = context.getSelectedPage();
@@ -44,6 +53,62 @@ describe('snapshot', () => {
         assert.ok(response.includeSnapshot);
       });
     });
+
+    it('should work with any-match array', async () => {
+      await withMcpContext(async (response, context) => {
+        const page = context.getSelectedPage();
+
+        await page.setContent(
+          html`<main><span>Status</span><div>Error</div></main>`,
+        );
+        await waitFor.handler(
+          {
+            params: {
+              text: ['Complete', 'Error'],
+            },
+          },
+          response,
+          context,
+        );
+
+        assert.equal(
+          response.responseLines[0],
+          'Element matching one of ["Complete","Error"] found.',
+        );
+        assert.ok(response.includeSnapshot);
+      });
+    });
+
+    it('should work with any-match array when element shows up later', async () => {
+      await withMcpContext(async (response, context) => {
+        const page = context.getSelectedPage();
+
+        const handlePromise = waitFor.handler(
+          {
+            params: {
+              text: ['Complete', 'Error'],
+            },
+          },
+          response,
+          context,
+        );
+
+        await page.setContent(
+          html`<main
+            ><span>Hello</span><span> </span><div>Complete</div></main
+          >`,
+        );
+
+        await handlePromise;
+
+        assert.equal(
+          response.responseLines[0],
+          'Element matching one of ["Complete","Error"] found.',
+        );
+        assert.ok(response.includeSnapshot);
+      });
+    });
+
     it('should work with element that show up later', async () => {
       await withMcpContext(async (response, context) => {
         const page = context.getSelectedPage();