1. 项目初衷为什么是 Playwright 而不是其他方案1.1 这个痛点真实存在先聊个场景。你有没有遇到过这样的工作每天上班先打开某个后台系统点开“批量导入”页面然后在文件选择框里一个一个挑文件再勾选一堆默认选项最后点提交。遇到文件多的时候光选文件都得花好几分钟一天下来这种机械操作可能要重复几十次。我有个朋友在某公司做运营每天要把几百个产品图片上传到内部系统他统计过一个上午大概有两个小时都在点同一个按钮。后来他找我帮忙说能不能让浏览器自己把这些事儿干了这才有了这篇文章的缘起。这个需求说白了就是“文件批量上传自动化”。市面上能用的工具不少比如老牌的 Selenium、新锐的 Cypress还有 Windows 上的按键精灵。但我最终选了 Playwright原因不是它名气大而是它在文件上传这件事上的底层设计比其他工具更贴近真实用户操作而且在处理弹窗、隐藏元素、多文件这些恶心场景时API 设计得非常顺手。这篇文章不会讲太虚的概念我会直接带你从环境搭建开始一直写到能跑通的批量上传脚本中间所有踩过的坑都会交代清楚。1.2 Playwright 在文件上传场景的几个独特优势先说第一个优势它支持一套代码跑三种浏览器引擎Chromium、Firefox、WebKit 都有。很多内部系统只测过 Chrome但保不齐领导电脑上用 360 或者 EdgeEdge 现在本质就是 Chromium问题不大。关键是同一套 setInputFiles 逻辑在三个引擎里行为一致这就省掉了“浏览器兼容性”这个变量。第二个优势是它的文件上传 API 是“直接设置文件路径”而不是像 Selenium 那样要模拟键盘输入。你们知道 Selenium 处理文件上传有多痛苦吗如果遇到那种不允许键盘输入的控件你得用 AutoIT 或者 Robot 类去模拟系统级操作写出来的东西又啰嗦又容易失效。Playwright 的做法是把文件路径直接注入到浏览器的文件输入流相当于你在页面上点了“选择文件”之后自动完成了文件选择这绕过了操作系统弹窗这一层稳定性和速度都上了一个档次。第三个优势是它对动态内容的等待机制。批量上传最怕的就是页面渲染慢、元素还没出来脚本就报了错。Playwright 自带的 actionability 检查会自动等待元素可交互你不用在代码里写一堆 Thread.sleep。这个特性在批量任务里太关键了因为循环遍历几十个文件时每个文件上传后的响应时间都不一样如果靠固定 sleep 要么等太久要么不够用而 Playwright 的自动等待能扛住这种波动。2. 文件上传的底层机制与 Playwright 的核心 API2.1 浏览器里“选文件”到底发生了什么事想用好工具先得理解页面上的“选文件”按钮在背后做了什么。在 HTML 层面绝大多数上传控件本质上就是一个input typefile元素你点它的时候浏览器会弹出文件选择对话框选中文件后浏览器把文件路径挂到这个 input 元素上接着脚本读取文件内容上传到服务器。如果你想用代码控制就要想办法把“文件路径”塞给这个 input 元素。Playwright 的核心做法就是定位到这个 input 元素然后调用setInputFiles()方法。它内部是用 CDPChrome DevTools ProtocolChrome 开发者工具协议的 DOM.setFileInputFiles 来设置文件这个操作不需要真正的系统文件选择框所以跑自动化的时候你甚至可以把浏览器最小化。这个方法可以接受单个文件路径、也可以接受一个数组传多个文件还可以接受带 mimeType 和 buffer 的对象。有一点值得注意不是所有上传控件都是原生 input。有些前端框架比如 Ant Design 的 Upload、Element 的 Upload会把 input 隐藏起来或者改成使用拖拽区。遇到这种情况你可以直接操作隐藏的 input 元素因为就算它在视觉上被display: none或者opacity: 0了只要它在 DOM 里Playwright 就能操作。如果遇到那种连 DOM 里都没有原生 input 的组件那就得用文件选择事件来兜底这个后面实操部分我会专门讲。2.2 核心 APIsetInputFiles 的三种形态Playwright 的setInputFiles有三种常见用法对着三种场景。第一种是纯路径字符串。适合本地文件明确、不需要临时生成内容的场景。await page.setInputFiles(#fileInput, C:\\data\\test1.pdf);第二种是传多个文件路径的数组。这个就是“批量上传”最直接的手段一次把所有要传的文件都塞进去。await page.setInputFiles(#fileInput, [ C:\\data\\test1.pdf, C:\\data\\test2.pdf, C:\\data\\test3.pdf ]);第三种是传文件内容对象适合文件是程序动态生成、不落盘或者不想依赖测试机磁盘文件的场景。await page.setInputFiles(#fileInput, { name: report.xlsx, mimeType: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet, buffer: Buffer.from(文件内容或者从请求里拿到的二进制) });2.3 两个容易被忽略但很关键的参数第一个是files参数里还可以加lastModified。这不是必须的但某些系统会校验文件的最后修改时间比如内部管理系统会把上传时间戳和文件名拼在一起生成记录。给这个参数可以避免因为时间戳异常导致的后端校验失败算是一个隐蔽坑的规避手段。第二个是setInputFiles会触发 change 事件所以页面上的 JS 监听器会照常运行这很重要。有些上传组件在 change 之后还会往 FormData 里塞额外的参数比如上传人的 ID、归属栏目、覆盖策略。直接用 setInputFiles 能完整触发这条链路不需要你再手动 dispatchEvent这是它比“隐藏 input 直接赋值”这种野路子靠谱太多的地方。注意使用 setInputFiles 时路径分隔符在 Windows 下要用双反斜杠\\或者直接用正斜杠/否则某些版本的 Playwright 会报 file not found。3. 批量上传的完整实操从单文件到目录级任务3.1 准备测试环境与文件样本开始写脚本之前你需要准备一个可复现的测试环境。我这边用的是一个本地起的静态页面模仿常见的后台管理系统的文件列表页你跑实验的时候直接用你自己的目标系统也行只要你能拿到选择器。先安装 Playwright 并拉取浏览器内核。npm init -y npm install playwright/test npx playwright install chromium文件样本的话建议在脚本目录下建一个uploads文件夹里面放几十个小体积测试文件。文件命名最好规范一点比如report_01.pdf、product_02.jpg这样脚本运行时能直观地看到处理的顺序。实测下来几千个几 KB 的小文件和几百个几 MB 的大文件处理速度差距很大但脚本逻辑是一致的建议初学先用小文件。3.2 第一阶段固定文件上传我把整个批量上传拆成了几个阶段先看最基础的固定文件上传。它的作用是验证整个链路通不通包括页面加载、选择文件、提交表单、等待反馈。const { test, expect } require(playwright/test); test(固定文件批量上传, async ({ page }) { await page.goto(http://localhost:8080/upload); const fileInput page.locator(input[typefile]); await fileInput.setInputFiles([ ./uploads/report_01.pdf, ./uploads/report_02.pdf, ./uploads/report_03.pdf ]); await page.click(button:has-text(提交)); // 等待上传成功提示出现 await expect(page.locator(.upload-success)).toHaveCount(3, { timeout: 10000 }); });这段代码跑通之后你能看到几个 key point一是 input 元素定位二是 setInputFiles 本身就把所有文件“选中”了不需要一个一个来三是提交后的结果用 expect 来等待而不是 sleep。第一次跑通的时候你会感觉整个过程快得离谱几十个文件十几秒就完事了。这里有个我实测中的体验如果你遇到上传成功率不稳定可以先检查 setInputFiles 之后页面上是否显示了“N 个文件已选择”之类的内容。有些组件在文件选择后还要再点一次“开始上传”按钮这跟“选择文件”按钮是两回事漏掉这一步脚本不会报错但它就卡在提交前的状态里。3.3 第二阶段动态遍历目录批量上传固定文件的问题显而易见要是文件是动态增加的脚本只能跟着改。所以第二阶段要解决“自动遍历文件夹里的所有文件逐个或者分组上传”这件事。Node.js 的fs模块读目录然后根据文件扩展名分组再塞给 setInputFiles。const fs require(fs); const path require(path); function getFilesByExtensions(dir, exts) { const results []; const items fs.readdirSync(dir); for (const item of items) { const fullPath path.join(dir, item); const stat fs.statSync(fullPath); if (stat.isFile()) { const ext path.extname(item).toLowerCase(); if (exts.includes(ext)) { results.push(fullPath); } } } return results; } const files getFilesByExtensions(./uploads, [.pdf, .jpg, .png]); const chunks []; const CHUNK_SIZE 10; for (let i 0; i files.length; i CHUNK_SIZE) { chunks.push(files.slice(i, i CHUNK_SIZE)); } test(动态目录批量上传, async ({ page }) { await page.goto(http://localhost:8080/upload); for (let i 0; i chunks.length; i) { const input page.locator(input[typefile]); await input.setInputFiles(chunks[i]); await page.click(button:has-text(提交)); await expect(page.locator(.upload-success)).toHaveCount((i 1) * chunks[i].length, { timeout: 15000 }); } });这里我用了分组上传每批 10 个文件。为什么不分一次传所有文件因为很多后端接口对单次上传文件数量和大小有限制传太多浏览器内存也吃紧。分组上传更像真实用户在页面上的操作——一次选一批、传一批、等反馈、再传下一批。另外注意.upload-success的计数方式我用了(i 1) * chunks[i].length而不是简单的累加这样确保每一批都完成。如果你在真实系统里没有这种成功元素的计数可以用最后列表条数的断言比如表格行数等于已传文件总数同样可靠。3.4 第三阶段带附加参数的表单逐个提交纯传文件太理想化了实际业务往往要求每个文件都要填一个标题、一个分类、或者勾选某个覆盖策略。这种场景下一个文件上传动作往往对应一整块表单脚本就得用循环来逐条处理。test(带附加参数的表单逐个提交, async ({ page }) { await page.goto(http://localhost:8080/upload); const files getFilesByExtensions(./uploads, [.jpg, .png]); for (const file of files) { const filename path.basename(file, path.extname(file)); // 每次进入一个新表单重新定位 input const input page.locator(input[typefile]); await input.setInputFiles(file); // 填标题默认用文件名 const titleInput page.locator(input[nametitle]); await titleInput.fill(filename); // 选择分类 await page.selectOption(select[namecategory], product); // 勾选“覆盖同名文件” await page.check(input[nameoverwrite]); await page.click(button:has-text(提交)); // 等待本条提交完成列表里出现对应文件名 await expect(page.locator(text${filename})).toBeVisible({ timeout: 10000 }); // 弹窗或 toast 关闭逻辑如果上一步出现弹窗顺手关掉 const closeBtn page.locator(.toast-close); if (await closeBtn.count()) { await closeBtn.click(); } } });这套循环的逻辑核心就是“每处理一个文件都要把状态拉回初始状态”。具体到细节如果页面在上传后还停留在成功提示层下一个次循环找不到元素那就要先在循环开头做一次“重置页面状态”的操作比如点击列表上的“新增”按钮或者跳转回上传页。这一步漏了往往是最常见的批量脚本不稳定原因。3.5 上传进度的判断与等待策略批量上传最磨人的是“怎么判断这一批传完了”。后端传大文件可能要几秒期间页面上会出现进度条百分比。这种场景不要用百分比判断结束因为后端处理完文件还可能要做转码、提取信息等后续动作此时进度条可能已经 100% 但还没完全成功。我推荐两个更稳定的结束信号第一个是出现明确的成功提示。比如“上传成功”“处理完成”这类文字或者列表中出现对应记录。await expect(page.locator(.upload-success)).toHaveCount(count);第二个是状态元素从“处理中”变成“已完成”。很多系统会有一列状态标签比如一开始是“待处理”上传后变成“已完成”。这时可以用toHaveText或者自定义 expect 轮询。await expect(page.locator(.status-badge).filter({ hasText: 已完成 })).toHaveCount(count);重要技巧只要业务状态明确优先用业务状态的断言而不是网络层面的等待。Playwright 的waitForResponse在某些内部系统里会因为后端数据异步写入而失效因为接口返回了不代表最终数据完成了。4. 那些不配合的页面特殊上传场景处理4.1 input[typefile] 是隐藏的怎么定位前端框架把上传控件做得很漂亮通常是一个按钮或者一个拖拽区域真正触发文件选择的 input 被display: none或visibility: hidden藏起来了。很多人看到这种 DOM 就慌了以为用 Playwright 没法操作。实际上 Playwright 的setInputFiles完全可以操作隐藏元素。它不需要元素可见只需要元素存在于 DOM、能被定位到。const input page.locator(input[typefile]); await input.setInputFiles(C:\\data\\test1.pdf);如果页面有多个输入框可以通过nth()或者靠近某个特定文本的locator精确定位。比如const input page.locator(.upload-wrapper input[typefile]);当然也有极少数情况input 是被动态渲染出来的要在点击“上传”按钮之后才出现在 DOM 里。这种情况就先点击按钮再等待 input 出现。await page.click(.upload-button); await page.waitForSelector(input[typefile]); await page.locator(input[typefile]).setInputFiles(file);我在实际内部系统中还遇到过更极端的情况input 的 type 不是 file整个上传组件是把文件转成 base64 再通过 JS 拼接进 FormData。这种属于“非标准实现”严格来说已经不是文件输入框了那就只能走 filechooser 方案。4.2 上传控件在 iframe 里老系统特别喜欢用 iframe 嵌上传模块尤其是那种前后端不分离的传统后台。Playwright 对 iframe 的处理比较 elegant先定位到frameLocator然后在 frame 内部操作。const frame page.frameLocator(#uploadFrame); await frame.locator(input[typefile]).setInputFiles(C:\\data\\test1.pdf);注意frameLocator只能定位到直接的 frame如果有多层嵌套 iframe需要一层层往下走。调试的时候在 Playwright 的 trace viewer 里看元素路径最直观。调试 iframe 上传时我的心得如果点击提交按钮之后页面刷新了但数据没进去大概率是 iframe 里的表单 action 指向的接口地址有问题这时候你先手动在页面上试一次确认成功后再自动化。别在框架逻辑还没验证好的时候写脚本容易把锅甩给 Playwright。4.3 非原生控件filechooser 事件兜底总有一部分系统不走寻常路页面上没有原生 input而是点击按钮后通过 JS 动态创建 FileReader 或 DataTransfer 对象去读文件。对于这类页面Playwright 提供了一个 filechooser 事件它可以拦截浏览器弹出的文件选择框然后注入文件路径。const [fileChooser] await Promise.all([ page.waitForEvent(filechooser), page.click(.upload-btn) ]); await fileChooser.setFiles(C:\\data\\test1.pdf);这个方案的逻辑是先声明“我在等文件选择事件”然后点击上传按钮触发它接着在回调里把文件塞进去。整个过程不用管页面有没有 input 元素只要点击动作会触发文件选择器就能接管。filechooser 的setFiles也支持数组批量场景一样适用。但要注意它一次只对应一个文件选择器事件如果你点击按钮后弹了两个选择器得写两个waitForEvent对应。我印象很深的一次踩坑某个系统点击“选择文件”后不是立刻打开选择器而是先弹一个“是否确认导入”的确认框确认后才弹文件选择器。这种流程要用Promise.all链着来先等待确认框出现、点击确认、再等待 filechooser 事件。说白了就是事件顺序不能乱。4.4 Drag and Drop 拖拽上传如何模拟现在不少系统都支持把桌面文件拖到页面上传这种交互在浏览器里是通过DataTransfer对象实现的。Playwright 本身没有一套“模拟真实拖拽”的高级 API需要手动构造 DataTransfer。const dataTransfer await page.evaluateHandle(() { const dt new DataTransfer(); // 用 File 构造函数创建文件对象 const file new File([hello world], test.txt, { type: text/plain }); dt.items.add(file); return dt; }); await page.dispatchEvent(.drop-zone, drop, { dataTransfer });evaluateHandle在浏览器上下文里创建了一个 DataTransfer 对象然后dispatchEvent把 drop 事件派发到目标元素上。这个方法在 Electron 应用界面和某些 Web Desktop 场景里也能用。不过在写拖拽之前我建议你先抓取一下页面的监听器。打开 DevTools 的 Elements 面板找到 drop zone 对应的 DOM 节点在 Console 里执行getEventListeners(node)看看它到底监听的是 drop 还是dragover。有些组件只监听 dragover 就去读数据而有些则两个事件都做了处理。事件没对上脚本就不会触发。提示page.dispatchEvent派发的事件是合成的不会真正触发浏览器原生拖拽行为。如果系统代码里依赖了dragenter事件的dataTransfer里特定格式的数据类型比如自定义的 MIME 类型你需要按它的要求填好 DataTransfer 内容否则就算触发 drop 也会被业务校验拦下来。5. 稳定性陷阱从“能跑”到“跑不挂”5.1 不要用固定等待新手最容易犯的错就是把定时等待当万能药。刚写完await page.waitForTimeout(3000)的时候发现一切正常文件多了以后发现超时率直线上升然后你开始调大 sleep 时间改到 5000、8000、甚至 15000脚本动辄跑半小时起步。这种方案有大问题第一等待时间和网络状况无法线性匹配你没法预期每一个文件上传要多久第二等待时间太长整个批量任务效率就废了第三有些系统在某个环节会因为后端服务处理慢而阻塞一会儿固定的 sleep 无法感知这种临时延迟。正确的思路是“等条件”而“不等时间”。常用的三个手法expect的通配断言、locator.waitFor()针对某个元素状态等待、waitForResponse针对网络接口等待。这三者我在前面都演示过了这里强调一遍优先级能用业务状态判断优先用业务状态其次用网络响应最后才用固定等待兜底。5.2 文件路径与测试数据隔离把测试文件放到和脚本无关的目录里尽量不要放到node_modules下面或者系统临时目录因为这些路径某些系统环境里没有读权限或者会被清理。我在实操中喜欢建一个平级目录叫test-data/uploads然后在项目里配置环境变量UPLOAD_DIR这样脚本不硬编码路径后面不管是本地跑、CI 跑还是服务器上跑只需要改环境变量就行。const uploadDir process.env.UPLOAD_DIR || path.join(__dirname, test-data, uploads);另外文件命名上有个细节有些后端系统用文件名做唯一标识如果重复传同名文件会被当作更新而不是新增。如果你跑幂等回归测试最好每次生成一个带时间戳的目录比如uploads-20250118文件用完可以批量删避免污染正式数据。5.3 并发执行的约束Playwright 的test.describe.parallel模式会让多个测试用例并行跑但文件上传这个场景我建议关闭并行。原因是并发跑多个浏览器实例容易触发后端的上传限流和并发锁而且如果你们用的是固定测试环境两个用例同时往同一个目录传文件会有互相覆盖的问题。如果你一定要并行推荐给每个并发测试实例分配独立的用户账号和应用目录否则排查问题时你会分不清是哪条线程污染了数据。我们实际用的方案是全量上传任务单独建一个 spec 文件故意设置test.describe.configure({ mode: serial })保证上传任务和上传任务之间串行执行其他无关的只读测试不受影响。5.4 失败重试机制设计批量上传跑 20 个文件传挂了 1 个整个任务重跑不现实。所以脚本要对每一步做拆分做不到逐文件重试也要做到逐批次重试。最简单的方案是外层套一个 for 循环批次失败后只是记录日志然后 continue 继续下一批。复杂一点的方案是写一个retry装饰器捕获超时异常重试前重新定位 input 和重置表单。async function retryOnTimeout(fn, retries 3) { for (let i 0; i retries; i) { try { return await fn(); } catch (e) { if (i retries - 1) throw e; console.log(第 ${i 1} 次重试错误: ${e.message}); } } }我对重试的一个原则如果重试了 3 次还是失败大概率不是偶发问题而是业务校验不通过比如某个文件格式不对、某个必填字段没填。这种失败必须立刻暴露出来不要无限重试掩盖真实问题。因此重试日志里要输出文件路径和失败时的页面日志快照方便你事后定位。6. 常见问题排查与经验总结6.1 问题速查表现象可能原因解决方案setInputFiles 报 “File not found”路径分隔符或者文件不存在检查路径Windows 使用双反斜杠或正斜杠确认文件存在点击提交后列表没有数据input 选中了文件但表单被前置校验拦截手动操作一遍确认业务路径脚本加上表单错误提示的断言上传成功但页面弹窗没关下一个循环找不到元素状态没有拉回初始循环开头关闭弹窗等待可操作状态隐藏 input 定位不到input 在 iframe 或者 shadow DOM 里用 frameLocator 定位 iframeshadow DOM 用 piercing selector文件传了但后端收到的文件大小是 0某些组件需要先触发 change 事件再上传检查 DOM 上是否有其他属性需要设置考虑用 filechooser 事件替代并发上传后端报限流触发并发上传过多串行执行或分批控制并发数6.2 我踩过的几个典型坑第一个坑是“iframe 内 input 定位失败”。那是一个老旧的内部人资系统上传控件嵌在多层 iframe 里用普通的分页 locator 根本摸不到。当时手动操作上传是正常的但是脚本怎么都报找不到元素。最后是通过 trace viewer 一帧一帧看元素树才发现它在嵌套的 iframe 里。从那之后我遇到传统的 iframe 布局系统第一反应就是先看元素树里有没有 iframe 节点。第二个坑是“上传完成判定失效”。有个系统上传成功后会弹出一个 modal 提示成功但是 modal 里有一个“知道了”按钮不点掉的话下次定位.upload-success还是会找到旧元素。我的做法是把成功提示改成expect(...).toHaveCount(expectedCount)的精确计数这样能感知到旧元素和新元素的叠加。后来发现还是有一种情况有些系统会复用同一个成功提示元素只是改变文字内容计数根本不管用那就要改成断言具体文字比如“上传成功5/5”。第三个坑是“换浏览器环境后脚本失效”。同一个脚本在本地 Chromium 跑得好好的拿到公司服务器上的无头环境跑就卡住。后来发现是服务器上字体和本地不一样某个按钮的 CSS 变化导致点击位置偏移。这个问题的通用解法是所有点击都不要用坐标点击全部用 locator 点击让 Playwright 自己计算点击位置。如果 UI 布局不稳定再考虑用position: fixed的固定悬浮按钮时用click(force: true)绕过遮挡检查但注意这会跳过 Playwright 的“元素可点击”校验只能作为最后手段。6.3 后续扩展可能性批量上传这个基础能力其实只是开始。我后续在这个基础上还扩展过几件事一个是把上传前后的文件列表差异比对自动生成报告另一个是 CI 流水线里定时跑全量上传回归还有一个是失败文件自动移动到一个failed文件夹并打日志方便运营同事核对。如果你们团队已经有了一套接口自动化框架也可以把 Playwright 的 UI 上传和接口层面的上传做双保险。接口没法验证 UI 交互逻辑UI 没法模拟后端对数据的各种处理两者互补能把这一类“上传类”项目的可靠性拉高不少。从我的实际体会来说文件批量上传自动化是投资回报率很高的一类脚本。它不像复杂业务流程那样需要维护一大堆业务状态核心就是“定位 input、塞文件、提交、等反馈”四步循环。你只要把这四步稳定住再花点精力处理弹窗和 iframe 这类偶发因子基本上就能把这类重复劳动彻底丢掉。如果你手上刚好有这种每天都要点上传的系统不妨按这篇文章搭一个脚本试试第一次跑通时那种“终于不用再手点了”的爽快感值得体验一次。
1. 项目初衷为什么是 Playwright 而不是其他方案1.1 这个痛点真实存在先聊个场景。你有没有遇到过这样的工作每天上班先打开某个后台系统点开“批量导入”页面然后在文件选择框里一个一个挑文件再勾选一堆默认选项最后点提交。遇到文件多的时候光选文件都得花好几分钟一天下来这种机械操作可能要重复几十次。我有个朋友在某公司做运营每天要把几百个产品图片上传到内部系统他统计过一个上午大概有两个小时都在点同一个按钮。后来他找我帮忙说能不能让浏览器自己把这些事儿干了这才有了这篇文章的缘起。这个需求说白了就是“文件批量上传自动化”。市面上能用的工具不少比如老牌的 Selenium、新锐的 Cypress还有 Windows 上的按键精灵。但我最终选了 Playwright原因不是它名气大而是它在文件上传这件事上的底层设计比其他工具更贴近真实用户操作而且在处理弹窗、隐藏元素、多文件这些恶心场景时API 设计得非常顺手。这篇文章不会讲太虚的概念我会直接带你从环境搭建开始一直写到能跑通的批量上传脚本中间所有踩过的坑都会交代清楚。1.2 Playwright 在文件上传场景的几个独特优势先说第一个优势它支持一套代码跑三种浏览器引擎Chromium、Firefox、WebKit 都有。很多内部系统只测过 Chrome但保不齐领导电脑上用 360 或者 EdgeEdge 现在本质就是 Chromium问题不大。关键是同一套 setInputFiles 逻辑在三个引擎里行为一致这就省掉了“浏览器兼容性”这个变量。第二个优势是它的文件上传 API 是“直接设置文件路径”而不是像 Selenium 那样要模拟键盘输入。你们知道 Selenium 处理文件上传有多痛苦吗如果遇到那种不允许键盘输入的控件你得用 AutoIT 或者 Robot 类去模拟系统级操作写出来的东西又啰嗦又容易失效。Playwright 的做法是把文件路径直接注入到浏览器的文件输入流相当于你在页面上点了“选择文件”之后自动完成了文件选择这绕过了操作系统弹窗这一层稳定性和速度都上了一个档次。第三个优势是它对动态内容的等待机制。批量上传最怕的就是页面渲染慢、元素还没出来脚本就报了错。Playwright 自带的 actionability 检查会自动等待元素可交互你不用在代码里写一堆 Thread.sleep。这个特性在批量任务里太关键了因为循环遍历几十个文件时每个文件上传后的响应时间都不一样如果靠固定 sleep 要么等太久要么不够用而 Playwright 的自动等待能扛住这种波动。2. 文件上传的底层机制与 Playwright 的核心 API2.1 浏览器里“选文件”到底发生了什么事想用好工具先得理解页面上的“选文件”按钮在背后做了什么。在 HTML 层面绝大多数上传控件本质上就是一个input typefile元素你点它的时候浏览器会弹出文件选择对话框选中文件后浏览器把文件路径挂到这个 input 元素上接着脚本读取文件内容上传到服务器。如果你想用代码控制就要想办法把“文件路径”塞给这个 input 元素。Playwright 的核心做法就是定位到这个 input 元素然后调用setInputFiles()方法。它内部是用 CDPChrome DevTools ProtocolChrome 开发者工具协议的 DOM.setFileInputFiles 来设置文件这个操作不需要真正的系统文件选择框所以跑自动化的时候你甚至可以把浏览器最小化。这个方法可以接受单个文件路径、也可以接受一个数组传多个文件还可以接受带 mimeType 和 buffer 的对象。有一点值得注意不是所有上传控件都是原生 input。有些前端框架比如 Ant Design 的 Upload、Element 的 Upload会把 input 隐藏起来或者改成使用拖拽区。遇到这种情况你可以直接操作隐藏的 input 元素因为就算它在视觉上被display: none或者opacity: 0了只要它在 DOM 里Playwright 就能操作。如果遇到那种连 DOM 里都没有原生 input 的组件那就得用文件选择事件来兜底这个后面实操部分我会专门讲。2.2 核心 APIsetInputFiles 的三种形态Playwright 的setInputFiles有三种常见用法对着三种场景。第一种是纯路径字符串。适合本地文件明确、不需要临时生成内容的场景。await page.setInputFiles(#fileInput, C:\\data\\test1.pdf);第二种是传多个文件路径的数组。这个就是“批量上传”最直接的手段一次把所有要传的文件都塞进去。await page.setInputFiles(#fileInput, [ C:\\data\\test1.pdf, C:\\data\\test2.pdf, C:\\data\\test3.pdf ]);第三种是传文件内容对象适合文件是程序动态生成、不落盘或者不想依赖测试机磁盘文件的场景。await page.setInputFiles(#fileInput, { name: report.xlsx, mimeType: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet, buffer: Buffer.from(文件内容或者从请求里拿到的二进制) });2.3 两个容易被忽略但很关键的参数第一个是files参数里还可以加lastModified。这不是必须的但某些系统会校验文件的最后修改时间比如内部管理系统会把上传时间戳和文件名拼在一起生成记录。给这个参数可以避免因为时间戳异常导致的后端校验失败算是一个隐蔽坑的规避手段。第二个是setInputFiles会触发 change 事件所以页面上的 JS 监听器会照常运行这很重要。有些上传组件在 change 之后还会往 FormData 里塞额外的参数比如上传人的 ID、归属栏目、覆盖策略。直接用 setInputFiles 能完整触发这条链路不需要你再手动 dispatchEvent这是它比“隐藏 input 直接赋值”这种野路子靠谱太多的地方。注意使用 setInputFiles 时路径分隔符在 Windows 下要用双反斜杠\\或者直接用正斜杠/否则某些版本的 Playwright 会报 file not found。3. 批量上传的完整实操从单文件到目录级任务3.1 准备测试环境与文件样本开始写脚本之前你需要准备一个可复现的测试环境。我这边用的是一个本地起的静态页面模仿常见的后台管理系统的文件列表页你跑实验的时候直接用你自己的目标系统也行只要你能拿到选择器。先安装 Playwright 并拉取浏览器内核。npm init -y npm install playwright/test npx playwright install chromium文件样本的话建议在脚本目录下建一个uploads文件夹里面放几十个小体积测试文件。文件命名最好规范一点比如report_01.pdf、product_02.jpg这样脚本运行时能直观地看到处理的顺序。实测下来几千个几 KB 的小文件和几百个几 MB 的大文件处理速度差距很大但脚本逻辑是一致的建议初学先用小文件。3.2 第一阶段固定文件上传我把整个批量上传拆成了几个阶段先看最基础的固定文件上传。它的作用是验证整个链路通不通包括页面加载、选择文件、提交表单、等待反馈。const { test, expect } require(playwright/test); test(固定文件批量上传, async ({ page }) { await page.goto(http://localhost:8080/upload); const fileInput page.locator(input[typefile]); await fileInput.setInputFiles([ ./uploads/report_01.pdf, ./uploads/report_02.pdf, ./uploads/report_03.pdf ]); await page.click(button:has-text(提交)); // 等待上传成功提示出现 await expect(page.locator(.upload-success)).toHaveCount(3, { timeout: 10000 }); });这段代码跑通之后你能看到几个 key point一是 input 元素定位二是 setInputFiles 本身就把所有文件“选中”了不需要一个一个来三是提交后的结果用 expect 来等待而不是 sleep。第一次跑通的时候你会感觉整个过程快得离谱几十个文件十几秒就完事了。这里有个我实测中的体验如果你遇到上传成功率不稳定可以先检查 setInputFiles 之后页面上是否显示了“N 个文件已选择”之类的内容。有些组件在文件选择后还要再点一次“开始上传”按钮这跟“选择文件”按钮是两回事漏掉这一步脚本不会报错但它就卡在提交前的状态里。3.3 第二阶段动态遍历目录批量上传固定文件的问题显而易见要是文件是动态增加的脚本只能跟着改。所以第二阶段要解决“自动遍历文件夹里的所有文件逐个或者分组上传”这件事。Node.js 的fs模块读目录然后根据文件扩展名分组再塞给 setInputFiles。const fs require(fs); const path require(path); function getFilesByExtensions(dir, exts) { const results []; const items fs.readdirSync(dir); for (const item of items) { const fullPath path.join(dir, item); const stat fs.statSync(fullPath); if (stat.isFile()) { const ext path.extname(item).toLowerCase(); if (exts.includes(ext)) { results.push(fullPath); } } } return results; } const files getFilesByExtensions(./uploads, [.pdf, .jpg, .png]); const chunks []; const CHUNK_SIZE 10; for (let i 0; i files.length; i CHUNK_SIZE) { chunks.push(files.slice(i, i CHUNK_SIZE)); } test(动态目录批量上传, async ({ page }) { await page.goto(http://localhost:8080/upload); for (let i 0; i chunks.length; i) { const input page.locator(input[typefile]); await input.setInputFiles(chunks[i]); await page.click(button:has-text(提交)); await expect(page.locator(.upload-success)).toHaveCount((i 1) * chunks[i].length, { timeout: 15000 }); } });这里我用了分组上传每批 10 个文件。为什么不分一次传所有文件因为很多后端接口对单次上传文件数量和大小有限制传太多浏览器内存也吃紧。分组上传更像真实用户在页面上的操作——一次选一批、传一批、等反馈、再传下一批。另外注意.upload-success的计数方式我用了(i 1) * chunks[i].length而不是简单的累加这样确保每一批都完成。如果你在真实系统里没有这种成功元素的计数可以用最后列表条数的断言比如表格行数等于已传文件总数同样可靠。3.4 第三阶段带附加参数的表单逐个提交纯传文件太理想化了实际业务往往要求每个文件都要填一个标题、一个分类、或者勾选某个覆盖策略。这种场景下一个文件上传动作往往对应一整块表单脚本就得用循环来逐条处理。test(带附加参数的表单逐个提交, async ({ page }) { await page.goto(http://localhost:8080/upload); const files getFilesByExtensions(./uploads, [.jpg, .png]); for (const file of files) { const filename path.basename(file, path.extname(file)); // 每次进入一个新表单重新定位 input const input page.locator(input[typefile]); await input.setInputFiles(file); // 填标题默认用文件名 const titleInput page.locator(input[nametitle]); await titleInput.fill(filename); // 选择分类 await page.selectOption(select[namecategory], product); // 勾选“覆盖同名文件” await page.check(input[nameoverwrite]); await page.click(button:has-text(提交)); // 等待本条提交完成列表里出现对应文件名 await expect(page.locator(text${filename})).toBeVisible({ timeout: 10000 }); // 弹窗或 toast 关闭逻辑如果上一步出现弹窗顺手关掉 const closeBtn page.locator(.toast-close); if (await closeBtn.count()) { await closeBtn.click(); } } });这套循环的逻辑核心就是“每处理一个文件都要把状态拉回初始状态”。具体到细节如果页面在上传后还停留在成功提示层下一个次循环找不到元素那就要先在循环开头做一次“重置页面状态”的操作比如点击列表上的“新增”按钮或者跳转回上传页。这一步漏了往往是最常见的批量脚本不稳定原因。3.5 上传进度的判断与等待策略批量上传最磨人的是“怎么判断这一批传完了”。后端传大文件可能要几秒期间页面上会出现进度条百分比。这种场景不要用百分比判断结束因为后端处理完文件还可能要做转码、提取信息等后续动作此时进度条可能已经 100% 但还没完全成功。我推荐两个更稳定的结束信号第一个是出现明确的成功提示。比如“上传成功”“处理完成”这类文字或者列表中出现对应记录。await expect(page.locator(.upload-success)).toHaveCount(count);第二个是状态元素从“处理中”变成“已完成”。很多系统会有一列状态标签比如一开始是“待处理”上传后变成“已完成”。这时可以用toHaveText或者自定义 expect 轮询。await expect(page.locator(.status-badge).filter({ hasText: 已完成 })).toHaveCount(count);重要技巧只要业务状态明确优先用业务状态的断言而不是网络层面的等待。Playwright 的waitForResponse在某些内部系统里会因为后端数据异步写入而失效因为接口返回了不代表最终数据完成了。4. 那些不配合的页面特殊上传场景处理4.1 input[typefile] 是隐藏的怎么定位前端框架把上传控件做得很漂亮通常是一个按钮或者一个拖拽区域真正触发文件选择的 input 被display: none或visibility: hidden藏起来了。很多人看到这种 DOM 就慌了以为用 Playwright 没法操作。实际上 Playwright 的setInputFiles完全可以操作隐藏元素。它不需要元素可见只需要元素存在于 DOM、能被定位到。const input page.locator(input[typefile]); await input.setInputFiles(C:\\data\\test1.pdf);如果页面有多个输入框可以通过nth()或者靠近某个特定文本的locator精确定位。比如const input page.locator(.upload-wrapper input[typefile]);当然也有极少数情况input 是被动态渲染出来的要在点击“上传”按钮之后才出现在 DOM 里。这种情况就先点击按钮再等待 input 出现。await page.click(.upload-button); await page.waitForSelector(input[typefile]); await page.locator(input[typefile]).setInputFiles(file);我在实际内部系统中还遇到过更极端的情况input 的 type 不是 file整个上传组件是把文件转成 base64 再通过 JS 拼接进 FormData。这种属于“非标准实现”严格来说已经不是文件输入框了那就只能走 filechooser 方案。4.2 上传控件在 iframe 里老系统特别喜欢用 iframe 嵌上传模块尤其是那种前后端不分离的传统后台。Playwright 对 iframe 的处理比较 elegant先定位到frameLocator然后在 frame 内部操作。const frame page.frameLocator(#uploadFrame); await frame.locator(input[typefile]).setInputFiles(C:\\data\\test1.pdf);注意frameLocator只能定位到直接的 frame如果有多层嵌套 iframe需要一层层往下走。调试的时候在 Playwright 的 trace viewer 里看元素路径最直观。调试 iframe 上传时我的心得如果点击提交按钮之后页面刷新了但数据没进去大概率是 iframe 里的表单 action 指向的接口地址有问题这时候你先手动在页面上试一次确认成功后再自动化。别在框架逻辑还没验证好的时候写脚本容易把锅甩给 Playwright。4.3 非原生控件filechooser 事件兜底总有一部分系统不走寻常路页面上没有原生 input而是点击按钮后通过 JS 动态创建 FileReader 或 DataTransfer 对象去读文件。对于这类页面Playwright 提供了一个 filechooser 事件它可以拦截浏览器弹出的文件选择框然后注入文件路径。const [fileChooser] await Promise.all([ page.waitForEvent(filechooser), page.click(.upload-btn) ]); await fileChooser.setFiles(C:\\data\\test1.pdf);这个方案的逻辑是先声明“我在等文件选择事件”然后点击上传按钮触发它接着在回调里把文件塞进去。整个过程不用管页面有没有 input 元素只要点击动作会触发文件选择器就能接管。filechooser 的setFiles也支持数组批量场景一样适用。但要注意它一次只对应一个文件选择器事件如果你点击按钮后弹了两个选择器得写两个waitForEvent对应。我印象很深的一次踩坑某个系统点击“选择文件”后不是立刻打开选择器而是先弹一个“是否确认导入”的确认框确认后才弹文件选择器。这种流程要用Promise.all链着来先等待确认框出现、点击确认、再等待 filechooser 事件。说白了就是事件顺序不能乱。4.4 Drag and Drop 拖拽上传如何模拟现在不少系统都支持把桌面文件拖到页面上传这种交互在浏览器里是通过DataTransfer对象实现的。Playwright 本身没有一套“模拟真实拖拽”的高级 API需要手动构造 DataTransfer。const dataTransfer await page.evaluateHandle(() { const dt new DataTransfer(); // 用 File 构造函数创建文件对象 const file new File([hello world], test.txt, { type: text/plain }); dt.items.add(file); return dt; }); await page.dispatchEvent(.drop-zone, drop, { dataTransfer });evaluateHandle在浏览器上下文里创建了一个 DataTransfer 对象然后dispatchEvent把 drop 事件派发到目标元素上。这个方法在 Electron 应用界面和某些 Web Desktop 场景里也能用。不过在写拖拽之前我建议你先抓取一下页面的监听器。打开 DevTools 的 Elements 面板找到 drop zone 对应的 DOM 节点在 Console 里执行getEventListeners(node)看看它到底监听的是 drop 还是dragover。有些组件只监听 dragover 就去读数据而有些则两个事件都做了处理。事件没对上脚本就不会触发。提示page.dispatchEvent派发的事件是合成的不会真正触发浏览器原生拖拽行为。如果系统代码里依赖了dragenter事件的dataTransfer里特定格式的数据类型比如自定义的 MIME 类型你需要按它的要求填好 DataTransfer 内容否则就算触发 drop 也会被业务校验拦下来。5. 稳定性陷阱从“能跑”到“跑不挂”5.1 不要用固定等待新手最容易犯的错就是把定时等待当万能药。刚写完await page.waitForTimeout(3000)的时候发现一切正常文件多了以后发现超时率直线上升然后你开始调大 sleep 时间改到 5000、8000、甚至 15000脚本动辄跑半小时起步。这种方案有大问题第一等待时间和网络状况无法线性匹配你没法预期每一个文件上传要多久第二等待时间太长整个批量任务效率就废了第三有些系统在某个环节会因为后端服务处理慢而阻塞一会儿固定的 sleep 无法感知这种临时延迟。正确的思路是“等条件”而“不等时间”。常用的三个手法expect的通配断言、locator.waitFor()针对某个元素状态等待、waitForResponse针对网络接口等待。这三者我在前面都演示过了这里强调一遍优先级能用业务状态判断优先用业务状态其次用网络响应最后才用固定等待兜底。5.2 文件路径与测试数据隔离把测试文件放到和脚本无关的目录里尽量不要放到node_modules下面或者系统临时目录因为这些路径某些系统环境里没有读权限或者会被清理。我在实操中喜欢建一个平级目录叫test-data/uploads然后在项目里配置环境变量UPLOAD_DIR这样脚本不硬编码路径后面不管是本地跑、CI 跑还是服务器上跑只需要改环境变量就行。const uploadDir process.env.UPLOAD_DIR || path.join(__dirname, test-data, uploads);另外文件命名上有个细节有些后端系统用文件名做唯一标识如果重复传同名文件会被当作更新而不是新增。如果你跑幂等回归测试最好每次生成一个带时间戳的目录比如uploads-20250118文件用完可以批量删避免污染正式数据。5.3 并发执行的约束Playwright 的test.describe.parallel模式会让多个测试用例并行跑但文件上传这个场景我建议关闭并行。原因是并发跑多个浏览器实例容易触发后端的上传限流和并发锁而且如果你们用的是固定测试环境两个用例同时往同一个目录传文件会有互相覆盖的问题。如果你一定要并行推荐给每个并发测试实例分配独立的用户账号和应用目录否则排查问题时你会分不清是哪条线程污染了数据。我们实际用的方案是全量上传任务单独建一个 spec 文件故意设置test.describe.configure({ mode: serial })保证上传任务和上传任务之间串行执行其他无关的只读测试不受影响。5.4 失败重试机制设计批量上传跑 20 个文件传挂了 1 个整个任务重跑不现实。所以脚本要对每一步做拆分做不到逐文件重试也要做到逐批次重试。最简单的方案是外层套一个 for 循环批次失败后只是记录日志然后 continue 继续下一批。复杂一点的方案是写一个retry装饰器捕获超时异常重试前重新定位 input 和重置表单。async function retryOnTimeout(fn, retries 3) { for (let i 0; i retries; i) { try { return await fn(); } catch (e) { if (i retries - 1) throw e; console.log(第 ${i 1} 次重试错误: ${e.message}); } } }我对重试的一个原则如果重试了 3 次还是失败大概率不是偶发问题而是业务校验不通过比如某个文件格式不对、某个必填字段没填。这种失败必须立刻暴露出来不要无限重试掩盖真实问题。因此重试日志里要输出文件路径和失败时的页面日志快照方便你事后定位。6. 常见问题排查与经验总结6.1 问题速查表现象可能原因解决方案setInputFiles 报 “File not found”路径分隔符或者文件不存在检查路径Windows 使用双反斜杠或正斜杠确认文件存在点击提交后列表没有数据input 选中了文件但表单被前置校验拦截手动操作一遍确认业务路径脚本加上表单错误提示的断言上传成功但页面弹窗没关下一个循环找不到元素状态没有拉回初始循环开头关闭弹窗等待可操作状态隐藏 input 定位不到input 在 iframe 或者 shadow DOM 里用 frameLocator 定位 iframeshadow DOM 用 piercing selector文件传了但后端收到的文件大小是 0某些组件需要先触发 change 事件再上传检查 DOM 上是否有其他属性需要设置考虑用 filechooser 事件替代并发上传后端报限流触发并发上传过多串行执行或分批控制并发数6.2 我踩过的几个典型坑第一个坑是“iframe 内 input 定位失败”。那是一个老旧的内部人资系统上传控件嵌在多层 iframe 里用普通的分页 locator 根本摸不到。当时手动操作上传是正常的但是脚本怎么都报找不到元素。最后是通过 trace viewer 一帧一帧看元素树才发现它在嵌套的 iframe 里。从那之后我遇到传统的 iframe 布局系统第一反应就是先看元素树里有没有 iframe 节点。第二个坑是“上传完成判定失效”。有个系统上传成功后会弹出一个 modal 提示成功但是 modal 里有一个“知道了”按钮不点掉的话下次定位.upload-success还是会找到旧元素。我的做法是把成功提示改成expect(...).toHaveCount(expectedCount)的精确计数这样能感知到旧元素和新元素的叠加。后来发现还是有一种情况有些系统会复用同一个成功提示元素只是改变文字内容计数根本不管用那就要改成断言具体文字比如“上传成功5/5”。第三个坑是“换浏览器环境后脚本失效”。同一个脚本在本地 Chromium 跑得好好的拿到公司服务器上的无头环境跑就卡住。后来发现是服务器上字体和本地不一样某个按钮的 CSS 变化导致点击位置偏移。这个问题的通用解法是所有点击都不要用坐标点击全部用 locator 点击让 Playwright 自己计算点击位置。如果 UI 布局不稳定再考虑用position: fixed的固定悬浮按钮时用click(force: true)绕过遮挡检查但注意这会跳过 Playwright 的“元素可点击”校验只能作为最后手段。6.3 后续扩展可能性批量上传这个基础能力其实只是开始。我后续在这个基础上还扩展过几件事一个是把上传前后的文件列表差异比对自动生成报告另一个是 CI 流水线里定时跑全量上传回归还有一个是失败文件自动移动到一个failed文件夹并打日志方便运营同事核对。如果你们团队已经有了一套接口自动化框架也可以把 Playwright 的 UI 上传和接口层面的上传做双保险。接口没法验证 UI 交互逻辑UI 没法模拟后端对数据的各种处理两者互补能把这一类“上传类”项目的可靠性拉高不少。从我的实际体会来说文件批量上传自动化是投资回报率很高的一类脚本。它不像复杂业务流程那样需要维护一大堆业务状态核心就是“定位 input、塞文件、提交、等反馈”四步循环。你只要把这四步稳定住再花点精力处理弹窗和 iframe 这类偶发因子基本上就能把这类重复劳动彻底丢掉。如果你手上刚好有这种每天都要点上传的系统不妨按这篇文章搭一个脚本试试第一次跑通时那种“终于不用再手点了”的爽快感值得体验一次。
平方复杂度无法被常规优化消除｜TaoToken 统一 Key 通道实测)
