Playwright FileChooser API 深度解析：跨浏览器文件上传测试的事件驱动模式

在 Web 自动化测试中，<input type="file"> 是最难自动化的一类元素：点击它弹出的是操作系统级的文件选择对话框，传统脚本无法操控。Playwright 的 FileChooser 类（自 v1.8 引入）正是为解决这个问题而设计的核心对象——它通过页面事件将"点击上传控件"与"设置文件"解耦，让测试无需打开任何对话框即可向文件输入框注入文件。读完本文，你将掌握 FileChooser 在 JS/Java/Python/C# 四种语言下的完整用法、element / isMultiple / page / setFiles 各成员的参数语义与默认值，以及从源码层面理解该事件从浏览器内到客户端对象的分发链路，能够编写可复现、可维护的文件上传测试。

事件驱动模型：FileChooser 从哪里来

FileChooser 对象不是主动查询出来的，而是由页面向外派发的事件产物。文档原文指出："FileChooser objects are dispatched by the page in the [event: Page.fileChooser] event"。这意味着正确的使用范式是"先挂起等待，再触发点击"，而不是点击之后再去寻找对象——因为文件选择框的生命周期极短，点击后若没有等待者，事件会直接丢失。

以 JavaScript 为例，这是官方文档给出的标准写法（注意 waitForEvent 前没有 await）：

// Start waiting for file chooser before clicking. Note no await.
const fileChooserPromise = page.waitForEvent('filechooser');
await page.getByText('Upload file').click();
const fileChooser = await fileChooserPromise;
await fileChooser.setFiles(path.join(__dirname, 'myfile.pdf'));

其他三种语言的等价实现，Playwright 都提供了语法糖把"等待 + 动作 + 取结果"三步折叠成一个调用：

// Java：waitForFileChooser 接收一个要执行的 Runnable
FileChooser fileChooser = page.waitForFileChooser(() -> page.getByText("Upload file").click());
fileChooser.setFiles(Paths.get("myfile.pdf"));

# Python 异步 API
async with page.expect_file_chooser() as fc_info:
    await page.get_by_text("Upload file").click()
file_chooser = await fc_info.value
await file_chooser.set_files("myfile.pdf")

# Python 同步 API
with page.expect_file_chooser() as fc_info:
    page.get_by_text("Upload file").click()
file_chooser = fc_info.value
file_chooser.set_files("myfile.pdf")

// C#：RunAndWaitForFileChooserAsync 在 Task 中同时完成等待与动作
var fileChooser = await page.RunAndWaitForFileChooserAsync(async () =>
{
    await page.GetByText("Upload file").ClickAsync();
});
await fileChooser.SetFilesAsync("temp.txt");

从源码结构看，这套事件机制的实现链路是清晰的：在客户端 Page 事件注册处 中，当底层通道收到 fileChooser 消息时，会立即构造一个 FileChooser 实例并发出 page 的 filechooser 事件：

this._channel.on('fileChooser', ({ element, isMultiple }) =>
  this.emit(Events.Page.FileChooser, new FileChooser(this, ElementHandle.from(element), isMultiple)));

也就是说，FileChooser 实例在构造时就绑定了三样东西：所属 Page、<input type="file"> 的 ElementHandle、以及是否支持多文件（isMultiple）。这三个构造函数参数也正是下文三个只读属性的来源。

三个实例属性：element、isMultiple、page

FileChooser 暴露的实例方法只有三个，全部是只读查询，文档标注均自 v1.8 可用：

method: FileChooser.element

• 返回类型：ElementHandle
• 文档描述："Returns input element associated with this file chooser."（返回与该文件选择器关联的 input 元素句柄。）

method: FileChooser.isMultiple

• 返回类型：boolean
• 文档描述："Returns whether this file chooser accepts multiple files."（返回该文件选择器是否接受多个文件。）

method: FileChooser.page

• 返回类型：Page
• 文档描述："Returns page this file chooser belongs to."（返回该文件选择器所属的页面。）

这三个属性在客户端源码 packages/playwright-core/src/client/fileChooser.ts 中是一目了然的纯 getter：

export class FileChooser implements api.FileChooser {
  private _page: Page;
  private _elementHandle: ElementHandle<Node>;
  private _isMultiple: boolean;

  constructor(page: Page, elementHandle: ElementHandle, isMultiple: boolean) { ... }

  element(): ElementHandle { return this._elementHandle; }
  isMultiple(): boolean { return this._isMultiple; }
  page(): Page { return this._page; }

  async setFiles(files: string | FilePayload | string[] | FilePayload[], options?: ...) {
    return await this._elementHandle.setInputFiles(files, options);
  }
}

这三个属性各有明确的实战用途：

• isMultiple() 用于断言业务语义。例如测试"批量导入"功能时，可以确认页面确实渲染了带 multiple 属性的输入框。官方测试套件 tests/page/page-filechooser.spec.ts 中"should upload multiple large files"用例就用它做了验证：向一个 50MB 级的大文件批量注入 10 个文件后，断言 fileChooser.isMultiple()).toBe(true) 且 input.files.length 等于 10。
• element() 返回的 ElementHandle 可以拿到 DOM 层面的信息，比如元素是否还在 DOM 中、属性值等，便于调试选择器定位问题。
• page() 在多页面、多 iframe 场景下帮你确认事件来源——即使文件输入框位于 iframe 内，事件也统一由顶层 page 派发（测试文件中"should emit event for iframe"用例即验证了 iframe 内的点击同样会在顶层 page 上收到 filechooser 事件）。

核心方法：FileChooser.setFiles 的参数详解

setFiles 是 FileChooser 上唯一的异步方法，文档原文描述为：

Sets the value of the file input this chooser is associated with. If some of the filePaths are relative paths, then they are resolved relative to the current working directory. For empty array, clears the selected files.

即：为关联的文件输入框设置文件；相对路径按当前工作目录解析；传入空数组的语义不是"不变"，而是清空已选文件——这一点在验证"取消选择"场景时尤其重要。

参数 files（%%-input-files-%%）

对照 Playwright 参数文档 docs/src/api/params.md 中 input-files 的完整定义：

• 类型：path | Array<path> | Object（FilePayload） | Array<Object>
• FilePayload 对象结构：
  • name（string）：文件名
  • mimeType（string）：文件类型
  • buffer（Buffer）：文件内容

也就是说 files 既可以是磁盘路径（单个或多个），也可以是内存中的虚拟文件（FilePayload）。虚拟文件在测试中价值很高：不必真正落盘即可构造临时数据，例如带特定 MIME 类型的 CSV 或图片缓冲区，测试结束也无需清理临时文件。混合写法同样成立——路径与 FilePayload 对象可以在同一数组中共存。

选项 timeout

文档为 JS 与其他语言分别引用了两套 timeout 参数：

• %%-input-timeout-%%（Python/Java/C#）：最大操作时长（毫秒），默认 30000（30 秒），传 0 表示禁用超时；全局默认值可通过 browserContext.setDefaultTimeout 或 page.setDefaultTimeout 修改。
• %%-input-timeout-js-%%（JavaScript）：默认 0——即不超时；可通过测试配置的 actionTimeout 选项，或 browserContext.setDefaultTimeout / page.setDefaultTimeout 修改默认值。

两节定义见 docs/src/api/params.md。

选项 noWaitAfter（已废弃，无实际作用）

文档中该选项引用的是 %%-input-no-wait-after-removed-%%，对应定义见 docs/src/api/params.md：

• deprecated: This option has no effect.* noWaitAfter — This option has no effect.

即在新版 Playwright 中 setFiles 的 noWaitAfter 选项已经没有任何效果，保留它只是为了向后兼容。写新代码时不应再依赖此参数。

选项 signal（JS）

%%-input-signal-%% 为 JS 语言提供的取消信号选项，允许传入 AbortSignal，以便在外部条件满足时取消正在进行的文件设置操作，与 Playwright 各等待类 API 的取消机制保持一致。

底层实现：setFiles 只是 setInputFiles 的委托

从源码可以看到，FileChooser.setFiles 并不自己操作 DOM，而是直接委托给关联元素的 ElementHandle.setInputFiles（fileChooser.ts）：

async setFiles(files, options) {
  return await this._elementHandle.setInputFiles(files, options);
}

这说明 FileChooser 本质上是一个事件包装器：它把"捕获输入框时机"的复杂性与"写入文件"的通用能力解耦——后者与直接对 ElementHandle / Locator 调 setInputFiles 走的是同一条通道。反过来，如果上传控件不是 <input type="file"> 而是自定义的点击区域，也可以先 setInputFiles 到隐藏的 input 上，不经过 FileChooser 事件。

事件捕获的边界场景：测试套件给出的验证清单

官方测试文件 tests/page/page-filechooser.spec.ts 系统地覆盖了 filechooser 事件的各种触发边界，这些用例可以直接作为你编写上传测试时的"行为契约"参考：

• 事件只触发一次（"should emit event once"）：对一个 <input type=file> 的点击，page.once('filechooser', ...) 恰好收到一次，不会重复派发。
• 监听器挂载方式无关：once / prependListener / on+off / addListener+removeListener 各种挂法都能正确捕获，说明事件走的是标准的 EventEmitter 语义，可自由组合取消与复用逻辑。
• iframe 内的输入框同样可捕获（"should emit event for iframe"）：即使在 iframe 里点击 input，顶层 page 也会收到事件——这对后台管理台里常见的"上传组件在子框架中"的场景尤其关键。
• input 尚未挂载到 DOM 也能工作（"should work when file input is not attached to DOM"）：动态 createElement('input') 后直接 click()，事件照样派发，setFiles 写入的文件内容可被 FileReader 读回。这解释了为什么"点击按钮后由 JS 动态生成 input 再触发文件对话框"这种常见的前端实现不会漏掉事件。
• 大文件多文件上传（"should upload multiple large files"）：10 个约 50MB 的 zip 文件一次性注入，验证 setFiles 对 multiple 输入框与大数据量的稳定性（该用例在 Android 模式下跳过）。

何时用 FileChooser，何时直接 setInputFiles

结合上述文档与源码事实，可以给出一个实用的决策参考：

场景	推荐方式
点击按钮触发原生文件对话框（含动态创建的 input）	必须用 FileChooser 事件模式，因为没有稳定的 DOM 句柄可提前获取
input 一开始就在 DOM 中、且可用选择器定位	可直接 locator.setInputFiles(...)，更简单
需要断言 multiple、确认 input 归属的页面	用 FileChooser，顺手调用 isMultiple() / page()
需要清理已选文件	对句柄调用 setInputFiles([]) / setFiles([])（空数组即清空）

无论走哪条路径，底层都是 setInputFiles 这一通道；FileChooser 的价值在于它把"文件选择框被打开"这一瞬态事件变成了可编程的对象。理解了这一层，文件上传、附件导入、图片粘贴前的文件准备等测试就能用统一、确定性的方式实现，而不再依赖系统对话框。

小结

FileChooser 是 Playwright 中"事件即接口"设计的一个典型：v1.8 引入的三个只读属性（element、isMultiple、page）与一个异步方法 setFiles 构成了极简但完备的 API 面。它的正确用法始终围绕一个原则——先建立等待，再触发点击；setFiles 接受路径与内存 FilePayload，相对路径相对当前工作目录解析，空数组用于清空选择；noWaitAfter 已废弃无效，timeout 的默认值在 JS（0）与其他语言（30000 毫秒）之间存在差异。事件的分发链路、参数语义均可在 docs/src/api/class-filechooser.md、packages/playwright-core/src/client/fileChooser.ts 与 tests/page/page-filechooser.spec.ts 中查证，便于在遇到问题时沿源码路径定位。