浏览器自动化中的下载与上传测试规范
通过自有夹具、明确的完成检查、隔离的工件和注重隐私的清理，让文件传输测试稳定可靠。
浏览器自动化中的文件测试要稳定，需要每个测试拥有自己的输入和输出，等待正确的完成信号，并把应用结果与磁盘上的字节分开检查。上传时使用合成文件和已知控件，确认已选择的名称与校验状态，再检查应用可见的接受结果。下载时执行文档规定的操作，等待浏览器下载事件，把工件保存到本次测试独有的路径，只检查场景需要的属性。始终清理自己创建的临时文件；本地浏览器事件不能证明业务操作完成，也不能证明远程文件已经删除。
一次传输会跨越多个责任边界。测试运行器拥有夹具和本地路径；浏览器展示选择和下载行为；应用决定是否接受文件；服务可能在浏览器停止观察后继续扫描、处理、存储、拒绝或保留文件。把这些结果分开，出现失败时就能定位问题，也不会读取无关的个人文件或把完整内容写进日志。Playwright 下载指南、文件上传指南和Selenium 文件上传文档说明的是框架机制，不是应用保证。
定义传输契约
先回答用户真正关心的问题：预期文档是否可用，或者应用是否接受了所选文件并完成了请求的操作？把答案拆成可观察的检查点。上传可以包含选择、客户端校验、提交请求和应用确认；下载可以包含用户操作、传输事件、本地工件和应用状态变化。不要把这些事实压成“文件可用”这样模糊的一条断言。
在调用框架前写出夹具契约：合成输入、格式和大小类别、页面或控件、预期结果、工作进程的所有者、输出位置，以及成功和失败时的清理方式。同时写明测试不能证明什么。保存报告不能证明数据库事务已经提交，控件显示文件名也不能证明远程处理已经完成。夹具与隔离指南介绍了更广泛的资源所有权。
让场景的公开边界保持狭窄。使用授权的测试路由和批准的合成账号。不要打开真实用户的文件选择器，不要上传机器上找到的文档，不要枚举服务器文件，也不要把文件名当成读取内容的许可。如果测试需要应用拥有的文件，应通过文档化的测试接口创建或准备，并指定删除责任人。数据应明显是合成的、非敏感的，并适合在受限的持续集成环境中短期保留。
按产品意义定义成功，而不是只按浏览器定义。表单可能在发送前显示文件名，浏览器也可能在下载到错误页面时发出下载事件。选择一到两个有意义的检查：可见状态、预期内容类型、稳定标头、已知的合成记录标识，或确定性夹具的摘要。日期、生成标识和换行符预期会变化时，不要逐字节比较整个文件。
选择 API 并保留失败夹具
用下面的简表选择最窄的浏览器 API，并明确它与保存的本地工件分别能证明什么。应用断言仍然要和框架事件分开。
| 测试需求 | Playwright | Selenium/WebDriver | 证据边界 |
|---|---|---|---|
| 指定上传 | locator.setInputFiles() 或文件选择器 | 对 <input type="file"> 使用 sendKeys() | 选择和客户端校验 |
| 观察下载 | 在操作前调用 page.waitForEvent('download') | 使用驱动的下载处理，再保存到自有路径 | 浏览器传输和有限工件检查 |
| 触发拒绝 | 只改变一个属性的合成夹具 | 通过文件控件使用同一夹具 | 字段错误和控件可复用性 |
| 清理 | finally 删除本次尝试目录 | finally 删除本次尝试目录 | 仅限本地所有权 |
在测试旁保留一个可复制的失败夹具。它能在不收集真实文档的情况下重现超时或拒绝：
const attemptDir = await fs.mkdtemp(path.join(os.tmpdir(), 'file-transfer-'));
try {
await page.locator('input[type=file]').setInputFiles('fixtures/rejected-type.txt');
await expect(page.getByRole('alert')).toContainText('file type');
} finally {
await fs.rm(attemptDir, { recursive: true, force: true });
}
夹具预期结果是字段级拒绝，随后控件仍可使用。下载超时也使用本次尝试目录，但应把第一次超时保留为主要失败。这项检查专门说明文件传输的可观察性；更广泛的夹具所有权规则和无障碍流程仍需要各自的测试。
让上传可重复
优先使用框架支持的文件输入 API，不要自动化操作系统对话框。WebDriver 可以把本地路径赋给 <input type="file">，Playwright 可以设置输入文件或处理文件选择器。这样直接使用页面的明确控件，不依赖窗口焦点、桌面主题、对话框语言或原生界面的时序。仍然需要授权页面和测试拥有的夹具路径。框架 API 不会替应用执行校验或访问控制；只有当隐藏控件确实是文档化流程的真实控件时才使用它。
把夹具准备为不可变输入。每个夹具应有场景名称、受控扩展名、已知媒体类型、有限大小和专门为该案例设计的内容。有效图片应是小型已知图片，不应是把工作站任意图片改名为 .png。拒绝案例只改变一个属性，例如扩展名或声明大小，这样才能把响应归因到原因。保持一组小型可复用夹具；真实文档会增加隐私和维护风险，却不会让断言更强。
先断言选择步骤，再提交。确认显示的文件名或数量，并在需要时检查类型或大小摘要。随后执行用户常用的提交动作，等待产品文档规定的响应。分开检查可以定位缺陷：没有选择通常指向夹具或控件，立即拒绝指向客户端校验，提交后的等待则可能指向传输或应用处理。点击动作成功返回不能证明文件已经到达服务。
把校验当成契约，而不是偶然错误文本的集合。加入一个有效合成文件、一个处于文档边界的文件，以及一个有代表性的拒绝案例，前提是这些案例对用户有意义。确认拒绝后控件仍可用，错误与字段关联且易懂，修正输入后可以重新提交。不要依赖浏览器生成的精确对话框文本或未规定的服务端消息。
不要信任文件元数据。浏览器报告的扩展名和 MIME 类型可能缺失、不准确或故意不一致。应用应在服务器端自行处理授权、大小限制、格式解析和内容校验。浏览器测试可以确认合成不匹配案例的公开响应，但不能证明扫描器、存储权限或服务处理链条正确。这些事实需要应用测试和服务端证据。
让下载可观察
要在触发下载动作之前开始等待下载。这样快速事件不会先于测试订阅发生。浏览器事件提供了有用的传输边界；随后可以把工件保存到本次尝试创建的路径，并检查一个最小属性。默认下载目录或固定文件名会依赖主机配置，并在并行执行时冲突。应在批准的临时根目录下，为每个工作进程和尝试使用新的目录。
区分传输完成和文档正确。只有在命名是用户可见行为时才检查建议文件名。只有在能回答场景问题时才检查 MIME、签名、标头或结构化字段。确定性的合成导出可以用摘要做精确比较；动态报告则检查稳定字段并允许预期变化。不要把完整内容或 base64 数据写入 CI 日志。需要更大语义检查时，使用应用支持的格式库，只保留简短的结果回执。
下载事件不能证明应用生成了正确的业务记录，也不能证明用户有权接收所有字段。在应用规定的边界验证授权和内容范围。报告只检查合成范围和少量非敏感字段；压缩包检查预期清单项，而不是提取任意路径。路径穿越、解压上限和不安全的归档处理属于应用安全测试，不应成为日常界面测试收集完整内容的理由。
不要让测试成功依赖主机的默认下载偏好、桌面外壳或真实用户的下载目录。浏览器框架可能在测试显式保存前把下载保持在浏览器临时存储中，具体生命周期随框架版本变化。使用相应的公开 API 和文档规定的保留边界。只复制到测试拥有的目标，然后按正常生命周期关闭页面或上下文，并在 finally 路径删除复制文件。
隔离工件与并行进程
每个工作进程都需要私有的工件空间。路径中可以包含稳定的场景、进程和尝试标签，但不要使用账号名、邮箱或其他个人标识。结构要足够可预测以供 CI 收集，同时确保两个进程不会写同一个文件。唯一路径可以防止覆盖，却不等于访问控制；CI 权限和保留期要另行配置，只上传诊断所需的工件。
把夹具视为只读输入。如果场景必须修改或重命名文件，就复制到本次测试的工作区。一个进程不能在另一个进程读取时覆盖共享夹具。生成下载时使用原子命名或每次尝试的新目录；缺少预期工件就明确失败，不要因为文件名相同而悄悄接受上一次尝试的文件。
并行浏览器上下文会分开浏览器管理的 cookie 和存储，但不会隔离主机文件系统或服务器记录。新上下文不能阻止两个测试请求同一导出任务、使用同一上传记录或竞相删除远程夹具。为每个进程准备独立的合成数据，或使用有明确负责人的文档化重置操作。只有确实共享的变更才串行化；增加等待时间不是可靠锁。
按敏感程度限制工件。下载的发票、诊断包或用户图片，即使由测试生成，也可能含有私人信息。优先使用信息量低的合成夹具，限制原始工件访问权限，设置短期过期，并让普通日志只包含场景标签、类别、大小等级、结果和清理状态。截图可能比回执暴露更多，只在获得批准的合成页面需要视觉诊断时捕获。
安全清理与重试
清理应遵循所有权。创建临时目录的测试负责删除它；上下文所有者负责关闭上下文；应用或服务所有者通过支持的接口删除远程对象。关闭上下文不会删除已复制的下载文件、取消服务器任务或删除已上传记录。把本地清理放进 finally，使断言失败和超时走同一条路径。若清理失败，应与原始错误一起报告，不要隐藏断言或返回误导性的成功。
让清理可以重复调用。文件写入后、记录成功前可能发生超时，安全钩子也可能再次关闭已关闭的上下文。检查测试拥有的路径和资源状态，只清理本次尝试创建的内容；无法确认时记录清理不完整。不要扫描宽泛的主机目录，也不要仅凭名称或扩展名删除文件。清理边界应尽可能比工件根目录更窄。
重试是带有新私有输出目录的新尝试。重复上传或请求新导出前，先判断动作是否只读、幂等，或能否通过场景标识安全查询。第一次请求可能已经到达服务，即使浏览器在展示响应前超时。产品提供状态信号时先检查它；否则报告结果不确定，并由测试负责人决定是否重试，不要自动制造重复远程变更。
保留第一次失败作为主要结果。如果下载超时且清理也失败，回执要同时指出这两个问题。记录浏览器和框架版本、场景标签、动作边界、预期信号、工件是否存在和清理状态。排除 cookie、授权标头、完整页面文字、原始文件字节和个人文件名。这些信息足以分派问题，不会把测试报告变成第二个数据存储。
检查应用边界
上传成功可能表示浏览器选中了文件、应用接受了请求、异步处理完成，或存储对象对后续用户可用。选择与用户需求对应的含义，并在正确边界断言。“排队中”消息只能证明进入队列，不能证明杀毒扫描完成；绿色提示只能证明显示了响应，不能证明对象以后一定可下载。需要持久化证据时，使用文档化的后续视图或专为测试设计的应用 API。
下载也有多层含义。链接可能存在却指向错误范围；浏览器可能完成了包含拒绝页面的传输；文件可能保存成功而服务器记录错误。把可见动作与有限的工件检查结合起来，必要时再增加授权的应用断言。不要收集无关网络请求，也不要通过网络检查推断隐藏账号数据。只对契约需要的请求或结果做检测。
保持端到端检查适度。文件名、MIME 解析、大小边界和服务端校验通常更适合组件或 API 测试，速度更快且更精确。浏览器测试聚焦用户体验：选择文件、看到可访问的校验、启动下载并收到清晰结果。规模较小的浏览器套件更容易诊断，也不容易保留敏感工件。Playwright 跟踪调试指南说明了如何限制可选诊断。
升级浏览器或框架后，重新执行选择、取消、有效上传、拒绝上传、完成下载、并行工件命名和失败清理案例。比较用户可见结果与文档化的 API 行为，不要比较偶然时间或临时内部路径。把版本写进测试结果。API 改变时更新夹具和所有权契约，不要用宽泛等待或额外重试掩盖差异。
BotBrowser 的能力与限制
BotBrowser 提供隔离的 BrowserContext 和独立的浏览器会话状态，可用于重复执行授权的合成上传和下载流程检查。团队可以从已知场景开始，不复用另一个上下文的 cookie 或存储，然后比较页面上的选择、校验和完成行为。当测试问题涉及已认证流程且必须控制初始浏览器状态时，这一能力很有用。BotBrowser 不控制操作系统的下载目录，不验证网站服务器端的文件处理，不取代框架事件处理或安全的临时文件管理，也不保证远程文件删除。参见BotBrowser 多账号隔离和Playwright 下载生命周期。
BrowserContext 隔离不拥有操作系统目录，也不判断网站后端是否接受、扫描、存储或删除文件。测试运行器仍须使用批准的合成文件、私有临时路径、应用级检查和受限工件保留，并在需要时调用服务支持的清理操作。干净上下文只说明浏览器管理的状态。
运行回执记录浏览器和框架版本、场景标签、合成输入类别、输出路径所有者、预期信号、观察结果和清理状态。不要把原始文件写进普通日志，只有授权诊断需要时才保留它们。明确测试观察到的是选择、浏览器传输、应用接受，还是之后可用；这些是不同事实。若服务端结果很重要，应使用文档化的应用信号，而不是声称浏览器事件已经证明它。