wait_for_selector
Pauses script execution until a specified CSS selector appears or disappears on a webpage, enabling reliable automation of dynamic content interactions.
Instructions
Wait for an element matching the selector to appear in the page
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| selector | Yes | CSS selector for the element | |
| visible | No | Wait for element to be visible | |
| hidden | No | Wait for element to be hidden | |
| timeout | No | Timeout in milliseconds | |
| tabId | No | Tab ID to operate on (uses active tab if not specified) |
Implementation Reference
- src/tools/waiting.ts:24-59 (handler)The handler function that implements the core logic of the 'wait_for_selector' tool, using Puppeteer's page.waitForSelector with options for visibility, hidden state, and timeout handling.async ({ selector, visible, hidden, timeout, tabId }) => { const pageResult = await getPageForOperation(tabId); if (!pageResult.success) { return handleResult(pageResult); } const page = pageResult.data; const timeoutMs = timeout ?? getDefaultTimeout(); try { const element = await page.waitForSelector(selector, { timeout: timeoutMs, visible: visible ?? false, hidden: hidden ?? false, }); if (!element) { return handleResult(err(selectorNotFound(selector))); } return handleResult(ok({ found: true, selector, })); } catch (error) { if (error instanceof Error) { if (error.message.includes('waiting for selector')) { return handleResult(err(selectorNotFound(selector))); } if (error.message.includes('timeout')) { return handleResult(err(operationTimeout('wait_for_selector', timeoutMs))); } } return handleResult(err(normalizeError(error))); } }
- src/schemas.ts:128-134 (schema)Zod schema defining the input parameters for the wait_for_selector tool: selector, visible, hidden, timeout, and tabId.export const waitForSelectorSchema = z.object({ selector: selectorSchema, visible: z.boolean().optional().default(false).describe('Wait for element to be visible'), hidden: z.boolean().optional().default(false).describe('Wait for element to be hidden'), timeout: timeoutSchema, tabId: tabIdSchema, });
- src/tools/waiting.ts:20-60 (registration)Registration of the 'wait_for_selector' tool on the MCP server, specifying name, description, input schema, and handler function.server.tool( 'wait_for_selector', 'Wait for an element matching the selector to appear in the page', waitForSelectorSchema.shape, async ({ selector, visible, hidden, timeout, tabId }) => { const pageResult = await getPageForOperation(tabId); if (!pageResult.success) { return handleResult(pageResult); } const page = pageResult.data; const timeoutMs = timeout ?? getDefaultTimeout(); try { const element = await page.waitForSelector(selector, { timeout: timeoutMs, visible: visible ?? false, hidden: hidden ?? false, }); if (!element) { return handleResult(err(selectorNotFound(selector))); } return handleResult(ok({ found: true, selector, })); } catch (error) { if (error instanceof Error) { if (error.message.includes('waiting for selector')) { return handleResult(err(selectorNotFound(selector))); } if (error.message.includes('timeout')) { return handleResult(err(operationTimeout('wait_for_selector', timeoutMs))); } } return handleResult(err(normalizeError(error))); } } );
- src/server.ts:26-26 (registration)Top-level registration call that invokes registerWaitingTools, thereby registering the wait_for_selector tool among others.registerWaitingTools(server);
- src/errors.ts:203-203 (helper)Specific error helper usage for timeout in wait_for_selector context.return operationTimeout('wait_for_selector');