wait_for_element
Wait for dynamic page elements to load before interacting with them, preventing errors when handling asynchronous content or page transitions.
Instructions
Wait for a specific element to appear on the page before continuing. Essential for handling dynamic content that loads asynchronously, page transitions, or elements that appear after clicking buttons. Prevents errors from trying to interact with elements that haven't loaded yet. Commonly used after login, navigation, or clicking buttons that trigger loading states.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| sessionId | Yes | Session ID obtained from initialize_session | |
| selector | Yes | CSS selector of the element to wait for (e.g., '.chat-container', '#message-input', '[data-loaded="true"]') | |
| timeout | No | Maximum time in milliseconds to wait before timing out. Increase for slow-loading pages (default: 30000) |
Implementation Reference
- src/tools/interaction.js:109-126 (handler)Core handler function that executes the wait_for_element tool logic using Playwright to wait for the specified selector.
export async function waitForElement(sessionId, selector, timeout = 30000) { const session = getSession(sessionId); const { page } = session; try { await page.waitForSelector(selector, { timeout }); return { success: true, sessionId, selector, message: `Element "${selector}" found`, currentUrl: page.url(), }; } catch (error) { throw new Error(`Element "${selector}" not found within ${timeout}ms`); } } - src/index.js:252-271 (schema)Input schema definition for the wait_for_element tool, specifying parameters and validation.
type: "object", properties: { sessionId: { type: "string", description: "Session ID obtained from initialize_session", }, selector: { type: "string", description: "CSS selector of the element to wait for (e.g., '.chat-container', '#message-input', '[data-loaded=\"true\"]')", }, timeout: { type: "number", description: "Maximum time in milliseconds to wait before timing out. Increase for slow-loading pages (default: 30000)", default: 30000, }, }, required: ["sessionId", "selector"], }, - src/index.js:247-272 (registration)Tool registration in the MCP server's ListTools response, defining name, description, and schema.
{ name: "wait_for_element", description: "Wait for a specific element to appear on the page before continuing. Essential for handling dynamic content that loads asynchronously, page transitions, or elements that appear after clicking buttons. Prevents errors from trying to interact with elements that haven't loaded yet. Commonly used after login, navigation, or clicking buttons that trigger loading states.", inputSchema: { type: "object", properties: { sessionId: { type: "string", description: "Session ID obtained from initialize_session", }, selector: { type: "string", description: "CSS selector of the element to wait for (e.g., '.chat-container', '#message-input', '[data-loaded=\"true\"]')", }, timeout: { type: "number", description: "Maximum time in milliseconds to wait before timing out. Increase for slow-loading pages (default: 30000)", default: 30000, }, }, required: ["sessionId", "selector"], }, }, - src/index.js:513-529 (registration)Dispatch handler in CallToolRequestSchema that validates parameters and calls the waitForElement function.
case "wait_for_element": { const { sessionId, selector, timeout = 30000 } = args; if (!sessionId) { throw new McpError( ErrorCode.InvalidParams, "sessionId parameter is required" ); } if (!selector) { throw new McpError( ErrorCode.InvalidParams, "selector parameter is required" ); } result = await waitForElement(sessionId, selector, timeout); break; } - src/tools/reverseEngineer.js:16-16 (helper)Re-export of waitForElement function from interaction.js to centralize imports.
export { clickElement, fillForm, waitForElement } from "./interaction.js";