@assertrx/dino 1.0.0

package/skills/playwright-core/file-operations.md

@@ -0,0 +1,749 @@
+# File Operations
+
+> **When to use**: Testing file uploads, downloads, drag-and-drop file interactions, file type validation, and download verification.
+> **Prerequisites**: [core/locators.md](locators.md), [core/assertions-and-waiting.md](assertions-and-waiting.md)
+
+## Quick Reference
+
+```typescript
+// Upload — single file
+await page.getByLabel('Upload').setInputFiles('fixtures/resume.pdf');
+
+// Upload — multiple files
+await page.getByLabel('Upload').setInputFiles(['fixtures/a.png', 'fixtures/b.png']);
+
+// Upload — clear selection
+await page.getByLabel('Upload').setInputFiles([]);
+
+// Download — wait and save
+const download = await page.waitForEvent('download');
+await page.getByRole('button', { name: 'Export CSV' }).click();
+const path = await download.path();           // temp path
+await download.saveAs('test-results/export.csv'); // permanent path
+
+// File chooser dialog — non-input uploads
+const fileChooser = await page.waitForEvent('filechooser');
+await page.getByRole('button', { name: 'Choose file' }).click();
+await fileChooser.setFiles('fixtures/photo.jpg');
+```
+
+## Patterns
+
+### Single File Upload
+
+**Use when**: A form has a standard `<input type="file">` element.
+**Avoid when**: The upload uses a drag-and-drop zone with no underlying file input.
+
+**TypeScript**
+```typescript
+import { test, expect } from '@playwright/test';
+import path from 'path';
+
+test('upload a single document', async ({ page }) => {
+  await page.goto('/settings/profile');
+
+  const filePath = path.join(__dirname, '../fixtures/avatar.png');
+  await page.getByLabel('Profile picture').setInputFiles(filePath);
+
+  // Verify the file name appears in the UI
+  await expect(page.getByText('avatar.png')).toBeVisible();
+
+  await page.getByRole('button', { name: 'Save' }).click();
+  await expect(page.getByText('Profile updated')).toBeVisible();
+});
+```
+
+**JavaScript**
+```javascript
+const { test, expect } = require('@playwright/test');
+const path = require('path');
+
+test('upload a single document', async ({ page }) => {
+  await page.goto('/settings/profile');
+
+  const filePath = path.join(__dirname, '../fixtures/avatar.png');
+  await page.getByLabel('Profile picture').setInputFiles(filePath);
+
+  await expect(page.getByText('avatar.png')).toBeVisible();
+
+  await page.getByRole('button', { name: 'Save' }).click();
+  await expect(page.getByText('Profile updated')).toBeVisible();
+});
+```
+
+### Multiple File Upload
+
+**Use when**: The file input accepts `multiple` and you need to attach several files at once.
+**Avoid when**: The UI only allows one file. Use single file upload.
+
+**TypeScript**
+```typescript
+import { test, expect } from '@playwright/test';
+import path from 'path';
+
+test('upload multiple attachments', async ({ page }) => {
+  await page.goto('/tickets/new');
+
+  const fixtures = ['doc1.pdf', 'doc2.pdf', 'screenshot.png'].map(
+    (f) => path.join(__dirname, '../fixtures', f)
+  );
+
+  await page.getByLabel('Attachments').setInputFiles(fixtures);
+
+  // Verify all files are listed
+  await expect(page.getByTestId('file-list').getByRole('listitem')).toHaveCount(3);
+
+  // Remove one file by clearing and re-setting
+  await page.getByLabel('Attachments').setInputFiles(fixtures.slice(0, 2));
+  await expect(page.getByTestId('file-list').getByRole('listitem')).toHaveCount(2);
+});
+```
+
+**JavaScript**
+```javascript
+const { test, expect } = require('@playwright/test');
+const path = require('path');
+
+test('upload multiple attachments', async ({ page }) => {
+  await page.goto('/tickets/new');
+
+  const fixtures = ['doc1.pdf', 'doc2.pdf', 'screenshot.png'].map(
+    (f) => path.join(__dirname, '../fixtures', f)
+  );
+
+  await page.getByLabel('Attachments').setInputFiles(fixtures);
+  await expect(page.getByTestId('file-list').getByRole('listitem')).toHaveCount(3);
+
+  await page.getByLabel('Attachments').setInputFiles(fixtures.slice(0, 2));
+  await expect(page.getByTestId('file-list').getByRole('listitem')).toHaveCount(2);
+});
+```
+
+### File Chooser Dialog
+
+**Use when**: The upload is triggered by a button click that opens the native file picker, not by a visible `<input type="file">`. Common with drag-and-drop libraries and custom upload components.
+**Avoid when**: There is a visible `<input type="file">` — use `setInputFiles` directly.
+
+**TypeScript**
+```typescript
+import { test, expect } from '@playwright/test';
+
+test('upload via file chooser dialog', async ({ page }) => {
+  await page.goto('/documents');
+
+  // Register the listener BEFORE the click that opens the dialog
+  const fileChooserPromise = page.waitForEvent('filechooser');
+  await page.getByRole('button', { name: 'Upload document' }).click();
+  const fileChooser = await fileChooserPromise;
+
+  // Verify dialog properties
+  expect(fileChooser.isMultiple()).toBe(false);
+
+  await fileChooser.setFiles('fixtures/report.pdf');
+  await expect(page.getByText('report.pdf')).toBeVisible();
+});
+
+test('upload multiple via file chooser', async ({ page }) => {
+  await page.goto('/gallery');
+
+  const fileChooserPromise = page.waitForEvent('filechooser');
+  await page.getByRole('button', { name: 'Add photos' }).click();
+  const fileChooser = await fileChooserPromise;
+
+  expect(fileChooser.isMultiple()).toBe(true);
+  await fileChooser.setFiles(['fixtures/photo1.jpg', 'fixtures/photo2.jpg']);
+
+  await expect(page.getByRole('img')).toHaveCount(2);
+});
+```
+
+**JavaScript**
+```javascript
+const { test, expect } = require('@playwright/test');
+
+test('upload via file chooser dialog', async ({ page }) => {
+  await page.goto('/documents');
+
+  const fileChooserPromise = page.waitForEvent('filechooser');
+  await page.getByRole('button', { name: 'Upload document' }).click();
+  const fileChooser = await fileChooserPromise;
+
+  expect(fileChooser.isMultiple()).toBe(false);
+
+  await fileChooser.setFiles('fixtures/report.pdf');
+  await expect(page.getByText('report.pdf')).toBeVisible();
+});
+
+test('upload multiple via file chooser', async ({ page }) => {
+  await page.goto('/gallery');
+
+  const fileChooserPromise = page.waitForEvent('filechooser');
+  await page.getByRole('button', { name: 'Add photos' }).click();
+  const fileChooser = await fileChooserPromise;
+
+  expect(fileChooser.isMultiple()).toBe(true);
+  await fileChooser.setFiles(['fixtures/photo1.jpg', 'fixtures/photo2.jpg']);
+
+  await expect(page.getByRole('img')).toHaveCount(2);
+});
+```
+
+### Drag-and-Drop File Upload
+
+**Use when**: The UI has a drop zone that accepts files via the HTML5 Drag and Drop API and has no `<input type="file">` fallback.
+**Avoid when**: A file input exists — even hidden ones work with `setInputFiles`.
+
+**TypeScript**
+```typescript
+import { test, expect } from '@playwright/test';
+import fs from 'fs';
+import path from 'path';
+
+test('drop file onto upload zone', async ({ page }) => {
+  await page.goto('/upload');
+
+  // Read the file into a buffer
+  const filePath = path.join(__dirname, '../fixtures/data.csv');
+  const buffer = fs.readFileSync(filePath);
+
+  // Create a DataTransfer with the file and dispatch drop event
+  const dropZone = page.getByTestId('drop-zone');
+
+  await dropZone.dispatchEvent('drop', {
+    dataTransfer: {
+      files: [
+        { name: 'data.csv', mimeType: 'text/csv', buffer },
+      ],
+    },
+  });
+
+  await expect(page.getByText('data.csv')).toBeVisible();
+  await expect(page.getByText('Upload complete')).toBeVisible();
+});
+
+test('drag-and-drop with hidden input fallback', async ({ page }) => {
+  await page.goto('/upload');
+
+  // Many drag-and-drop libraries still use a hidden <input type="file">
+  // Check for it first — this is more reliable than simulating DnD events
+  const hiddenInput = page.locator('input[type="file"]');
+
+  if (await hiddenInput.count() > 0) {
+    await hiddenInput.setInputFiles('fixtures/data.csv');
+  }
+
+  await expect(page.getByText('data.csv')).toBeVisible();
+});
+```
+
+**JavaScript**
+```javascript
+const { test, expect } = require('@playwright/test');
+const fs = require('fs');
+const path = require('path');
+
+test('drop file onto upload zone', async ({ page }) => {
+  await page.goto('/upload');
+
+  const filePath = path.join(__dirname, '../fixtures/data.csv');
+  const buffer = fs.readFileSync(filePath);
+
+  const dropZone = page.getByTestId('drop-zone');
+
+  await dropZone.dispatchEvent('drop', {
+    dataTransfer: {
+      files: [
+        { name: 'data.csv', mimeType: 'text/csv', buffer },
+      ],
+    },
+  });
+
+  await expect(page.getByText('data.csv')).toBeVisible();
+  await expect(page.getByText('Upload complete')).toBeVisible();
+});
+
+test('drag-and-drop with hidden input fallback', async ({ page }) => {
+  await page.goto('/upload');
+
+  const hiddenInput = page.locator('input[type="file"]');
+
+  if (await hiddenInput.count() > 0) {
+    await hiddenInput.setInputFiles('fixtures/data.csv');
+  }
+
+  await expect(page.getByText('data.csv')).toBeVisible();
+});
+```
+
+### File Download — Wait and Verify
+
+**Use when**: Testing export buttons, report generation, or any action that triggers a browser download.
+**Avoid when**: The file is served as a page navigation (opens in a new tab). Use multi-tab patterns instead.
+
+**TypeScript**
+```typescript
+import { test, expect } from '@playwright/test';
+import fs from 'fs';
+
+test('download and verify file content', async ({ page }) => {
+  await page.goto('/reports');
+
+  // Register BEFORE the click that triggers the download
+  const downloadPromise = page.waitForEvent('download');
+  await page.getByRole('button', { name: 'Export CSV' }).click();
+  const download = await downloadPromise;
+
+  // Verify download metadata
+  expect(download.suggestedFilename()).toBe('report-2025.csv');
+
+  // Save to a known location
+  const savePath = 'test-results/report.csv';
+  await download.saveAs(savePath);
+
+  // Read and verify content
+  const content = fs.readFileSync(savePath, 'utf-8');
+  expect(content).toContain('Name,Email,Status');
+  expect(content).toContain('Jane Doe,jane@example.com,Active');
+
+  // Verify file size is reasonable
+  const stats = fs.statSync(savePath);
+  expect(stats.size).toBeGreaterThan(100);
+});
+
+test('download triggered by a link', async ({ page }) => {
+  await page.goto('/files');
+
+  const downloadPromise = page.waitForEvent('download');
+  await page.getByRole('link', { name: 'Download invoice' }).click();
+  const download = await downloadPromise;
+
+  expect(download.suggestedFilename()).toMatch(/invoice-\d+\.pdf/);
+
+  // Use download.path() for the temp file path
+  const tempPath = await download.path();
+  expect(tempPath).toBeTruthy();
+});
+```
+
+**JavaScript**
+```javascript
+const { test, expect } = require('@playwright/test');
+const fs = require('fs');
+
+test('download and verify file content', async ({ page }) => {
+  await page.goto('/reports');
+
+  const downloadPromise = page.waitForEvent('download');
+  await page.getByRole('button', { name: 'Export CSV' }).click();
+  const download = await downloadPromise;
+
+  expect(download.suggestedFilename()).toBe('report-2025.csv');
+
+  const savePath = 'test-results/report.csv';
+  await download.saveAs(savePath);
+
+  const content = fs.readFileSync(savePath, 'utf-8');
+  expect(content).toContain('Name,Email,Status');
+  expect(content).toContain('Jane Doe,jane@example.com,Active');
+
+  const stats = fs.statSync(savePath);
+  expect(stats.size).toBeGreaterThan(100);
+});
+
+test('download triggered by a link', async ({ page }) => {
+  await page.goto('/files');
+
+  const downloadPromise = page.waitForEvent('download');
+  await page.getByRole('link', { name: 'Download invoice' }).click();
+  const download = await downloadPromise;
+
+  expect(download.suggestedFilename()).toMatch(/invoice-\d+\.pdf/);
+
+  const tempPath = await download.path();
+  expect(tempPath).toBeTruthy();
+});
+```
+
+### Configuring Download Paths
+
+**Use when**: You need downloads to go to a specific directory, or you need to disable the download dialog prompt.
+**Avoid when**: Default temp paths via `download.path()` or `download.saveAs()` are sufficient.
+
+**TypeScript**
+```typescript
+// playwright.config.ts — global download behavior
+import { defineConfig } from '@playwright/test';
+
+export default defineConfig({
+  use: {
+    // Accept all downloads without prompting
+    acceptDownloads: true, // default is true
+  },
+});
+```
+
+```typescript
+import { test, expect } from '@playwright/test';
+import fs from 'fs';
+import path from 'path';
+
+// Per-test download directory via a custom fixture
+const downloadTest = test.extend<{ downloadDir: string }>({
+  downloadDir: async ({}, use, testInfo) => {
+    const dir = path.join('test-results', 'downloads', testInfo.title.replace(/\s+/g, '-'));
+    fs.mkdirSync(dir, { recursive: true });
+    await use(dir);
+  },
+});
+
+downloadTest('save downloads to organized directories', async ({ page, downloadDir }) => {
+  await page.goto('/exports');
+
+  const downloadPromise = page.waitForEvent('download');
+  await page.getByRole('button', { name: 'Export' }).click();
+  const download = await downloadPromise;
+
+  const savePath = path.join(downloadDir, download.suggestedFilename());
+  await download.saveAs(savePath);
+
+  expect(fs.existsSync(savePath)).toBe(true);
+});
+```
+
+**JavaScript**
+```javascript
+// playwright.config.js
+const { defineConfig } = require('@playwright/test');
+
+module.exports = defineConfig({
+  use: {
+    acceptDownloads: true,
+  },
+});
+```
+
+```javascript
+const { test, expect } = require('@playwright/test');
+const fs = require('fs');
+const path = require('path');
+
+const downloadTest = test.extend({
+  downloadDir: async ({}, use, testInfo) => {
+    const dir = path.join('test-results', 'downloads', testInfo.title.replace(/\s+/g, '-'));
+    fs.mkdirSync(dir, { recursive: true });
+    await use(dir);
+  },
+});
+
+downloadTest('save downloads to organized directories', async ({ page, downloadDir }) => {
+  await page.goto('/exports');
+
+  const downloadPromise = page.waitForEvent('download');
+  await page.getByRole('button', { name: 'Export' }).click();
+  const download = await downloadPromise;
+
+  const savePath = path.join(downloadDir, download.suggestedFilename());
+  await download.saveAs(savePath);
+
+  expect(fs.existsSync(savePath)).toBe(true);
+});
+```
+
+### File Type Validation
+
+**Use when**: Testing that the application rejects invalid file types and accepts valid ones.
+**Avoid when**: The application does no client-side validation and relies entirely on server-side checks (test via API instead).
+
+**TypeScript**
+```typescript
+import { test, expect } from '@playwright/test';
+
+test('rejects unsupported file types', async ({ page }) => {
+  await page.goto('/upload');
+
+  // Upload an invalid file type
+  await page.getByLabel('Upload image').setInputFiles({
+    name: 'malware.exe',
+    mimeType: 'application/octet-stream',
+    buffer: Buffer.from('fake-exe-content'),
+  });
+
+  await expect(page.getByText('Only JPG, PNG, and GIF files are allowed')).toBeVisible();
+  await expect(page.getByRole('button', { name: 'Submit' })).toBeDisabled();
+});
+
+test('accepts valid file types', async ({ page }) => {
+  await page.goto('/upload');
+
+  await page.getByLabel('Upload image').setInputFiles({
+    name: 'photo.jpg',
+    mimeType: 'image/jpeg',
+    buffer: Buffer.from('fake-jpg-content'),
+  });
+
+  await expect(page.getByText('photo.jpg')).toBeVisible();
+  await expect(page.getByRole('button', { name: 'Submit' })).toBeEnabled();
+});
+
+test('validates file size limits', async ({ page }) => {
+  await page.goto('/upload');
+
+  // Create a buffer that exceeds the 5MB limit
+  const largeBuffer = Buffer.alloc(6 * 1024 * 1024, 'x');
+
+  await page.getByLabel('Upload document').setInputFiles({
+    name: 'huge-file.pdf',
+    mimeType: 'application/pdf',
+    buffer: largeBuffer,
+  });
+
+  await expect(page.getByText('File size must be under 5MB')).toBeVisible();
+});
+```
+
+**JavaScript**
+```javascript
+const { test, expect } = require('@playwright/test');
+
+test('rejects unsupported file types', async ({ page }) => {
+  await page.goto('/upload');
+
+  await page.getByLabel('Upload image').setInputFiles({
+    name: 'malware.exe',
+    mimeType: 'application/octet-stream',
+    buffer: Buffer.from('fake-exe-content'),
+  });
+
+  await expect(page.getByText('Only JPG, PNG, and GIF files are allowed')).toBeVisible();
+  await expect(page.getByRole('button', { name: 'Submit' })).toBeDisabled();
+});
+
+test('accepts valid file types', async ({ page }) => {
+  await page.goto('/upload');
+
+  await page.getByLabel('Upload image').setInputFiles({
+    name: 'photo.jpg',
+    mimeType: 'image/jpeg',
+    buffer: Buffer.from('fake-jpg-content'),
+  });
+
+  await expect(page.getByText('photo.jpg')).toBeVisible();
+  await expect(page.getByRole('button', { name: 'Submit' })).toBeEnabled();
+});
+
+test('validates file size limits', async ({ page }) => {
+  await page.goto('/upload');
+
+  const largeBuffer = Buffer.alloc(6 * 1024 * 1024, 'x');
+
+  await page.getByLabel('Upload document').setInputFiles({
+    name: 'huge-file.pdf',
+    mimeType: 'application/pdf',
+    buffer: largeBuffer,
+  });
+
+  await expect(page.getByText('File size must be under 5MB')).toBeVisible();
+});
+```
+
+### Large File Handling
+
+**Use when**: Testing uploads or downloads of large files where timeouts and progress indicators matter.
+**Avoid when**: Every test. Large file tests are slow. Run them in a separate suite or tag them for nightly runs.
+
+**TypeScript**
+```typescript
+import { test, expect } from '@playwright/test';
+import fs from 'fs';
+import path from 'path';
+
+test.describe('large file operations', () => {
+  // Increase timeout for the entire describe block
+  test.slow(); // Triples the default timeout
+
+  test('upload large file with progress tracking', async ({ page }) => {
+    await page.goto('/upload');
+
+    // Create a test file on disk (avoid Buffer.alloc for very large files)
+    const largePath = path.join('test-results', 'large-test-file.bin');
+    const stream = fs.createWriteStream(largePath);
+    for (let i = 0; i < 100; i++) {
+      stream.write(Buffer.alloc(1024 * 1024, 'a')); // 100MB total
+    }
+    stream.end();
+    await new Promise((resolve) => stream.on('finish', resolve));
+
+    await page.getByLabel('Upload file').setInputFiles(largePath);
+
+    // Wait for progress indicator
+    await expect(page.getByRole('progressbar')).toBeVisible();
+
+    // Wait for completion — extended timeout
+    await expect(page.getByText('Upload complete')).toBeVisible({ timeout: 120_000 });
+
+    // Cleanup
+    fs.unlinkSync(largePath);
+  });
+
+  test('download large file', async ({ page }) => {
+    await page.goto('/exports');
+
+    const downloadPromise = page.waitForEvent('download');
+    await page.getByRole('button', { name: 'Export full dataset' }).click();
+    const download = await downloadPromise;
+
+    const savePath = 'test-results/large-export.zip';
+    await download.saveAs(savePath);
+
+    // Verify file size is reasonable (at least 10MB)
+    const stats = fs.statSync(savePath);
+    expect(stats.size).toBeGreaterThan(10 * 1024 * 1024);
+
+    fs.unlinkSync(savePath);
+  });
+});
+```
+
+**JavaScript**
+```javascript
+const { test, expect } = require('@playwright/test');
+const fs = require('fs');
+const path = require('path');
+
+test.describe('large file operations', () => {
+  test.slow();
+
+  test('upload large file with progress tracking', async ({ page }) => {
+    await page.goto('/upload');
+
+    const largePath = path.join('test-results', 'large-test-file.bin');
+    const stream = fs.createWriteStream(largePath);
+    for (let i = 0; i < 100; i++) {
+      stream.write(Buffer.alloc(1024 * 1024, 'a'));
+    }
+    stream.end();
+    await new Promise((resolve) => stream.on('finish', resolve));
+
+    await page.getByLabel('Upload file').setInputFiles(largePath);
+
+    await expect(page.getByRole('progressbar')).toBeVisible();
+    await expect(page.getByText('Upload complete')).toBeVisible({ timeout: 120_000 });
+
+    fs.unlinkSync(largePath);
+  });
+
+  test('download large file', async ({ page }) => {
+    await page.goto('/exports');
+
+    const downloadPromise = page.waitForEvent('download');
+    await page.getByRole('button', { name: 'Export full dataset' }).click();
+    const download = await downloadPromise;
+
+    const savePath = 'test-results/large-export.zip';
+    await download.saveAs(savePath);
+
+    const stats = fs.statSync(savePath);
+    expect(stats.size).toBeGreaterThan(10 * 1024 * 1024);
+
+    fs.unlinkSync(savePath);
+  });
+});
+```
+
+## Decision Guide
+
+| Scenario | Approach | Key API |
+|---|---|---|
+| Standard `<input type="file">` | `setInputFiles()` on the locator | `locator.setInputFiles(path)` |
+| Hidden file input | Find the input even if hidden, call `setInputFiles()` | `page.locator('input[type="file"]').setInputFiles()` |
+| Custom button opens file picker | Listen for `filechooser` event before clicking | `page.waitForEvent('filechooser')` |
+| Drag-and-drop zone with no input | Dispatch `drop` event with `DataTransfer` | `locator.dispatchEvent('drop', ...)` |
+| DnD zone with hidden input fallback | Prefer `setInputFiles()` on the hidden input | Check `input[type="file"]` count first |
+| Multiple files at once | Pass array to `setInputFiles()` | `setInputFiles([path1, path2])` |
+| In-memory test file (no disk) | Pass object with `name`, `mimeType`, `buffer` | `setInputFiles({ name, mimeType, buffer })` |
+| Download — verify filename | `download.suggestedFilename()` | `page.waitForEvent('download')` |
+| Download — verify content | `download.saveAs()` then read with `fs` | `fs.readFileSync()` |
+| Download — temp file only | `download.path()` returns temp location | Auto-deleted after test |
+| Large file upload/download | Use `test.slow()`, increase assertion timeouts | `{ timeout: 120_000 }` |
+
+## Anti-Patterns
+
+| Don't Do This | Problem | Do This Instead |
+|---|---|---|
+| `await page.waitForTimeout(3000)` after upload | Arbitrary delay; flaky | `await expect(page.getByText('Upload complete')).toBeVisible()` |
+| `await page.setInputFiles('#file', path)` using CSS selector | Fragile selector; breaks on ID changes | `await page.getByLabel('Upload').setInputFiles(path)` |
+| Clicking download then immediately reading the file | Race condition; file may not be written yet | Use `page.waitForEvent('download')` then `download.saveAs()` |
+| Creating large test files in `beforeAll` and never cleaning up | Fills disk in CI, slows down subsequent runs | Clean up in `afterAll` or use fixture teardown |
+| Using `page.on('filechooser')` for every upload | Unnecessary complexity when `<input type="file">` exists | Use `setInputFiles()` directly |
+| Hardcoding absolute file paths | Breaks across machines and CI | Use `path.join(__dirname, ...)` or relative to project root |
+| Testing file upload with empty buffer | Does not test real validation behavior | Use realistic file content or minimum valid file size |
+| Using `download.path()` for permanent storage | Temp files are cleaned up after test context closes | Use `download.saveAs()` for permanent paths |
+| Uploading real 100MB files in every test run | Slows entire suite, wastes CI resources | Tag large file tests separately; run on schedule, not every PR |
+
+## Troubleshooting
+
+### "FileChooser event was not emitted"
+
+**Cause**: The click did not open a native file picker dialog. The upload component may use a different mechanism.
+
+```typescript
+// Debug: check if there is a hidden <input type="file"> you can target directly
+const fileInputCount = await page.locator('input[type="file"]').count();
+console.log(`Found ${fileInputCount} file inputs`);
+
+// If input exists, skip the file chooser approach entirely
+if (fileInputCount > 0) {
+  await page.locator('input[type="file"]').setInputFiles('fixtures/file.pdf');
+}
+```
+
+### "Download event was not emitted"
+
+**Cause**: The link opens in a new tab or navigates to the file URL instead of triggering a download.
+
+```typescript
+// Fix 1: Ensure acceptDownloads is true in config
+// Fix 2: Check if the link opens a new tab — handle it as a new page
+const pagePromise = page.context().waitForEvent('page');
+await page.getByRole('link', { name: 'Download' }).click();
+const newPage = await pagePromise;
+// Then wait for the download event on the new page
+const download = await newPage.waitForEvent('download');
+```
+
+### Upload works locally but fails in CI
+
+**Cause**: File paths are wrong in CI, or the fixture files are not included in the repo/build.
+
+```typescript
+// Fix: always resolve paths relative to the test file
+import path from 'path';
+const fixturePath = path.join(__dirname, '..', 'fixtures', 'test-file.pdf');
+
+// Verify the file exists before uploading
+import fs from 'fs';
+if (!fs.existsSync(fixturePath)) {
+  throw new Error(`Fixture file missing: ${fixturePath}`);
+}
+```
+
+### `setInputFiles` does nothing — no file appears
+
+**Cause**: The input element is detached, inside a Shadow DOM, or in an iframe.
+
+```typescript
+// Check for iframe
+const frame = page.frameLocator('iframe[title="Upload"]');
+await frame.locator('input[type="file"]').setInputFiles('fixtures/file.pdf');
+
+// Check for Shadow DOM — Playwright pierces open shadow roots automatically
+// but the input may be in a closed shadow root (rare). Use the file chooser approach instead.
+```
+
+## Related
+
+- [core/locators.md](locators.md) -- locator strategies for finding upload/download elements
+- [core/assertions-and-waiting.md](assertions-and-waiting.md) -- assertion patterns for verifying upload/download results
+- [core/fixtures-and-hooks.md](fixtures-and-hooks.md) -- creating reusable download directory fixtures
+- [core/network-mocking.md](network-mocking.md) -- mocking upload endpoints for faster tests
+- [core/error-and-edge-cases.md](error-and-edge-cases.md) -- testing upload failure states and error handling