refactor: update waitForTextOnPage to accept a non-empty array of strings

Author: ashutoshpw

docs/tool-reference.md

@@ -193,7 +193,7 @@
 
 **Parameters:**
 
-- **text** (string | array of string) **(required)**: Text to appear on the page, or a non-empty list of texts. Resolves when any value appears.
+- **text** (array of string) **(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

@@ -826,20 +826,15 @@ export class McpContext implements Context {
   }
 
   waitForTextOnPage(
-    text: string | string[],
+    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 =>
-        texts.flatMap(value => [
+        text.flatMap(value => [
           frame.locator(`aria/${value}`),
           frame.locator(`text/${value}`),
         ]),

src/tools/ToolDefinition.ts

@@ -144,7 +144,7 @@ export type Context = Readonly<{
     options?: {timeout?: number},
   ): Promise<void>;
   waitForTextOnPage(
-    text: string | string[],
+    text: [string, ...string[]],
     timeout?: number,
   ): Promise<Element>;
   getDevToolsData(): Promise<DevToolsData>;

src/tools/snapshot.ts

@@ -50,9 +50,10 @@ export const waitFor = defineTool({
   },
   schema: {
     text: zod
-      .union([zod.string(), zod.array(zod.string()).nonempty()])
+      .tuple([zod.string()])
+      .rest(zod.string())
       .describe(
-        'Text to appear on the page, or a non-empty list of texts. Resolves when any value appears.',
+        'Non-empty list of texts. Resolves when any value appears on the page.',
       ),
     ...timeoutSchema,
   },
@@ -62,15 +63,9 @@ export const waitFor = defineTool({
       request.params.timeout,
     );
 
-    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.appendResponseLine(
+      `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,7 +39,7 @@ describe('snapshot', () => {
 
         assert.equal(
           response.responseLines[0],
-          'Element with text "Hello" found.',
+          'Element matching one of ["Hello"] found.',
         );
         assert.ok(response.includeSnapshot);
       });
@@ -107,7 +107,7 @@ describe('snapshot', () => {
         const handlePromise = waitFor.handler(
           {
             params: {
-              text: 'Hello World',
+              text: ['Hello World'],
             },
           },
           response,
@@ -122,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);
       });
@@ -138,7 +138,7 @@ describe('snapshot', () => {
         await waitFor.handler(
           {
             params: {
-              text: 'Header',
+              text: ['Header'],
             },
           },
           response,
@@ -147,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);
       });
@@ -165,7 +165,7 @@ describe('snapshot', () => {
         await waitFor.handler(
           {
             params: {
-              text: 'Hello iframe',
+              text: ['Hello iframe'],
             },
           },
           response,
@@ -174,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);
       });