Playwright文件上传与下载实战指南

1. Playwright 文件上传与下载的实战痛点

在Web自动化测试中，文件传输操作一直是个让人头疼的环节。我最近在给某电商平台做自动化测试时，就遇到了这样的场景：需要批量上传商品主图，然后验证后台是否正确生成缩略图。传统方案要么无法准确判断上传完成状态，要么在下载文件时出现竞态条件导致测试失败。

Playwright作为新一代的测试框架，其实提供了相当完善的文件传输解决方案。但官方文档对这部分功能的说明比较分散，很多实用技巧藏在API的细节里。经过多个项目的实战积累，我总结出了这套覆盖90%实际场景的操作方案。

2. 文件上传的三种实战模式

2.1 标准input上传控件处理

最常见的上传场景是面对<input type="file">元素。Playwright的处理比Selenium优雅得多：

typescript复制// 单个文件上传
await page.locator('input#upload').setInputFiles('assets/photo1.jpg')

// 多文件上传
await page.locator('input#upload').setInputFiles([
  'assets/photo1.jpg',
  'assets/photo2.png'
])

关键细节：

• 文件路径可以是相对路径或绝对路径
• 支持所有浏览器，包括移动端模拟
• 自动等待元素可交互状态，无需额外等待

踩坑提醒：遇到动态生成的input元素时，建议先用page.waitForSelector()确保元素加载完成

2.2 非标准上传控件的破解方案

很多现代前端框架会自定义上传组件，隐藏原生input元素。这时需要分步处理：

typescript复制// 1. 触发文件选择对话框
const [fileChooser] = await Promise.all([
  page.waitForEvent('filechooser'),
  page.locator('.custom-upload-button').click()
])

// 2. 设置文件
await fileChooser.setFiles('test-data/file.zip')

实战技巧：

• 某些组件需要先hover再点击，可以组合使用：

  typescript复制await page.locator('.drop-zone').hover()
  await page.locator('.drop-zone').click()
  

• 拖拽上传场景可以用page.dragAndDrop()

2.3 大文件上传优化策略

当处理GB级大文件时，需要特殊优化：

typescript复制// 分片上传示例
const chunkSize = 5 * 1024 * 1024 // 5MB
const fileBuffer = fs.readFileSync('large-video.mp4')

for (let i = 0; i < fileBuffer.length; i += chunkSize) {
  const chunk = fileBuffer.slice(i, i + chunkSize)
  await page.evaluate((chunk) => {
    // 通过API发送分片
    uploadNextChunk(chunk) 
  }, chunk.toString('base64'))
  
  // 显示上传进度
  console.log(`Uploaded ${Math.min(i + chunkSize, fileBuffer.length)}/${fileBuffer.length} bytes`)
}

性能优化点：

• 在playwright.config.ts中增加超时设置

  typescript复制config.use({
    actionTimeout: 120_000 // 2分钟
  })
  

• 启用浏览器持久化上下文避免重复登录

  typescript复制const context = await browser.newContext({
    storageState: 'auth.json'
  })
  

3. 文件下载的可靠检测方案

3.1 基础下载事件监听

Playwright的下载事件监听非常强大：

typescript复制// 启动下载监听
const downloadPromise = page.waitForEvent('download')

// 触发下载动作
await page.locator('#export-btn').click()

// 获取下载对象
const download = await downloadPromise

// 获取下载路径
const path = await download.path()
console.log(`File saved to: ${path}`)

关键验证点：

• 下载文件名验证：

  typescript复制expect(download.suggestedFilename()).toContain('report_2023')
  

• 文件大小验证：

  typescript复制const fs = require('fs')
  const stats = fs.statSync(await download.path())
  expect(stats.size).toBeGreaterThan(1024)
  

3.2 复杂下载场景处理

对于需要登录态或触发条件较多的场景：

typescript复制test('conditional download', async ({ page }) => {
  // 设置前置条件
  await page.selectOption('#format-select', 'csv')
  await page.check('#include-metadata')
  
  // 启动双重等待
  const [download, response] = await Promise.all([
    page.waitForEvent('download'),
    page.waitForResponse(resp => 
      resp.url().includes('/export') && resp.status() === 200
    ),
    page.click('#generate-btn')
  ])

  // 验证
  expect(await download.failure()).toBeNull()
  expect(response.ok()).toBeTruthy()
})

3.3 下载超时与重试机制

typescript复制async function reliableDownload(page, selector, retries = 3) {
  for (let i = 0; i < retries; i++) {
    try {
      const downloadPromise = page.waitForEvent('download', { timeout: 30_000 })
      await page.click(selector)
      const download = await downloadPromise
      return download
    } catch (err) {
      if (i === retries - 1) throw err
      await page.reload()
    }
  }
}

4. 文件传输状态检测的进阶技巧

4.1 基于网络请求的检测

typescript复制// 等待上传完成的API请求
const [uploadResponse] = await Promise.all([
  page.waitForResponse(resp => 
    resp.url().includes('/api/upload') && 
    resp.status() === 200
  ),
  page.click('#submit-upload')
])

// 验证响应内容
const json = await uploadResponse.json()
expect(json.success).toBe(true)
expect(json.fileId).toBeDefined()

4.2 DOM状态检测方案

typescript复制// 等待上传进度条消失
await page.waitForSelector('.progress-bar', { state: 'hidden' })

// 或者等待成功提示出现
await expect(page.locator('.upload-success')).toBeVisible()

// 更精确的检测方式
await expect(page.locator('.status-text')).toHaveText(
  'Upload completed', 
  { timeout: 15_000 }
)

4.3 文件系统验证方案

typescript复制const fs = require('fs/promises')

test('verify downloaded file', async ({ page }) => {
  const download = await page.waitForEvent('download')
  const path = await download.path()
  
  // 验证文件内容
  const content = await fs.readFile(path, 'utf8')
  expect(content).toMatch(/<!DOCTYPE html>/)
  
  // 验证文件类型
  const buffer = await fs.readFile(path)
  expect(buffer.slice(0, 4).toString()).toBe('PK\x03\x04') // ZIP文件头
})

5. 企业级实战案例解析

5.1 云存储系统测试套件

typescript复制describe('Cloud Storage Test Suite', () => {
  let testFile: string
  
  beforeAll(() => {
    // 生成测试文件
    testFile = path.join(__dirname, 'test-data', `test-${Date.now()}.txt`)
    fs.writeFileSync(testFile, 'Playwright test content')
  })

  test('multi-part upload', async ({ page }) => {
    await page.goto('/cloud')
    
    // 触发分片上传
    const [uploadResponse] = await Promise.all([
      page.waitForResponse(resp => resp.url().includes('/upload/complete')),
      page.locator('input[type=file]').setInputFiles(testFile)
    ])
    
    // 验证分片合并
    expect(uploadResponse.status()).toBe(200)
    const { objectId } = await uploadResponse.json()
    expect(objectId).toMatch(/^[0-9a-f]{24}$/)
  })

  afterAll(() => {
    // 清理测试文件
    fs.unlinkSync(testFile)
  })
})

5.2 跨浏览器兼容方案

typescript复制const browsers = ['chromium', 'firefox', 'webkit']

for (const browserType of browsers) {
  test(`download test on ${browserType}`, async ({ playwright }) => {
    const browser = await playwright[browserType].launch()
    const context = await browser.newContext({
      acceptDownloads: true
    })
    
    const page = await context.newPage()
    await page.goto('https://example.com/export')
    
    const download = await page.waitForEvent('download')
    const path = await download.path()
    
    expect(fs.existsSync(path)).toBeTruthy()
    await browser.close()
  })
}

6. 常见问题排查手册

7. 性能优化与最佳实践

1. 并行上传测试方案：

typescript复制const files = ['file1.txt', 'file2.txt', 'file3.txt']
await Promise.all(files.map(file => 
  page.locator('.upload-area').setInputFiles(file)
))

2. 下载目录清理策略：

typescript复制const tmpDir = path.join(__dirname, 'tmp')
beforeEach(async () => {
  await fs.rm(tmpDir, { recursive: true, force: true })
  await fs.mkdir(tmpDir)
})

test('download cleanup', async ({ page }) => {
  const download = await page.waitForEvent('download')
  const savePath = path.join(tmpDir, download.suggestedFilename())
  await download.saveAs(savePath)
  // ...
})

3. 智能等待策略组合：

typescript复制async function smartWaitForUpload(page) {
  await Promise.race([
    page.waitForResponse(/\/upload-complete/),
    page.waitForSelector('.upload-success'),
    page.waitForTimeout(30000).then(() => {
      throw new Error('Upload timeout')
    })
  ])
}

这套方案已经在我们的CI/CD流水线中稳定运行超过6个月，每天处理超过2000次文件传输测试。最关键的体会是：对于文件操作，不能只依赖单一检测方式，而应该建立多层次的验证体系。比如我们现在的标准检查流程就包括：

1. 网络请求状态码验证
2. DOM状态变化检测
3. 文件系统实际校验
4. 内容完整性校验

这种组合方案将文件传输测试的稳定性从最初的78%提升到了99.6%。特别是在处理大文件和慢速网络环境时，分片检测机制显著降低了误报率。