Playwright 弹窗处理完全指南：alert / confirm / prompt 与 beforeunload 的拦截、接受与关闭

本文基于 Playwright 官方文档 dialogs.md 展开，讲解如何拦截并处理 Web 页面中四类弹窗——alert、confirm、prompt、beforeunload 确认框，以及如何断言 window.print() 触发的打印对话框；同时深入 playwright-core 源码，剖析 dialog 事件从浏览器到测试代码的完整调用链、"无弹窗监听器时自动关闭"的底层机制，以及 beforeunload 弹窗为何在关闭页面时需要特殊处理的原理，帮助你在自动化脚本与端到端测试中稳定地驾驭各种模态对话框。

概述：Playwright 支持的弹窗类型

Playwright 可以交互处理网页中的几类原生对话框，对应浏览器 Web API 中的 Window.alert、Window.confirm、Window.prompt，以及 beforeunload 确认事件。从源码看，服务端 dialog.ts 中定义的类型枚举与之一一对应：

// packages/playwright-core/src/server/dialog.ts
export type DialogType = 'alert' | 'beforeunload' | 'confirm' | 'prompt';

打印对话框（window.print）不属于上述模态框，它无法被浏览器协议直接拦截，Playwright 通过页面内注入脚本的方式实现断言，见打印对话框一节。

alert()、confirm()、prompt() 弹窗的处理

默认行为：如果没有任何 dialog 监听器，Playwright 会自动关闭（auto-dismiss）所有弹窗，测试无需关心。若需要显式接受或取消，必须在触发弹窗的动作之前注册 Page.dialog 事件监听器，然后在回调中调用 Dialog.accept() 或 Dialog.dismiss()：

// JavaScript
page.on('dialog', dialog => dialog.accept());
await page.getByRole('button').click();

// Java
page.onDialog(dialog -> dialog.accept());
page.getByRole(AriaRole.BUTTON).click();

# Python（async 与 sync API 写法相同）
page.on("dialog", lambda dialog: dialog.accept())
await page.get_by_role("button").click()   # async
page.get_by_role("button").click()         # sync

// .NET
Page.Dialog += async (_, dialog) =>
{
    await dialog.AcceptAsync();
};
await Page.GetByRole(AriaRole.Button).ClickAsync();

为什么监听器"必须"处理弹窗

文档中特别强调：Page.dialog 监听器必须处理这个 dialog，否则触发动作（如 Locator.click）会一直挂起。原因是浏览器中的弹窗是模态（modal）的——它会阻塞页面主线程的后续执行，直到对话框被响应。

这一点在源码中有直接印证。DialogManager.dialogDidOpen() 在弹窗打开时会做两件事：一是让当前页面上所有进行中的 JavaScript 求值进入"停滞"状态，二是逐个调用已注册的处理器：

// packages/playwright-core/src/server/dialog.ts
dialogDidOpen(dialog: Dialog) {
  // Any ongoing evaluations will be stalled until the dialog is closed.
  for (const frame of dialog.page().frameManager.frames())
    frame.invalidateNonStallingEvaluations(new EvaluationStalledError('JavaScript dialog interrupted evaluation'));
  this._openedDialogs.add(dialog);
  this._instrumentation.onDialog(dialog);

  let hasHandlers = true;
  for (const handler of this._dialogHandlers) {
    if (handler(dialog))
      hasHandlers = true;
  }
  if (!hasHandlers)
    dialog._close().then(() => {});
}

可以看到：只有当某个 handler 调用了 accept/dismiss 时，页面执行才会恢复；若监听器只是 console.log(dialog.message()) 而没有做任何处理，弹窗永远不会被关闭，点击操作也就永远阻塞。因此下面的写法是错误的（各语言等价，均以 JavaScript 为例，官方文档给出了五语言版本）：

// 错误示例：只打印消息，没有 accept/dismiss —— 点击将永久挂起
page.on('dialog', dialog => console.log(dialog.message()));
await page.getByRole('button').click(); // Will hang here

正确姿势：若只想记录消息，也应在回调中补上 dialog.dismiss()（或 accept()），例如 page.on('dialog', async d => { console.log(d.message()); await d.dismiss(); })。

源码剖析：无监听器时的自动关闭逻辑

"如果 Page.dialog 没有任何监听器，所有对话框都会被自动关闭"这一默认行为，同样来自 DialogManager：dialogDidOpen 遍历所有 handler，若没有任何 handler 认领（返回 false），就调用 dialog._close()。而 _close() 的语义与弹窗类型相关：

// packages/playwright-core/src/server/dialog.ts
async _close() {
  if (this._type === 'beforeunload')
    await this._accept();   // beforeunload 默认"接受"（即执行卸载）
  else
    await this._dismiss();  // alert/confirm/prompt 默认"取消"
}

这是一个值得注意的细节：beforeunload 弹窗在无监听器时的默认动作是 accept（放行关闭），其余三类则是 dismiss（取消）。

客户端侧的 Dialog 类 提供了 type()、message()、defaultValue() 三个只读属性和 accept(promptText?)、dismiss() 两个方法，所有语言绑定均基于该统一 API。其中 accept(promptText) 支持传入 prompt 弹窗的响应文本；dismiss() 内部还做了容错处理——若目标已关闭（isTargetClosedError）则静默返回，避免清理阶段抛出无意义异常：

// packages/playwright-core/src/client/dialog.ts
async accept(promptText: string | undefined) {
  await this._channel.accept({ promptText }, kNoTimeout);
}

async dismiss() {
  try {
    await this._channel.dismiss({}, kNoTimeout);
  } catch (e) {
    if (isTargetClosedError(e))
      return;
    throw e;
  }
}

另外从构造器注释可以看到一个边界情况：页面初始化早期弹出的 dialog 可能先于 Page 对象完成初始化，因此客户端 Dialog 的 _page 允许为 null，以保证这类弹窗依然能被监听并处理（见 client/dialog.ts）。

beforeunload 弹窗

当 Page.close() 以真值参数 runBeforeUnload: true 调用时，页面会执行其 beforeunload 处理函数。这是 Page.close() 唯一一种不等待页面真正关闭的场景——因为用户（或测试）可能最终选择"留在这个页面"，操作结束时页面仍可能处于打开状态。

可以通过 dialog 监听器自行处理 beforeunload 弹窗：

// JavaScript
page.on('dialog', async dialog => {
  assert(dialog.type() === 'beforeunload');
  await dialog.dismiss();
});
await page.close({ runBeforeUnload: true });

// Java
page.onDialog(dialog -> {
  assertEquals("beforeunload", dialog.type());
  dialog.dismiss();
});
page.close(new Page.CloseOptions().setRunBeforeUnload(true));

# Python（async 版本；sync 版本去掉 await 即可）
async def handle_dialog(dialog):
    assert dialog.type == 'beforeunload'
    await dialog.dismiss()

page.on('dialog', lambda: handle_dialog)
await page.close(run_before_unload=True)

// .NET
Page.Dialog += async (_, dialog) =>
{
    Assert.AreEqual("beforeunload", dialog.Type);
    await dialog.DismissAsync();
};
await Page.CloseAsync(new() { RunBeforeUnload = true });

源码剖析：dismiss beforeunload 等价于取消导航

在 Chromium 后端实现中，beforeunload 弹窗被拒绝（dismiss）时会触发一次"导航被取消"的内部流程。参见 crPage.ts 的 _onDialog：

_onDialog(event: Protocol.Page.javascriptDialogOpeningPayload) {
  if (!this._page.frameManager.frame(this._targetId))
    return; // Our frame/subtree may be gone already.
  this._page.browserContext.dialogManager.dialogDidOpen(new dialog.Dialog(
      this._page,
      event.type,
      event.message,
      async (accept: boolean, promptText?: string) => {
        // TODO: this should actually be a CDP event that notifies about a cancelled navigation attempt.
        if (this._isMainFrame() && event.type === 'beforeunload' && !accept)
          this._page.frameManager.frameAbortedNavigation(this._page.mainFrame()._id, 'navigation cancelled by beforeunload dialog');
        await this._client.send('Page.handleJavaScriptDialog', { accept, promptText });
      },
      event.defaultPrompt));
}

即：对主框架的 beforeunload 弹窗执行 dismiss 时，除了向浏览器发送 Page.handleJavaScriptDialog（accept=false）之外，还会额外通知 FrameManager 主框架的导航已被 beforeunload 取消，从而保证 Playwright 的导航/关闭状态机与浏览器真实行为保持一致（页面留在原地）。WebKit、Firefox、BiDi 等各后端均在各自实现（如 wkPage.ts、ffPage.ts、bidiPage.ts）中通过 dialogManager.dialogDidOpen(new dialog.Dialog(...)) 汇入同一套 DialogManager 处理逻辑。

runBeforeUnload 的关闭流程在 Page 服务端实现 中：close() 最终委托给浏览器后端的 closePage(runBeforeUnload)，例如 Chromium 实现 crPage.closePage 会根据该标志决定以何种方式发起关闭。服务端 DialogManager.closeBeforeUnloadDialogs() 还负责在必要时统一 dismiss 页面残留的 beforeunload 弹窗。测试仓库中 beforeunload.spec.ts 针对该行为覆盖了多种场景（配合资源页 beforeunload.html），可作为理解"关闭时是否执行卸载"各种分支的参考。

打印对话框

window.print() 触发的打印对话框无法像模态弹窗那样被直接拦截，官方推荐的做法是用 page.evaluate() 注入脚本，把 window.print 替换为"resolve 一个 Promise 的函数"，再通过 page.waitForFunction() 等待其被调用：

// JavaScript
await page.goto('<url>');

// 在按钮被点击前，页面已加载后，先注入这段脚本
await page.evaluate('(() => {window.waitForPrintDialog = new Promise(f => window.print = f);})()');
await page.getByText('Print it!').click();

// 等待打印对话框被触发
await page.waitForFunction('window.waitForPrintDialog');

// Java
page.navigate("<url>");

page.evaluate("(() => {window.waitForPrintDialog = new Promise(f => window.print = f);})()");
page.getByText("Print it!").click();

page.waitForFunction("window.waitForPrintDialog");

# Python（async 版本；sync 版本去掉 await）
await page.goto("<url>")

await page.evaluate("(() => {window.waitForPrintDialog = new Promise(f => window.print = f);})()")
await page.get_by_text("Print it!").click()

await page.wait_for_function("window.waitForPrintDialog")

// .NET
await Page.GotoAsync("<url>");

await Page.EvaluateAsync("(() => {window.waitForPrintDialog = new Promise(f => window.print = f);})()");
await Page.GetByText("Print it!").ClickAsync();

await Page.WaitForFunctionAsync("window.waitForPrintDialog");

这段代码的效果是：点击按钮后等待打印对话框被打开。注意时序要求：注入脚本必须在按钮点击之前、页面加载完成之后执行——一旦 window.print 被真实调用而 waitForPrintDialog 尚未就位，Promise 就永远不会被 resolve，waitForFunction 将一直等待。

小结与实践建议

• 默认即安全：不注册 Page.dialog 监听器时，alert/confirm/prompt 自动 dismiss、beforeunload 自动 accept（依据 DialogManager._close() 的实现），绝大多数测试无需处理弹窗。
• 监听器必须"闭环"：只要注册了 Page.dialog 监听器，就必须在其中 accept 或 dismiss，否则模态弹窗会阻塞主线程，点击等动作永久挂起。
• prompt 可传入响应文本：dialog.accept(promptText)（客户端 Dialog 将其透传给协议层）可用于断言/填写 prompt 弹窗的返回值。
• beforeunload 与 close 组合：只有 close({ runBeforeUnload: true }) 会执行卸载逻辑且不保证页面关闭；Chromium 下 dismiss 主框架 beforeunload 会同步触发"导航被取消"的内部处理（见 crPage.ts#L876-L894）。
• 打印对话框靠注入断言：用 Promise 替换 window.print + waitForFunction，并严格遵守"先注入、后触发"的时序。

以上行为在 Chromium、Firefox、WebKit（含 BiDi 路径）中由统一的 DialogManager 协调，各后端差异封装在各自的 _onDialog 实现内，因此文档中的 API 与示例在所有浏览器上表现一致。