feat: support any-match text arrays in wait_for (#1011)

## Summary

Enhances wait_for to support waiting on multiple possible texts and
resolve when any one appears.

This addresses long-running flows that can end in different UI outcomes
(for example, "Complete" or "Error"), avoiding unnecessary 300s waits
when only one expected string is provided.

Closes #916.

## Tool Update

### wait_for

Waits for text on the selected page, now with any-match support.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| text | string \| string[] | yes | A single text or a non-empty list of
texts. Resolves when any value appears. |
| timeout | integer | no | Maximum wait in ms (0 keeps default
behavior). |

---

## Design / Implementation

- Kept backward compatibility: existing single-string text calls
continue to work unchanged.
- Added schema support for string | string[] with non-empty array
validation.
- Updated context API to accept string | string[].
- Matching logic now normalizes to an array and races all candidates
across all frames using both:
    - aria/<text>
    - text/<text>
- Added clearer response output for array input:
    - Element matching one of ["Complete","Error"] found.
- Updated generated tool docs for the new wait_for contract.
- Improved docs generation to render ZodUnion types (so union params are
documented correctly, not as unknown).
  
---

## Tests

Added/updated coverage for:

- Schema acceptance of:
    - single string
    - non-empty string array
    - rejection of empty array
- Any-match array success case
- Any-match array when matching text appears later (async/delayed
content)
- Existing wait_for behavior remains covered for single-text usage

Executed relevant test suites:

- tests/tools/snapshot.test.ts
- tests/McpContext.test.ts
- tests/index.test.ts 

Confirmation after the change applied:
https://opncd.ai/share/8m6I4r4a

Author: ashutoshpw

docs/tool-reference.md

@@ -1,6 +1,6 @@
 <!-- AUTO GENERATED DO NOT EDIT - run 'npm run docs' to update-->
 
-# Chrome DevTools MCP Tool Reference (~6885 cl100k_base tokens)
+# Chrome DevTools MCP Tool Reference (~6916 cl100k_base tokens)
 
 - **[Input automation](#input-automation)** (8 tools)
   - [`click`](#click)
@@ -195,7 +195,7 @@
 
 **Parameters:**
 
-- **text** (string) **(required)**: Text to appear on the page
+- **text** (array) **(required)**: Non-empty list of texts. Resolves when any value appears on the page.
 - **timeout** (integer) _(optional)_: Maximum wait time in milliseconds. If set to 0, the default timeout will be used.
 
 ---

src/McpContext.ts

@@ -881,15 +881,17 @@ export class McpContext implements Context {
     return this.#networkCollector.getIdForResource(request);
   }
 
-  waitForTextOnPage(text: string, timeout?: number): Promise<Element> {
+  waitForTextOnPage(text: string[], timeout?: number): Promise<Element> {
     const page = this.getSelectedPage();
     const frames = page.frames();
 
     let locator = this.#locatorClass.race(
-      frames.flatMap(frame => [
-        frame.locator(`aria/${text}`),
-        frame.locator(`text/${text}`),
-      ]),
+      frames.flatMap(frame =>
+        text.flatMap(value => [
+          frame.locator(`aria/${value}`),
+          frame.locator(`text/${value}`),
+        ]),
+      ),
     );
 
     if (timeout) {

src/tools/ToolDefinition.ts

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

src/tools/snapshot.ts

@@ -49,7 +49,12 @@ export const waitFor = defineTool({
     readOnlyHint: true,
   },
   schema: {
-    text: zod.string().describe('Text to appear on the page'),
+    text: zod
+      .array(zod.string())
+      .min(1)
+      .describe(
+        'Non-empty list of texts. Resolves when any value appears on the page.',
+      ),
     ...timeoutSchema,
   },
   handler: async (request, response, context) => {
@@ -59,7 +64,7 @@ export const waitFor = defineTool({
     );
 
     response.appendResponseLine(
-      `Element with text "${request.params.text}" found.`,
+      `Element matching one of ${JSON.stringify(request.params.text)} found.`,
     );
 
     response.includeSnapshot();

tests/tools/snapshot.test.ts

@@ -30,7 +30,7 @@ describe('snapshot', () => {
         await waitFor.handler(
           {
             params: {
-              text: 'Hello',
+              text: ['Hello'],
             },
           },
           response,
@@ -39,19 +39,75 @@ describe('snapshot', () => {
 
         assert.equal(
           response.responseLines[0],
-          'Element with text "Hello" found.',
+          'Element matching one of ["Hello"] found.',
         );
         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();
 
         const handlePromise = waitFor.handler(
           {
             params: {
-              text: 'Hello World',
+              text: ['Hello World'],
             },
           },
           response,
@@ -66,7 +122,7 @@ describe('snapshot', () => {
 
         assert.equal(
           response.responseLines[0],
-          'Element with text "Hello World" found.',
+          'Element matching one of ["Hello World"] found.',
         );
         assert.ok(response.includeSnapshot);
       });
@@ -82,7 +138,7 @@ describe('snapshot', () => {
         await waitFor.handler(
           {
             params: {
-              text: 'Header',
+              text: ['Header'],
             },
           },
           response,
@@ -91,7 +147,7 @@ describe('snapshot', () => {
 
         assert.equal(
           response.responseLines[0],
-          'Element with text "Header" found.',
+          'Element matching one of ["Header"] found.',
         );
         assert.ok(response.includeSnapshot);
       });
@@ -109,7 +165,7 @@ describe('snapshot', () => {
         await waitFor.handler(
           {
             params: {
-              text: 'Hello iframe',
+              text: ['Hello iframe'],
             },
           },
           response,
@@ -118,7 +174,7 @@ describe('snapshot', () => {
 
         assert.equal(
           response.responseLines[0],
-          'Element with text "Hello iframe" found.',
+          'Element matching one of ["Hello iframe"] found.',
         );
         assert.ok(response.includeSnapshot);
       });