Playwright文件上传与下载测试完全指南

文件上传和下载功能是现代Web应用中的常见需求，也是自动化测试中需要特别处理的场景。本指南将详细介绍如何使用Playwright高效、可靠地测试文件上传和下载功能。

一、文件上传测试详解

1.1 基础文件上传方法

对于大多数使用<input type="file">元素的文件上传，Playwright提供了简洁的处理方式：

// 基础文件上传示例
const { chromium } = require('playwright');

(async () => {
  const browser = await chromium.launch();
  const page = await browser.newPage();
  
  await page.goto('https://example.com/upload');
  
  // 定位文件输入元素并设置文件路径
  await page.locator('input[type="file"]').setInputFiles('./test-files/sample.pdf');
  
  // 如果需要上传多个文件
  await page.locator('input[type="file"]').setInputFiles([
    './test-files/sample1.pdf',
    './test-files/sample2.jpg'
  ]);
  
  await browser.close();
})();

1.2 处理隐藏或复杂的上传控件

有些应用使用自定义样式隐藏了原生文件输入，或者通过JavaScript实现了复杂的上传逻辑：

// 处理自定义上传组件
async function uploadFileWithCustomUI(page, filePath) {
  // 方法1：通过点击自定义按钮触发隐藏的input
  const fileInput = page.locator('.custom-upload-input');
  await fileInput.setInputFiles(filePath);
  
  // 方法2：如果input完全隐藏，使用evaluate直接设置值
  await page.evaluate((selector) => {
    const input = document.querySelector(selector);
    const dataTransfer = new DataTransfer();
    const file = new File(['test content'], 'test.txt', { type: 'text/plain' });
    dataTransfer.items.add(file);
    input.files = dataTransfer.files;
    
    // 触发change事件
    input.dispatchEvent(new Event('change', { bubbles: true }));
  }, '.hidden-input');
  
  // 等待上传完成
  await page.waitForSelector('.upload-progress', { state: 'hidden' });
}

1.3 拖放上传测试

拖放上传在现代应用中越来越常见，Playwright也能轻松模拟：

// 模拟拖放文件上传
async function dragAndDropUpload(page, filePath, dropZoneSelector) {
  // 创建数据转移对象
  const dataTransfer = await page.evaluateHandle(() => {
    const dt = new DataTransfer();
    return dt;
  });
  
  // 读取文件内容
  const fs = require('fs');
  const fileContent = fs.readFileSync(filePath, 'utf8');
  const fileName = filePath.split('/').pop();
  
  // 在页面上下文中创建File对象
  await page.evaluate(({ content, name }) => {
    const file = new File([content], name, { type: 'text/plain' });
    window.testFile = file;
  }, { content: fileContent, name: fileName });
  
  // 触发拖放事件
  await page.dispatchEvent(dropZoneSelector, 'dragenter', { dataTransfer });
  await page.dispatchEvent(dropZoneSelector, 'dragover', { dataTransfer });
  await page.dispatchEvent(dropZoneSelector, 'drop', { dataTransfer });
  
  // 等待上传完成
  await page.waitForResponse(response => 
    response.url().includes('/upload') && response.status() === 200
  );
}

1.4 大文件上传和进度监控

测试大文件上传时，需要关注上传进度和可能的超时问题：

// 大文件上传测试
async function testLargeFileUpload(page) {
  // 创建测试大文件（仅在测试环境使用）
  const fs = require('fs');
  const largeContent = '0'.repeat(1024 * 1024 * 10); // 10MB
  fs.writeFileSync('./large-test-file.txt', largeContent);
  
  // 设置更长超时时间
  page.setDefaultTimeout(60000);
  
  // 上传文件
  await page.locator('input[type="file"]').setInputFiles('./large-test-file.txt');
  
  // 监控上传进度
  const progressLogs = [];
  page.on('console', msg => {
    if (msg.text().includes('Upload progress')) {
      progressLogs.push(msg.text());
    }
  });
  
  // 等待上传完成
  await page.waitForSelector('.upload-complete', { timeout: 60000 });
  
  // 验证进度
  expect(progressLogs.length).toBeGreaterThan(0);
  
  // 清理测试文件
  fs.unlinkSync('./large-test-file.txt');
}

二、文件下载测试详解

2.1 基本下载测试流程

// 基础文件下载测试
async function testFileDownload(page) {
  // 等待下载开始
  const [download] = await Promise.all([
    page.waitForEvent('download'), // 监听下载事件
    page.click('#download-button') // 触发下载
  ]);
  
  // 获取下载信息
  console.log('下载文件名:', download.suggestedFilename());
  console.log('下载URL:', download.url());
  
  // 保存文件到指定路径
  const downloadPath = './downloads/' + download.suggestedFilename();
  await download.saveAs(downloadPath);
  
  // 验证文件是否存在
  const fs = require('fs');
  expect(fs.existsSync(downloadPath)).toBeTruthy();
  
  // 验证文件内容（如果是文本文件）
  if (downloadPath.endsWith('.txt') || downloadPath.endsWith('.csv')) {
    const fileContent = fs.readFileSync(downloadPath, 'utf8');
    expect(fileContent).toContain('expected content');
  }
  
  // 清理下载的文件
  fs.unlinkSync(downloadPath);
}

2.2 处理需要认证的下载

// 测试需要认证的下载
async function testAuthenticatedDownload(page) {
  // 设置下载路径
  const downloadPath = './test-downloads';
  
  // 配置浏览器上下文以下载文件
  const context = await browser.newContext({
    acceptDownloads: true,
    viewport: null
  });
  
  // 如果有认证要求，先登录
  await page.goto('https://example.com/login');
  await page.fill('#username', 'testuser');
  await page.fill('#password', 'testpass');
  await page.click('#login-button');
  await page.waitForURL('**/dashboard');
  
  // 触发下载并等待
  const [download] = await Promise.all([
    page.waitForEvent('download'),
    page.click('.secure-download-link')
  ]);
  
  // 处理下载文件
  const path = await download.path();
  expect(path).toBeTruthy();
  
  // 验证文件类型
  const contentType = download.url().split('.').pop();
  expect(['pdf', 'xlsx', 'docx']).toContain(contentType);
}

2.3 批量下载测试

// 批量下载测试
async function testBatchDownloads(page) {
  const downloads = [];
  
  // 监听多个下载
  page.on('download', download => {
    downloads.push(download);
  });
  
  // 触发多个下载
  const downloadLinks = await page.locator('.download-link').all();
  
  for (const link of downloadLinks) {
    await link.click();
    await page.waitForTimeout(1000); // 等待一下避免同时发起太多请求
  }
  
  // 等待所有下载开始
  await page.waitForTimeout(5000);
  
  // 处理所有下载
  const downloadPromises = downloads.map(async (download, index) => {
    const path = `./batch-downloads/file-${index}.${download.suggestedFilename().split('.').pop()}`;
    await download.saveAs(path);
    return path;
  });
  
  const downloadedPaths = await Promise.all(downloadPromises);
  
  // 验证下载数量
  expect(downloadedPaths.length).toBe(downloadLinks.length);
}

三、高级技巧与最佳实践

3.1 使用Fixture管理测试文件

// 测试文件管理
const { test, expect } = require('@playwright/test');
const fs = require('fs');
const path = require('path');

// 创建测试夹具
const testFileFixture = {
  testFilePath: null,
  
  async createTestFile(content = 'Test content', extension = 'txt') {
    const fileName = `test-${Date.now()}.${extension}`;
    const filePath = path.join(__dirname, 'temp-files', fileName);
    
    // 确保目录存在
    if (!fs.existsSync(path.dirname(filePath))) {
      fs.mkdirSync(path.dirname(filePath), { recursive: true });
    }
    
    fs.writeFileSync(filePath, content);
    this.testFilePath = filePath;
    return filePath;
  },
  
  async cleanup() {
    if (this.testFilePath && fs.existsSync(this.testFilePath)) {
      fs.unlinkSync(this.testFilePath);
    }
  }
};

// 在测试中使用
test('文件上传测试', async ({ page }) => {
  const filePath = await testFileFixture.createTestFile('Hello World', 'txt');
  
  await page.goto('/upload');
  await page.locator('input[type="file"]').setInputFiles(filePath);
  
  // 验证上传成功
  await expect(page.locator('.upload-success')).toBeVisible();
  
  await testFileFixture.cleanup();
});

3.2 处理动态文件名和内容验证

// 动态文件验证
async function validateDownloadedFile(page, expectedContent) {
  const [download] = await Promise.all([
    page.waitForEvent('download'),
    page.click('#download-dynamic')
  ]);
  
  // 使用临时文件路径
  const tempPath = await download.createReadStream();
  
  // 验证文件内容
  let downloadedContent = '';
  for await (const chunk of tempPath) {
    downloadedContent += chunk.toString();
  }
  
  // 对于JSON文件
  if (download.suggestedFilename().endsWith('.json')) {
    const jsonData = JSON.parse(downloadedContent);
    expect(jsonData).toMatchObject(expectedContent);
  }
  
  // 对于CSV文件
  if (download.suggestedFilename().endsWith('.csv')) {
    const rows = downloadedContent.split('\n');
    expect(rows.length).toBeGreaterThan(1);
  }
}

3.3 错误处理和重试机制

// 带有重试机制的上传测试
async function uploadWithRetry(page, filePath, maxRetries = 3) {
  let lastError;
  
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      console.log(`上传尝试第 ${attempt} 次`);
      
      await page.locator('input[type="file"]').setInputFiles(filePath);
      await page.waitForSelector('.upload-success', { timeout: 10000 });
      
      // 如果成功，返回
      return;
    } catch (error) {
      lastError = error;
      console.log(`第 ${attempt} 次尝试失败:`, error.message);
      
      if (attempt < maxRetries) {
        // 等待后重试
        await page.waitForTimeout(2000);
        
        // 刷新页面重新尝试
        await page.reload();
      }
    }
  }
  
  throw new Error(`上传失败，最大重试次数 ${maxRetries} 已用完: ${lastError.message}`);
}

3.4 跨浏览器测试考虑

// 跨浏览器的文件测试配置
const { chromium, firefox, webkit } = require('playwright');

const browsers = [
  { name: 'Chromium', launcher: chromium },
  { name: 'Firefox', launcher: firefox },
  { name: 'WebKit', launcher: webkit }
];

for (const browserConfig of browsers) {
  test(`文件上传测试 - ${browserConfig.name}`, async () => {
    const browser = await browserConfig.launcher.launch();
    const context = await browser.newContext({
      acceptDownloads: true,
      // 针对不同浏览器的特殊配置
      ...(browserConfig.name === 'Firefox' ? {
        extraHTTPHeaders: { 'Accept': '*/*' }
      } : {})
    });
    
    const page = await context.newPage();
    
    // 执行测试
    await testFileUpload(page);
    
    await browser.close();
  });
}

四、常见问题与解决方案

问题1：文件上传对话框无法处理

解决方案：避免尝试操作系统文件对话框，始终使用setInputFiles方法直接设置文件路径。

问题2：下载文件保存在未知位置

解决方案：始终明确指定下载路径，使用download.saveAs()方法控制保存位置。

问题3：网络速度影响测试稳定性

解决方案：适当增加超时时间，使用网络节流模拟不同网络环境。

问题4：文件内容验证复杂

解决方案：根据文件类型使用不同的验证方法，对于二进制文件可以验证文件大小和类型。

总结

Playwright提供了强大而灵活的工具来处理文件上传和下载测试。通过本指南介绍的方法，你可以：

1. 可靠地测试各种文件上传场景
2. 精确控制和验证文件下载
3. 处理复杂的真实世界用例
4. 编写稳定、可维护的文件操作测试

记住，良好的测试应该模拟真实用户行为，同时保持稳定性和可维护性。根据你的具体应用需求，适当调整和扩展这些模式，构建适合你的测试解决方案。

测试文件上传和下载功能时，始终考虑边界情况、错误处理和性能影响，这样才能确保你的应用在实际使用中表现可靠。