wait_for_selector
Pauses script execution until a specified CSS selector element appears, becomes visible, or disappears in the browser page, ensuring reliable automation timing.
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)Executes the wait_for_selector tool: gets the page, waits for the selector using Puppeteer page.waitForSelector with options, handles not found and timeout errors, returns success with found selector.
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.
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)Registers the wait_for_selector MCP tool with its 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))); } } );