wait_for_navigation

Wait for page navigation to complete before proceeding with browser automation tasks. Specify timeout and wait conditions for reliable script execution.

Instructions

Wait for the page to navigate to a new URL

Input Schema

TableJSON Schema

Name	Required	Description
`waitUntil`	No
`timeout`	No	Timeout in milliseconds
`tabId`	No	Tab ID to operate on (uses active tab if not specified)

Implementation Reference

src/tools/waiting.ts:67-92 (handler)

The handler function that executes the wait_for_navigation tool. It retrieves the page, waits for navigation with specified options, and returns the new URL and title or handles errors like timeout.

async ({ waitUntil, timeout, tabId }) => {
  const pageResult = await getPageForOperation(tabId);
  if (!pageResult.success) {
    return handleResult(pageResult);
  }

  const page = pageResult.data;
  const timeoutMs = timeout ?? getDefaultTimeout();

  try {
    await page.waitForNavigation({
      waitUntil: (waitUntil ?? 'load') as WaitUntilOption,
      timeout: timeoutMs,
    });

    return handleResult(ok({
      url: page.url(),
      title: await page.title(),
    }));
  } catch (error) {
    if (error instanceof Error && error.message.includes('timeout')) {
      return handleResult(err(operationTimeout('wait_for_navigation', timeoutMs)));
    }
    return handleResult(err(normalizeError(error)));
  }
}

src/schemas.ts:136-140 (schema)
Zod schema defining the input parameters for the wait_for_navigation tool: waitUntil, timeout (optional), tabId (optional).
```
export const waitForNavigationSchema = z.object({
  waitUntil: waitUntilSchema,
  timeout: timeoutSchema,
  tabId: tabIdSchema,
});
```

src/tools/waiting.ts:63-93 (registration)

Registers the wait_for_navigation tool on the MCP server with description, schema, and handler function.

server.tool(
  'wait_for_navigation',
  'Wait for the page to navigate to a new URL',
  waitForNavigationSchema.shape,
  async ({ waitUntil, timeout, tabId }) => {
    const pageResult = await getPageForOperation(tabId);
    if (!pageResult.success) {
      return handleResult(pageResult);
    }

    const page = pageResult.data;
    const timeoutMs = timeout ?? getDefaultTimeout();

    try {
      await page.waitForNavigation({
        waitUntil: (waitUntil ?? 'load') as WaitUntilOption,
        timeout: timeoutMs,
      });

      return handleResult(ok({
        url: page.url(),
        title: await page.title(),
      }));
    } catch (error) {
      if (error instanceof Error && error.message.includes('timeout')) {
        return handleResult(err(operationTimeout('wait_for_navigation', timeoutMs)));
      }
      return handleResult(err(normalizeError(error)));
    }
  }
);

Puppeteer MCP Server