page_waitElement

Instructions

Implementation Reference

• src/tools/page.ts:207-269 (handler)

  The `createWaitForElementTool` function creates the tool handler for 'page_waitElement'. It waits for a DOM element matching the given selector to appear on the page, polling with configurable timeout and retryInterval. Supports [index=N] syntax to target a specific element by index.

  function createWaitForElementTool(manager: WeappAutomatorManager): AnyTool {
    return {
      name: "page_waitElement",
      description: "等待指定选择器的元素出现在页面上。支持 [index=N] 语法选择第 N 个元素。增强版：增加了超时和重试间隔参数。",
      parameters: waitForElementParameters,
      execute: async (rawArgs, context: ToolContext) =>
        withUserErrorResult(async () => {
        const args = waitForElementParameters.parse(rawArgs ?? {});
        return manager.withPage<ContentResult>(
          context.log,
          { overrides: args.connection },
          async (page) => {
            if (typeof page.$$ !== "function") {
              throw new UserError("当前页面不支持查询元素数组。");
            }
  
            const startTime = Date.now();
            const timeout = args.timeout;
            const retryInterval = args.retryInterval;
  
            let selector = args.selector;
            let indexHint: number | undefined;
  
            const parsed = parseSelectorWithIndex(selector);
            if (parsed) {
              selector = parsed.baseSelector;
              indexHint = parsed.index;
            }
  
            while (Date.now() - startTime < timeout) {
              try {
                let elements = await page.$$(selector);
                if (!Array.isArray(elements) || elements.length === 0) {
                } else if (indexHint !== undefined) {
                  if (indexHint >= 0 && indexHint < elements.length) {
                    return toTextResult(formatJson({
                      selector: args.selector,
                      index: indexHint,
                      found: true,
                      waitTime: Date.now() - startTime,
                    }));
                  }
                } else {
                  return toTextResult(formatJson({
                    selector: args.selector,
                    found: true,
                    waitTime: Date.now() - startTime,
                  }));
                }
              } catch (error) {
                if (error instanceof UserError) {
                  throw error;
                }
              }
              await new Promise(resolve => setTimeout(resolve, retryInterval));
            }
  
            throw new UserError(`等待元素 "${args.selector}" 超时 (${timeout}ms)。`);
          }
        );
        }),
    };
  }

• src/tools/page.ts:31-35 (schema)

  The `waitForElementParameters` schema defines the input validation for the page_waitElement tool: selector (string), timeout (positive int, default 5000ms), retryInterval (positive int, default 200ms).

  const waitForElementParameters = connectionContainerSchema.extend({
    selector: z.string().trim().min(1),
    timeout: z.coerce.number().int().positive().optional().default(5000),
    retryInterval: z.coerce.number().int().positive().optional().default(200),
  });

• src/tools/page.ts:52-62 (registration)

  The `createPageTools` function registers all page tools, including `createWaitForElementTool`, into an array returned to the caller. This is where page_waitElement is aggregated.

  export function createPageTools(manager: WeappAutomatorManager): AnyTool[] {
    return [
      createGetElementTool(manager),
      createGetElementsTool(manager),
      createWaitForElementTool(manager),
      createWaitForTimeoutTool(manager),
      createGetPageDataTool(manager),
      createSetPageDataTool(manager),
      createCallPageMethodTool(manager),
    ];
  }

• src/tools.ts:1-13 (registration)

  The top-level `createTools` function spreads `createPageTools` results (which includes page_waitElement) into the final tool array.

  import { createApplicationTools } from "./tools/application.js";
  import { AnyTool } from "./tools/common.js";
  import { createElementTools } from "./tools/element.js";
  import { createPageTools } from "./tools/page.js";
  import { WeappAutomatorManager } from "./weappClient.js";
  
  export function createTools(manager: WeappAutomatorManager): AnyTool[] {
    return [
      ...createApplicationTools(manager),
      ...createPageTools(manager),
      ...createElementTools(manager),
    ];
  }

• src/tools/common.ts:286-296 (helper)

  The `parseSelectorWithIndex` helper is used by the page_waitElement handler to parse the [index=N] suffix from selectors.

  export function parseSelectorWithIndex(selector: string): { baseSelector: string; index: number } | null {
    // 匹配 selector[index=N] 语法
    const match = selector.match(/^(.+?)\[index=(\d+)\]$/);
    if (match) {
      return {
        baseSelector: match[1],
        index: parseInt(match[2], 10),
      };
    }
    return null;
  }