@arcadialdev/arcality 2.2.0

package/.agents/skills/playwright-best-practices/testing-patterns/file-upload-download.md

@@ -0,0 +1,562 @@
+# File Upload and Download Testing
+
+> **When to use**: Testing file uploads (single, multiple, drag-and-drop), downloads (content verification, filename, type), upload progress indicators, or file type/size restrictions.
+
+## Table of Contents
+
+1. [Downloading Files](#downloading-files)
+2. [Single File Upload](#single-file-upload)
+3. [Multiple File Upload](#multiple-file-upload)
+4. [Drag-and-Drop Zones](#drag-and-drop-zones)
+5. [File Chooser Dialog](#file-chooser-dialog)
+6. [Upload Progress and Cancellation](#upload-progress-and-cancellation)
+7. [Retry After Failure](#retry-after-failure)
+8. [File Type and Size Restrictions](#file-type-and-size-restrictions)
+9. [Image Preview](#image-preview)
+10. [Authenticated Downloads](#authenticated-downloads)
+11. [Tips](#tips)
+
+---
+
+## Downloading Files
+
+### Capturing Downloads and Verifying Content
+
+```typescript
+import { test, expect } from '@playwright/test';
+import fs from 'fs';
+import path from 'path';
+
+test('verifies downloaded CSV content', async ({ page }) => {
+  await page.goto('/exports');
+
+  // Set up download listener BEFORE triggering the download
+  const downloadPromise = page.waitForEvent('download');
+  await page.getByRole('link', { name: 'transactions.csv' }).click();
+
+  const download = await downloadPromise;
+  const savePath = path.join(__dirname, '../tmp', download.suggestedFilename());
+  await download.saveAs(savePath);
+
+  const content = fs.readFileSync(savePath, 'utf-8');
+  expect(content).toContain('id,amount,date');
+  expect(content).toContain('1001,250.00,2025-01-15');
+
+  const rows = content.trim().split('\n');
+  expect(rows.length).toBeGreaterThan(1);
+
+  fs.unlinkSync(savePath);
+});
+
+test('reads download via stream without disk I/O', async ({ page }) => {
+  await page.goto('/exports');
+
+  const downloadPromise = page.waitForEvent('download');
+  await page.getByRole('link', { name: 'transactions.csv' }).click();
+
+  const download = await downloadPromise;
+  const readable = await download.createReadStream();
+  const chunks: Buffer[] = [];
+
+  for await (const chunk of readable!) {
+    chunks.push(Buffer.from(chunk));
+  }
+
+  const content = Buffer.concat(chunks).toString('utf-8');
+  expect(content).toContain('id,amount,date');
+});
+```
+
+### Verifying Filename and Format
+
+```typescript
+test('export filename matches selected format', async ({ page }) => {
+  await page.goto('/analytics');
+
+  const downloadPromise = page.waitForEvent('download');
+  await page.getByRole('button', { name: 'Export PDF' }).click();
+
+  const download = await downloadPromise;
+  expect(download.suggestedFilename()).toMatch(/^analytics-\d{4}-\d{2}-\d{2}\.pdf$/);
+});
+
+test('format selector changes output extension', async ({ page }) => {
+  await page.goto('/analytics');
+
+  await page.getByLabel('Format').selectOption('csv');
+  const csvDownload = page.waitForEvent('download');
+  await page.getByRole('button', { name: 'Download' }).click();
+  expect((await csvDownload).suggestedFilename()).toMatch(/\.csv$/);
+
+  await page.getByLabel('Format').selectOption('xlsx');
+  const xlsxDownload = page.waitForEvent('download');
+  await page.getByRole('button', { name: 'Download' }).click();
+  expect((await xlsxDownload).suggestedFilename()).toMatch(/\.xlsx$/);
+});
+```
+
+### Checking Response Headers
+
+```typescript
+test('download response has correct MIME type', async ({ page }) => {
+  await page.goto('/analytics');
+
+  const responsePromise = page.waitForResponse('**/api/analytics/export**');
+  const downloadPromise = page.waitForEvent('download');
+
+  await page.getByRole('button', { name: 'Export PDF' }).click();
+
+  const response = await responsePromise;
+  expect(response.headers()['content-type']).toContain('application/pdf');
+  expect(response.headers()['content-disposition']).toContain('attachment');
+
+  await downloadPromise;
+});
+```
+
+### Handling Download Failures
+
+```typescript
+test('shows error when download fails', async ({ page }) => {
+  await page.route('**/api/analytics/export**', async (route) => {
+    await route.fulfill({
+      status: 500,
+      contentType: 'application/json',
+      body: JSON.stringify({ error: 'Generation failed' }),
+    });
+  });
+
+  await page.goto('/analytics');
+  await page.getByRole('button', { name: 'Export PDF' }).click();
+
+  await expect(page.getByRole('alert')).toContainText(/failed|error/i);
+});
+```
+
+---
+
+## Single File Upload
+
+### From Fixture File
+
+```typescript
+import path from 'path';
+
+test('uploads document from fixture', async ({ page }) => {
+  await page.goto('/attachments');
+
+  const fileInput = page.locator('input[type="file"]');
+  await fileInput.setInputFiles(path.resolve(__dirname, '../fixtures/invoice.pdf'));
+
+  await expect(page.getByText('invoice.pdf')).toBeVisible();
+
+  await page.getByRole('button', { name: 'Upload' }).click();
+  await expect(page.getByRole('alert')).toContainText('uploaded successfully');
+  await expect(page.getByRole('link', { name: 'invoice.pdf' })).toBeVisible();
+});
+```
+
+### From In-Memory Buffer
+
+```typescript
+test('uploads in-memory CSV', async ({ page }) => {
+  await page.goto('/attachments');
+
+  const fileInput = page.locator('input[type="file"]');
+  await fileInput.setInputFiles({
+    name: 'contacts.csv',
+    mimeType: 'text/csv',
+    buffer: Buffer.from('name,email\nAlice,alice@acme.com\nBob,bob@acme.com'),
+  });
+
+  await expect(page.getByText('contacts.csv')).toBeVisible();
+  await page.getByRole('button', { name: 'Upload' }).click();
+  await expect(page.getByRole('alert')).toContainText('uploaded successfully');
+});
+```
+
+### Clearing Selection
+
+```typescript
+test('clears selected file', async ({ page }) => {
+  await page.goto('/attachments');
+
+  const fileInput = page.locator('input[type="file"]');
+  await fileInput.setInputFiles({
+    name: 'draft.txt',
+    mimeType: 'text/plain',
+    buffer: Buffer.from('draft content'),
+  });
+
+  await expect(page.getByText('draft.txt')).toBeVisible();
+
+  // Clear via API
+  await fileInput.setInputFiles([]);
+  await expect(page.getByText('draft.txt')).not.toBeVisible();
+});
+```
+
+---
+
+## Multiple File Upload
+
+```typescript
+test('uploads multiple files at once', async ({ page }) => {
+  await page.goto('/attachments');
+
+  const fileInput = page.locator('input[type="file"]');
+  await fileInput.setInputFiles([
+    { name: 'doc1.pdf', mimeType: 'application/pdf', buffer: Buffer.from('pdf1') },
+    { name: 'doc2.pdf', mimeType: 'application/pdf', buffer: Buffer.from('pdf2') },
+    { name: 'doc3.pdf', mimeType: 'application/pdf', buffer: Buffer.from('pdf3') },
+  ]);
+
+  await expect(page.getByText('doc1.pdf')).toBeVisible();
+  await expect(page.getByText('doc2.pdf')).toBeVisible();
+  await expect(page.getByText('doc3.pdf')).toBeVisible();
+  await expect(page.getByText('3 files selected')).toBeVisible();
+
+  await page.getByRole('button', { name: 'Upload all' }).click();
+  await expect(page.getByRole('alert')).toContainText('3 files uploaded');
+});
+
+test('removes one file from selection', async ({ page }) => {
+  await page.goto('/attachments');
+
+  const fileInput = page.locator('input[type="file"]');
+  await fileInput.setInputFiles([
+    { name: 'keep.txt', mimeType: 'text/plain', buffer: Buffer.from('keep') },
+    { name: 'discard.txt', mimeType: 'text/plain', buffer: Buffer.from('discard') },
+  ]);
+
+  const discardRow = page.getByText('discard.txt').locator('..');
+  await discardRow.getByRole('button', { name: /remove|delete|×/i }).click();
+
+  await expect(page.getByText('discard.txt')).not.toBeVisible();
+  await expect(page.getByText('keep.txt')).toBeVisible();
+});
+```
+
+---
+
+## Drag-and-Drop Zones
+
+Drop zones always have an underlying `input[type="file"]`—target it directly instead of simulating OS-level drag events.
+
+```typescript
+test('uploads via drop zone', async ({ page }) => {
+  await page.goto('/attachments');
+
+  const dropZone = page.locator('[data-testid="drop-zone"]');
+  await expect(dropZone).toContainText(/drag.*here|drop.*files/i);
+
+  const fileInput = page.locator('input[type="file"]');
+  await fileInput.setInputFiles({
+    name: 'dropped.pdf',
+    mimeType: 'application/pdf',
+    buffer: Buffer.from('pdf-content'),
+  });
+
+  await expect(dropZone.getByText('dropped.pdf')).toBeVisible();
+  await page.getByRole('button', { name: 'Upload' }).click();
+  await expect(page.getByRole('alert')).toContainText('uploaded successfully');
+});
+
+test('shows visual feedback on drag-over', async ({ page }) => {
+  await page.goto('/attachments');
+
+  const dropZone = page.locator('[data-testid="drop-zone"]');
+
+  await dropZone.dispatchEvent('dragenter', {
+    dataTransfer: { types: ['Files'], files: [] },
+  });
+
+  await expect(dropZone).toHaveClass(/active|highlight|drag-over/);
+  await expect(dropZone).toContainText(/release|drop now/i);
+
+  await dropZone.dispatchEvent('dragleave');
+  await expect(dropZone).not.toHaveClass(/active|highlight|drag-over/);
+});
+```
+
+---
+
+## File Chooser Dialog
+
+```typescript
+test('uploads via native file chooser', async ({ page }) => {
+  await page.goto('/attachments');
+
+  const fileChooserPromise = page.waitForEvent('filechooser');
+  await page.getByRole('button', { name: 'Choose file' }).click();
+
+  const fileChooser = await fileChooserPromise;
+  expect(fileChooser.isMultiple()).toBe(false);
+
+  await fileChooser.setFiles({
+    name: 'selected.pdf',
+    mimeType: 'application/pdf',
+    buffer: Buffer.from('pdf-content'),
+  });
+
+  await expect(page.getByText('selected.pdf')).toBeVisible();
+});
+```
+
+---
+
+## Upload Progress and Cancellation
+
+```typescript
+test('displays upload progress for large file', async ({ page }) => {
+  await page.goto('/attachments');
+
+  const fileInput = page.locator('input[type="file"]');
+  const largeBuffer = Buffer.alloc(5 * 1024 * 1024, 'x');
+
+  await fileInput.setInputFiles({
+    name: 'dataset.bin',
+    mimeType: 'application/octet-stream',
+    buffer: largeBuffer,
+  });
+
+  await page.getByRole('button', { name: 'Upload' }).click();
+
+  const progressBar = page.getByRole('progressbar');
+  await expect(progressBar).toBeVisible();
+
+  await expect(async () => {
+    const value = await progressBar.getAttribute('aria-valuenow');
+    expect(Number(value)).toBeGreaterThan(0);
+  }).toPass({ timeout: 10000 });
+
+  await expect(progressBar).not.toBeVisible({ timeout: 60000 });
+  await expect(page.getByRole('alert')).toContainText('uploaded successfully');
+});
+
+test('cancels in-progress upload', async ({ page }) => {
+  await page.route('**/api/attachments/upload', async (route) => {
+    await new Promise((resolve) => setTimeout(resolve, 10000));
+    await route.continue();
+  });
+
+  await page.goto('/attachments');
+
+  const fileInput = page.locator('input[type="file"]');
+  await fileInput.setInputFiles({
+    name: 'large.bin',
+    mimeType: 'application/octet-stream',
+    buffer: Buffer.alloc(5 * 1024 * 1024, 'x'),
+  });
+
+  await page.getByRole('button', { name: 'Upload' }).click();
+  await expect(page.getByRole('progressbar')).toBeVisible();
+
+  await page.getByRole('button', { name: 'Cancel upload' }).click();
+
+  await expect(page.getByRole('progressbar')).not.toBeVisible();
+  await expect(page.getByText(/cancelled|aborted/i)).toBeVisible();
+  await expect(page.getByRole('link', { name: 'large.bin' })).not.toBeVisible();
+});
+```
+
+---
+
+## Retry After Failure
+
+```typescript
+test('retries failed upload', async ({ page }) => {
+  let attempt = 0;
+
+  await page.route('**/api/attachments/upload', async (route) => {
+    attempt++;
+    if (attempt === 1) {
+      await route.fulfill({
+        status: 500,
+        contentType: 'application/json',
+        body: JSON.stringify({ error: 'Server error' }),
+      });
+    } else {
+      await route.fulfill({
+        status: 200,
+        contentType: 'application/json',
+        body: JSON.stringify({ id: 'abc', name: 'data.csv' }),
+      });
+    }
+  });
+
+  await page.goto('/attachments');
+
+  const fileInput = page.locator('input[type="file"]');
+  await fileInput.setInputFiles({
+    name: 'data.csv',
+    mimeType: 'text/csv',
+    buffer: Buffer.from('col1,col2\nval1,val2'),
+  });
+
+  await page.getByRole('button', { name: 'Upload' }).click();
+  await expect(page.getByText(/upload failed|error/i)).toBeVisible();
+
+  await page.getByRole('button', { name: /retry/i }).click();
+  await expect(page.getByRole('alert')).toContainText('uploaded successfully');
+  expect(attempt).toBe(2);
+});
+```
+
+---
+
+## File Type and Size Restrictions
+
+### Validating Allowed Types
+
+```typescript
+test('accepts allowed file types', async ({ page }) => {
+  await page.goto('/attachments');
+
+  const fileInput = page.locator('input[type="file"]');
+  await expect(fileInput).toHaveAttribute('accept', /\.pdf|\.doc|\.docx|\.txt/);
+
+  await fileInput.setInputFiles({
+    name: 'report.pdf',
+    mimeType: 'application/pdf',
+    buffer: Buffer.from('pdf-content'),
+  });
+
+  await expect(page.getByText('report.pdf')).toBeVisible();
+  await expect(page.getByText(/not allowed|invalid/i)).not.toBeVisible();
+});
+
+test('rejects disallowed file types', async ({ page }) => {
+  await page.goto('/attachments');
+
+  const fileInput = page.locator('input[type="file"]');
+  // setInputFiles bypasses the accept attribute—tests JavaScript validation
+  await fileInput.setInputFiles({
+    name: 'malware.exe',
+    mimeType: 'application/x-msdownload',
+    buffer: Buffer.from('exe-content'),
+  });
+
+  await expect(page.getByRole('alert')).toContainText(
+    /not allowed|unsupported file type|only .pdf, .doc/i
+  );
+  await expect(page.getByText('malware.exe')).not.toBeVisible();
+});
+```
+
+### Enforcing Size Limits
+
+```typescript
+test('rejects oversized file', async ({ page }) => {
+  await page.goto('/attachments');
+
+  const fileInput = page.locator('input[type="file"]');
+  const oversizedBuffer = Buffer.alloc(11 * 1024 * 1024, 'x');
+
+  await fileInput.setInputFiles({
+    name: 'huge.pdf',
+    mimeType: 'application/pdf',
+    buffer: oversizedBuffer,
+  });
+
+  await expect(page.getByRole('alert')).toContainText(/file.*too large|exceeds.*10 ?MB/i);
+  await expect(page.getByText('huge.pdf')).not.toBeVisible();
+});
+```
+
+### Enforcing File Count Limits
+
+```typescript
+test('rejects too many files', async ({ page }) => {
+  await page.goto('/attachments');
+
+  const fileInput = page.locator('input[type="file"]');
+  const files = Array.from({ length: 6 }, (_, i) => ({
+    name: `file-${i + 1}.txt`,
+    mimeType: 'text/plain' as const,
+    buffer: Buffer.from(`content ${i + 1}`),
+  }));
+
+  await fileInput.setInputFiles(files);
+
+  await expect(page.getByRole('alert')).toContainText(/maximum.*5 files|too many files/i);
+});
+```
+
+### Validating Image Dimensions
+
+```typescript
+test('rejects image below minimum dimensions', async ({ page }) => {
+  await page.goto('/profile/avatar');
+
+  const fileInput = page.locator('input[type="file"]');
+  // Minimal 1x1 PNG
+  const tinyPng = Buffer.from(
+    'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==',
+    'base64'
+  );
+
+  await fileInput.setInputFiles({
+    name: 'tiny.png',
+    mimeType: 'image/png',
+    buffer: tinyPng,
+  });
+
+  await expect(page.getByRole('alert')).toContainText(/minimum.*dimensions|too small/i);
+});
+```
+
+---
+
+## Image Preview
+
+```typescript
+test('shows image preview after selection', async ({ page }) => {
+  await page.goto('/profile/avatar');
+
+  const fileInput = page.locator('input[type="file"]');
+  await fileInput.setInputFiles(path.resolve(__dirname, '../fixtures/photo.jpg'));
+
+  const preview = page.getByRole('img', { name: /preview|avatar/i });
+  await expect(preview).toBeVisible();
+
+  const src = await preview.getAttribute('src');
+  expect(src).toMatch(/^(blob:|data:image)/);
+});
+```
+
+---
+
+## Authenticated Downloads
+
+```typescript
+test('downloads file requiring authentication', async ({ page, request }) => {
+  await page.goto('/attachments');
+
+  // Browser download works because cookies are sent
+  const downloadPromise = page.waitForEvent('download');
+  await page.getByRole('link', { name: 'confidential.pdf' }).click();
+
+  const download = await downloadPromise;
+  expect(download.suggestedFilename()).toBe('confidential.pdf');
+
+  // Verify via API request (carries auth context)
+  const response = await request.get('/api/attachments/456/download');
+  expect(response.ok()).toBeTruthy();
+  expect(response.headers()['content-type']).toContain('application/pdf');
+});
+```
+
+---
+
+## Tips
+
+1. **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.
+
+2. **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).
+
+3. **Set up download listener before clicking**. Call `page.waitForEvent('download')` before the click that triggers the download—otherwise you may miss the event.
+
+4. **Use `createReadStream()` for content verification**. Reading directly from the stream avoids disk I/O and cleanup of temporary files.
+
+5. **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.