1# File Upload and Download Testing
2 
3> **When to use**: Testing file uploads (single, multiple, drag-and-drop), downloads (content verification, filename, type), upload progress indicators, or file type/size restrictions.
4 
5## Table of Contents
6 
71. [Downloading Files](#downloading-files)
82. [Single File Upload](#single-file-upload)
93. [Multiple File Upload](#multiple-file-upload)
104. [Drag-and-Drop Zones](#drag-and-drop-zones)
115. [File Chooser Dialog](#file-chooser-dialog)
126. [Upload Progress and Cancellation](#upload-progress-and-cancellation)
137. [Retry After Failure](#retry-after-failure)
148. [File Type and Size Restrictions](#file-type-and-size-restrictions)
159. [Image Preview](#image-preview)
1610. [Authenticated Downloads](#authenticated-downloads)
1711. [Tips](#tips)
18 
19---
20 
21## Downloading Files
22 
23### Capturing Downloads and Verifying Content
24 
25```typescript
26import { test, expect } from '@playwright/test';
27import fs from 'fs';
28import path from 'path';
29 
30test('verifies downloaded CSV content', async ({ page }) => {
31  await page.goto('/exports');
32 
33  // Set up download listener BEFORE triggering the download
34  const downloadPromise = page.waitForEvent('download');
35  await page.getByRole('link', { name: 'transactions.csv' }).click();
36 
37  const download = await downloadPromise;
38  const savePath = path.join(__dirname, '../tmp', download.suggestedFilename());
39  await download.saveAs(savePath);
40 
41  const content = fs.readFileSync(savePath, 'utf-8');
42  expect(content).toContain('id,amount,date');
43  expect(content).toContain('1001,250.00,2025-01-15');
44 
45  const rows = content.trim().split('\n');
46  expect(rows.length).toBeGreaterThan(1);
47 
48  fs.unlinkSync(savePath);
49});
50 
51test('reads download via stream without disk I/O', async ({ page }) => {
52  await page.goto('/exports');
53 
54  const downloadPromise = page.waitForEvent('download');
55  await page.getByRole('link', { name: 'transactions.csv' }).click();
56 
57  const download = await downloadPromise;
58  const readable = await download.createReadStream();
59  const chunks: Buffer[] = [];
60 
61  for await (const chunk of readable!) {
62    chunks.push(Buffer.from(chunk));
63  }
64 
65  const content = Buffer.concat(chunks).toString('utf-8');
66  expect(content).toContain('id,amount,date');
67});
68```
69 
70### Verifying Filename and Format
71 
72```typescript
73test('export filename matches selected format', async ({ page }) => {
74  await page.goto('/analytics');
75 
76  const downloadPromise = page.waitForEvent('download');
77  await page.getByRole('button', { name: 'Export PDF' }).click();
78 
79  const download = await downloadPromise;
80  expect(download.suggestedFilename()).toMatch(/^analytics-\d{4}-\d{2}-\d{2}\.pdf$/);
81});
82 
83test('format selector changes output extension', async ({ page }) => {
84  await page.goto('/analytics');
85 
86  await page.getByLabel('Format').selectOption('csv');
87  const csvDownload = page.waitForEvent('download');
88  await page.getByRole('button', { name: 'Download' }).click();
89  expect((await csvDownload).suggestedFilename()).toMatch(/\.csv$/);
90 
91  await page.getByLabel('Format').selectOption('xlsx');
92  const xlsxDownload = page.waitForEvent('download');
93  await page.getByRole('button', { name: 'Download' }).click();
94  expect((await xlsxDownload).suggestedFilename()).toMatch(/\.xlsx$/);
95});
96```
97 
98### Checking Response Headers
99 
100```typescript
101test('download response has correct MIME type', async ({ page }) => {
102  await page.goto('/analytics');
103 
104  const responsePromise = page.waitForResponse('**/api/analytics/export**');
105  const downloadPromise = page.waitForEvent('download');
106 
107  await page.getByRole('button', { name: 'Export PDF' }).click();
108 
109  const response = await responsePromise;
110  expect(response.headers()['content-type']).toContain('application/pdf');
111  expect(response.headers()['content-disposition']).toContain('attachment');
112 
113  await downloadPromise;
114});
115```
116 
117### Handling Download Failures
118 
119```typescript
120test('shows error when download fails', async ({ page }) => {
121  await page.route('**/api/analytics/export**', async (route) => {
122    await route.fulfill({
123      status: 500,
124      contentType: 'application/json',
125      body: JSON.stringify({ error: 'Generation failed' }),
126    });
127  });
128 
129  await page.goto('/analytics');
130  await page.getByRole('button', { name: 'Export PDF' }).click();
131 
132  await expect(page.getByRole('alert')).toContainText(/failed|error/i);
133});
134```
135 
136---
137 
138## Single File Upload
139 
140### From Fixture File
141 
142```typescript
143import path from 'path';
144 
145test('uploads document from fixture', async ({ page }) => {
146  await page.goto('/attachments');
147 
148  const fileInput = page.locator('input[type="file"]');
149  await fileInput.setInputFiles(path.resolve(__dirname, '../fixtures/invoice.pdf'));
150 
151  await expect(page.getByText('invoice.pdf')).toBeVisible();
152 
153  await page.getByRole('button', { name: 'Upload' }).click();
154  await expect(page.getByRole('alert')).toContainText('uploaded successfully');
155  await expect(page.getByRole('link', { name: 'invoice.pdf' })).toBeVisible();
156});
157```
158 
159### From In-Memory Buffer
160 
161```typescript
162test('uploads in-memory CSV', async ({ page }) => {
163  await page.goto('/attachments');
164 
165  const fileInput = page.locator('input[type="file"]');
166  await fileInput.setInputFiles({
167    name: 'contacts.csv',
168    mimeType: 'text/csv',
169    buffer: Buffer.from('name,email\nAlice,[email protected]\nBob,[email protected]'),
170  });
171 
172  await expect(page.getByText('contacts.csv')).toBeVisible();
173  await page.getByRole('button', { name: 'Upload' }).click();
174  await expect(page.getByRole('alert')).toContainText('uploaded successfully');
175});
176```
177 
178### Clearing Selection
179 
180```typescript
181test('clears selected file', async ({ page }) => {
182  await page.goto('/attachments');
183 
184  const fileInput = page.locator('input[type="file"]');
185  await fileInput.setInputFiles({
186    name: 'draft.txt',
187    mimeType: 'text/plain',
188    buffer: Buffer.from('draft content'),
189  });
190 
191  await expect(page.getByText('draft.txt')).toBeVisible();
192 
193  // Clear via API
194  await fileInput.setInputFiles([]);
195  await expect(page.getByText('draft.txt')).not.toBeVisible();
196});
197```
198 
199---
200 
201## Multiple File Upload
202 
203```typescript
204test('uploads multiple files at once', async ({ page }) => {
205  await page.goto('/attachments');
206 
207  const fileInput = page.locator('input[type="file"]');
208  await fileInput.setInputFiles([
209    { name: 'doc1.pdf', mimeType: 'application/pdf', buffer: Buffer.from('pdf1') },
210    { name: 'doc2.pdf', mimeType: 'application/pdf', buffer: Buffer.from('pdf2') },
211    { name: 'doc3.pdf', mimeType: 'application/pdf', buffer: Buffer.from('pdf3') },
212  ]);
213 
214  await expect(page.getByText('doc1.pdf')).toBeVisible();
215  await expect(page.getByText('doc2.pdf')).toBeVisible();
216  await expect(page.getByText('doc3.pdf')).toBeVisible();
217  await expect(page.getByText('3 files selected')).toBeVisible();
218 
219  await page.getByRole('button', { name: 'Upload all' }).click();
220  await expect(page.getByRole('alert')).toContainText('3 files uploaded');
221});
222 
223test('removes one file from selection', async ({ page }) => {
224  await page.goto('/attachments');
225 
226  const fileInput = page.locator('input[type="file"]');
227  await fileInput.setInputFiles([
228    { name: 'keep.txt', mimeType: 'text/plain', buffer: Buffer.from('keep') },
229    { name: 'discard.txt', mimeType: 'text/plain', buffer: Buffer.from('discard') },
230  ]);
231 
232  const discardRow = page.getByText('discard.txt').locator('..');
233  await discardRow.getByRole('button', { name: /remove|delete|×/i }).click();
234 
235  await expect(page.getByText('discard.txt')).not.toBeVisible();
236  await expect(page.getByText('keep.txt')).toBeVisible();
237});
238```
239 
240---
241 
242## Drag-and-Drop Zones
243 
244Drop zones always have an underlying `input[type="file"]`—target it directly instead of simulating OS-level drag events.
245 
246```typescript
247test('uploads via drop zone', async ({ page }) => {
248  await page.goto('/attachments');
249 
250  const dropZone = page.locator('[data-testid="drop-zone"]');
251  await expect(dropZone).toContainText(/drag.*here|drop.*files/i);
252 
253  const fileInput = page.locator('input[type="file"]');
254  await fileInput.setInputFiles({
255    name: 'dropped.pdf',
256    mimeType: 'application/pdf',
257    buffer: Buffer.from('pdf-content'),
258  });
259 
260  await expect(dropZone.getByText('dropped.pdf')).toBeVisible();
261  await page.getByRole('button', { name: 'Upload' }).click();
262  await expect(page.getByRole('alert')).toContainText('uploaded successfully');
263});
264 
265test('shows visual feedback on drag-over', async ({ page }) => {
266  await page.goto('/attachments');
267 
268  const dropZone = page.locator('[data-testid="drop-zone"]');
269 
270  await dropZone.dispatchEvent('dragenter', {
271    dataTransfer: { types: ['Files'], files: [] },
272  });
273 
274  await expect(dropZone).toHaveClass(/active|highlight|drag-over/);
275  await expect(dropZone).toContainText(/release|drop now/i);
276 
277  await dropZone.dispatchEvent('dragleave');
278  await expect(dropZone).not.toHaveClass(/active|highlight|drag-over/);
279});
280```
281 
282---
283 
284## File Chooser Dialog
285 
286```typescript
287test('uploads via native file chooser', async ({ page }) => {
288  await page.goto('/attachments');
289 
290  const fileChooserPromise = page.waitForEvent('filechooser');
291  await page.getByRole('button', { name: 'Choose file' }).click();
292 
293  const fileChooser = await fileChooserPromise;
294  expect(fileChooser.isMultiple()).toBe(false);
295 
296  await fileChooser.setFiles({
297    name: 'selected.pdf',
298    mimeType: 'application/pdf',
299    buffer: Buffer.from('pdf-content'),
300  });
301 
302  await expect(page.getByText('selected.pdf')).toBeVisible();
303});
304```
305 
306---
307 
308## Upload Progress and Cancellation
309 
310```typescript
311test('displays upload progress for large file', async ({ page }) => {
312  await page.goto('/attachments');
313 
314  const fileInput = page.locator('input[type="file"]');
315  const largeBuffer = Buffer.alloc(5 * 1024 * 1024, 'x');
316 
317  await fileInput.setInputFiles({
318    name: 'dataset.bin',
319    mimeType: 'application/octet-stream',
320    buffer: largeBuffer,
321  });
322 
323  await page.getByRole('button', { name: 'Upload' }).click();
324 
325  const progressBar = page.getByRole('progressbar');
326  await expect(progressBar).toBeVisible();
327 
328  await expect(async () => {
329    const value = await progressBar.getAttribute('aria-valuenow');
330    expect(Number(value)).toBeGreaterThan(0);
331  }).toPass({ timeout: 10000 });
332 
333  await expect(progressBar).not.toBeVisible({ timeout: 60000 });
334  await expect(page.getByRole('alert')).toContainText('uploaded successfully');
335});
336 
337test('cancels in-progress upload', async ({ page }) => {
338  await page.route('**/api/attachments/upload', async (route) => {
339    await new Promise((resolve) => setTimeout(resolve, 10000));
340    await route.continue();
341  });
342 
343  await page.goto('/attachments');
344 
345  const fileInput = page.locator('input[type="file"]');
346  await fileInput.setInputFiles({
347    name: 'large.bin',
348    mimeType: 'application/octet-stream',
349    buffer: Buffer.alloc(5 * 1024 * 1024, 'x'),
350  });
351 
352  await page.getByRole('button', { name: 'Upload' }).click();
353  await expect(page.getByRole('progressbar')).toBeVisible();
354 
355  await page.getByRole('button', { name: 'Cancel upload' }).click();
356 
357  await expect(page.getByRole('progressbar')).not.toBeVisible();
358  await expect(page.getByText(/cancelled|aborted/i)).toBeVisible();
359  await expect(page.getByRole('link', { name: 'large.bin' })).not.toBeVisible();
360});
361```
362 
363---
364 
365## Retry After Failure
366 
367```typescript
368test('retries failed upload', async ({ page }) => {
369  let attempt = 0;
370 
371  await page.route('**/api/attachments/upload', async (route) => {
372    attempt++;
373    if (attempt === 1) {
374      await route.fulfill({
375        status: 500,
376        contentType: 'application/json',
377        body: JSON.stringify({ error: 'Server error' }),
378      });
379    } else {
380      await route.fulfill({
381        status: 200,
382        contentType: 'application/json',
383        body: JSON.stringify({ id: 'abc', name: 'data.csv' }),
384      });
385    }
386  });
387 
388  await page.goto('/attachments');
389 
390  const fileInput = page.locator('input[type="file"]');
391  await fileInput.setInputFiles({
392    name: 'data.csv',
393    mimeType: 'text/csv',
394    buffer: Buffer.from('col1,col2\nval1,val2'),
395  });
396 
397  await page.getByRole('button', { name: 'Upload' }).click();
398  await expect(page.getByText(/upload failed|error/i)).toBeVisible();
399 
400  await page.getByRole('button', { name: /retry/i }).click();
401  await expect(page.getByRole('alert')).toContainText('uploaded successfully');
402  expect(attempt).toBe(2);
403});
404```
405 
406---
407 
408## File Type and Size Restrictions
409 
410### Validating Allowed Types
411 
412```typescript
413test('accepts allowed file types', async ({ page }) => {
414  await page.goto('/attachments');
415 
416  const fileInput = page.locator('input[type="file"]');
417  await expect(fileInput).toHaveAttribute('accept', /\.pdf|\.doc|\.docx|\.txt/);
418 
419  await fileInput.setInputFiles({
420    name: 'report.pdf',
421    mimeType: 'application/pdf',
422    buffer: Buffer.from('pdf-content'),
423  });
424 
425  await expect(page.getByText('report.pdf')).toBeVisible();
426  await expect(page.getByText(/not allowed|invalid/i)).not.toBeVisible();
427});
428 
429test('rejects disallowed file types', async ({ page }) => {
430  await page.goto('/attachments');
431 
432  const fileInput = page.locator('input[type="file"]');
433  // setInputFiles bypasses the accept attribute—tests JavaScript validation
434  await fileInput.setInputFiles({
435    name: 'malware.exe',
436    mimeType: 'application/x-msdownload',
437    buffer: Buffer.from('exe-content'),
438  });
439 
440  await expect(page.getByRole('alert')).toContainText(
441    /not allowed|unsupported file type|only .pdf, .doc/i
442  );
443  await expect(page.getByText('malware.exe')).not.toBeVisible();
444});
445```
446 
447### Enforcing Size Limits
448 
449```typescript
450test('rejects oversized file', async ({ page }) => {
451  await page.goto('/attachments');
452 
453  const fileInput = page.locator('input[type="file"]');
454  const oversizedBuffer = Buffer.alloc(11 * 1024 * 1024, 'x');
455 
456  await fileInput.setInputFiles({
457    name: 'huge.pdf',
458    mimeType: 'application/pdf',
459    buffer: oversizedBuffer,
460  });
461 
462  await expect(page.getByRole('alert')).toContainText(/file.*too large|exceeds.*10 ?MB/i);
463  await expect(page.getByText('huge.pdf')).not.toBeVisible();
464});
465```
466 
467### Enforcing File Count Limits
468 
469```typescript
470test('rejects too many files', async ({ page }) => {
471  await page.goto('/attachments');
472 
473  const fileInput = page.locator('input[type="file"]');
474  const files = Array.from({ length: 6 }, (_, i) => ({
475    name: `file-${i + 1}.txt`,
476    mimeType: 'text/plain' as const,
477    buffer: Buffer.from(`content ${i + 1}`),
478  }));
479 
480  await fileInput.setInputFiles(files);
481 
482  await expect(page.getByRole('alert')).toContainText(/maximum.*5 files|too many files/i);
483});
484```
485 
486### Validating Image Dimensions
487 
488```typescript
489test('rejects image below minimum dimensions', async ({ page }) => {
490  await page.goto('/profile/avatar');
491 
492  const fileInput = page.locator('input[type="file"]');
493  // Minimal 1x1 PNG
494  const tinyPng = Buffer.from(
495    'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==',
496    'base64'
497  );
498 
499  await fileInput.setInputFiles({
500    name: 'tiny.png',
501    mimeType: 'image/png',
502    buffer: tinyPng,
503  });
504 
505  await expect(page.getByRole('alert')).toContainText(/minimum.*dimensions|too small/i);
506});
507```
508 
509---
510 
511## Image Preview
512 
513```typescript
514test('shows image preview after selection', async ({ page }) => {
515  await page.goto('/profile/avatar');
516 
517  const fileInput = page.locator('input[type="file"]');
518  await fileInput.setInputFiles(path.resolve(__dirname, '../fixtures/photo.jpg'));
519 
520  const preview = page.getByRole('img', { name: /preview|avatar/i });
521  await expect(preview).toBeVisible();
522 
523  const src = await preview.getAttribute('src');
524  expect(src).toMatch(/^(blob:|data:image)/);
525});
526```
527 
528---
529 
530## Authenticated Downloads
531 
532```typescript
533test('downloads file requiring authentication', async ({ page, request }) => {
534  await page.goto('/attachments');
535 
536  // Browser download works because cookies are sent
537  const downloadPromise = page.waitForEvent('download');
538  await page.getByRole('link', { name: 'confidential.pdf' }).click();
539 
540  const download = await downloadPromise;
541  expect(download.suggestedFilename()).toBe('confidential.pdf');
542 
543  // Verify via API request (carries auth context)
544  const response = await request.get('/api/attachments/456/download');
545  expect(response.ok()).toBeTruthy();
546  expect(response.headers()['content-type']).toContain('application/pdf');
547});
548```
549 
550---
551 
552## Tips
553 
5541. **Use `setInputFiles` for uploads**. Even drag-and-drop zones have an underlying `input[type="file"]`. Target it directly instead of simulating OS-level drag events.
555 
5562. **Prefer in-memory buffers**. Creating files with `Buffer.from()` keeps tests self-contained. Use fixture files only when you need real content (e.g., a valid PDF your app parses).
557 
5583. **Set up download listener before clicking**. Call `page.waitForEvent('download')` before the click that triggers the download—otherwise you may miss the event.
559 
5604. **Use `createReadStream()` for content verification**. Reading directly from the stream avoids disk I/O and cleanup of temporary files.
561 
5625. **Test both `accept` attribute and JavaScript validation**. The HTML `accept` attribute only filters the OS file dialog. `setInputFiles()` bypasses it, which is exactly what you need to test your app's JavaScript validation.
563