企业官网建设流程全解析

如何用 waitForNetworkIdleTimeout 自定义 Midscene 网页自动化的网络空闲等待

【免费下载链接】midsceneGUI Agent for E2E Testing项目地址: https://gitcode.com/GitHub_Trending/mid/midscene

在 Midscene 驱动网页自动化时，点击、输入等操作之后页面往往还在发起请求，此时截图或断言可能抓到旧内容。Midscene 的应对策略是在每次交互或导航后自动等待网络空闲，等待超时时不报错、直接继续执行。如果你想让等待更久、更短，或者在页面有长连接/轮询导致空闲等待始终超时干脆关掉它，就需要用waitForNetworkIdleTimeout这个参数。本文覆盖三种配置入口：Agent 构造参数、Playwright 测试 fixture、YAML 脚本，并给出每种情况下如何从终端日志判断配置是否生效。

默认行为：先确认你现在处于哪种等待

Midscene 网页自动化有两类自动等待（见 Integrate with Playwright 文档 的 “Customize the network timeout” 一节）：

两个关键事实：

1. 等待超时不会导致脚本失败。文档原话是 “Nothing would happen if the waiting process is timeout”——它只影响执行节奏，不会把用例判为失败。
2. 参数设为0表示跳过对应的等待（API Reference 中对PlaywrightPageAgent/PuppeteerPageAgent的选项说明均为 “Set to0to skip the wait”）。

另外有一个实现层面的差别需要注意：在当前源码中，操作后的网络空闲等待只在 Puppeteer 路径真正执行，底层调用是page.waitForNetworkIdle({ idleTime: 200, concurrency: 2, timeout: this.waitForNetworkIdleTimeout })，其中并发数2来自 常量定义；而 Playwright 路径会打印一次警告后跳过实际等待：

[midscene:warning] waitForNetworkIdle is skipped for Playwright. Playwright does not provide an equivalent underlying capability for the intended post-action network idle behavior here.

见 base-page.ts。也就是说，如果你的用例跑在 Playwright 引擎上，waitForNetworkIdleTimeout会被接受，但操作后不会真正执行网络空闲等待（导航等待仍然生效，因为 Playwright 与 Puppeteer 共用waitForNavigation路径）。调整该参数后主要观察 Puppeteer 路径与 YAML 脚本的表现。

路径一：在 Agent 构造参数中配置（脚本直接集成）

适用于用脚本直接驱动PlaywrightAgent/PuppeteerPageAgent的场景。先安装依赖并配置模型环境变量（文档中的示例）：

# 依赖安装（文档命令） npm install @midscene/web playwright @playwright/test tsx --save-dev # 模型环境（文档示例，替换 your-api-key） export MIDSCENE_MODEL_BASE_URL="https://dashscope.aliyuncs.com/compatible-mode/v1" export MIDSCENE_MODEL_API_KEY="your-api-key" export MIDSCENE_MODEL_NAME="qwen3.7-plus" export MIDSCENE_MODEL_FAMILY="qwen3"

创建 Agent 时通过第二个参数传入选项，waitForNetworkIdleTimeout与waitForNavigationTimeout均为可选数值（毫秒）：

import { PlaywrightPageAgent } from '@midscene/web/playwright'; const agent = new PlaywrightPageAgent(page, { waitForNetworkIdleTimeout: <ms>, // 每次操作后等待网络空闲的上限，默认 2000；设为 0 跳过 waitForNavigationTimeout: <ms>, // 动作触发导航时的等待上限，默认 5000；设为 0 跳过 });

其中<ms>需要替换为你自己决定的毫秒数，比如沿用默认的2000、调大到能覆盖慢加载的数值，或0关闭等待；参数名与默认值以 API Reference 为准，文档没有给出其他推荐值，因此具体调多大需要结合你目标页面的加载速度自行确定。Puppeteer 侧等价写法是把page换成 Puppeteer 的Page并 import 自@midscene/web/puppeteer的PuppeteerPageAgent。

运行脚本后（文档给出的运行方式为npx tsx demo.ts），成功时终端输出Midscene - report file updated: /path/to/report/some_id.html，用浏览器打开即可查看报告——这是文档给出的通用运行验证方式。

路径二：Playwright 测试用例中通过 PlaywrightAiFixture 配置

如果你的 Midscene 能力挂在@playwright/test用例里，在扩展test实例的 fixture 里传参即可。PlaywrightAiFixture()接受所有共享的PlaywrightAgent选项，waitForNetworkIdleTimeout在 fixture 创建时直接写入（文档示例，代码中省略了与本主题无关的replanningCycleLimit）：

// ./e2e/fixture.ts import { test as base } from '@playwright/test'; import type { PlayWRightAiFixtureType } from '@midscene/web/playwright'; import { PlaywrightAiFixture } from '@midscene/web/playwright'; export const test = base.extend<PlayWRightAiFixtureType>( PlaywrightAiFixture({ // 可选，交互过程中等待网络空闲的超时时间，默认 2000ms；设为 0 禁用 waitForNetworkIdleTimeout: 2000, }), );

要禁用等待时把该值改为0即可，文档注释原话是 “default is 2000ms” / “设置为 0 则禁用超时”（中文版）。之后按常规方式运行用例验证：

npx playwright test ./e2e/ebay-search.spec.ts

运行成功后会输出Midscene - report file updated: ./current_cwd/midscene_run/report/some_id.html，打开报告文件即完成文档给出的验证步骤。

路径三：YAML 脚本中的web.page.waitForNetworkIdle

用 YAML 脚本驱动 Puppeteer 模式时，网络空闲策略放在page的waitForNetworkIdle小节下（Automate with Scripts in YAML 的共享选项）：

web: page: url: https://example.com waitForNetworkIdle: timeout: 2000 # 每次网络空闲等待的毫秒数，可选，默认 2000ms continueOnNetworkIdleError: true # 可选，默认 true

文档对两个子项的适用范围有明确区分：

• timeout同时作用于 YAML 中web.url的初始打开，以及aiTap、aiInput等后续操作后的等待；
• continueOnNetworkIdleError只作用于初始打开：初始打开等空闲超时时是否继续，默认true表示继续；后续操作时的等待即使超时也总是继续执行。

实现上可以进一步确认（agent-launcher.ts）：timeout小于等于0时初始打开不做任何空闲等待；等待超时且continueOnNetworkIdleError为false时抛出错误failed to wait for network idle: ...，否则打印警告后继续。

如何判断配置已经生效

Midscene 不会在成功时打印“已等待网络空闲 N ms”这类信息，验证只能看等待超时或被跳过时的终端日志：

• Puppeteer 路径（Agent 构造参数、YAML 脚本）：空闲等待超时后终端出现

  [midscene:warning] Waiting for the "network idle" has timed out, but Midscene will continue execution.

  说明等待确实执行了、但没在你设定的时限内等到空闲。如果你把timeout调大后这条警告消失，说明新时限已生效。

• YAML 脚本初始打开：出现failed to wait for network idle after <ms>ms, but the script will continue.时，日志中的毫秒数就是当前实际使用的超时值，可以核对是否与你配置的一致；若设置continueOnNetworkIdleError: false，此处会直接抛错而不是警告。

• Playwright 路径：只会看到一次waitForNetworkIdle is skipped for Playwright警告（见上文实现说明），这是当前版本 Playwright 引擎下的正常现象，不代表配置丢失。

边界与限制

• 无论怎么调大waitForNetworkIdleTimeout，等待超时都不会让自动化失败；如果你需要“初始打开必须等到空闲否则失败”的严格语义，只有 YAML 路径的continueOnNetworkIdleError: false能做到，且它只覆盖初始打开。
• 设为0是禁用而非报错，适合页面存在持续轮询、网络永远不空闲的环境。
• waitForNetworkIdleTimeout（操作后空闲等待）和waitForNavigationTimeout（导航等待，默认5000）是两个独立参数，文档把它们并列列出，改一个不影响另一个。

需要更多 Agent 参数细节时，继续查 API Reference 的 Web 一节 和 Integrate with Playwright 即可。

【免费下载链接】midsceneGUI Agent for E2E Testing项目地址: https://gitcode.com/GitHub_Trending/mid/midscene