ever-co/ever-works / .agents/skills/playwright-best-practices
playwright-best-practices
VerifiedUse when writing Playwright tests, fixing flaky tests, debugging failures, implementing Page Object Model, configuring CI/CD, optimizing performance, mocking APIs, handling authentication or OAuth, testing accessibility (axe-core), file uploads/downloads, date/time mocking, WebSockets, geolocation, permissions, multi-tab/popup flows, mobile/responsive layouts, touch gestures, GraphQL, error handling, offline mode, multi-user collaboration, third-party services (payments, email verification), console error monitoring, global setup/teardown, test annotations (skip, fixme, slow), test tags (@smoke, @fast, @critical, filtering with --grep), project dependencies, security testing (XSS, CSRF, auth), performance budgets (Web Vitals, Lighthouse), iframes, component testing, canvas/WebGL, service workers/PWA, test coverage, i18n/localization, Electron apps, or browser extension testing. Covers E2E, component, API, visual, accessibility, security, Electron, and extension testing.
testing-patterns/file-operations.md
View on GitHub# File Upload & Download Testing
> For advanced patterns (progress tracking, cancellation, retry logic), see [file-upload-download.md](./file-upload-download.md)
## Table of Contents
1. [File Downloads](#file-downloads)
2. [File Uploads](#file-uploads)
3. [Drag and Drop](#drag-and-drop)
4. [File Content Verification](#file-content-verification)
## File Downloads
### Basic Download
```typescript
test('download PDF report', async ({ page }) => {
await page.goto('/reports');
// Start waiting for download before clicking
const downloadPromise = page.waitForEvent('download');
await page.getByRole('button', { name: 'Download PDF' }).click();
const download = await downloadPromise;
// Verify filename
expect(download.suggestedFilename()).toBe('report.pdf');
// Save to specific path
await download.saveAs('./downloads/report.pdf');
});
```
### Download with Custom Path
```typescript
test('download to temp directory', async ({ page }, testInfo) => {
await page.goto('/exports');
const downloadPromise = page.waitForEvent('download');
await page.getByRole('link', { name: 'Export CSV' }).click();
const download = await downloadPromise;
// Save to test output directory
const path = testInfo.outputPath(download.suggestedFilename());
await download.saveAs(path);
// Attach to test report
await testInfo.attach('downloaded-file', { path });
});
```
### Verify Download Content
```typescript
import fs from 'fs';
import path from 'path';
test('verify CSV content', async ({ page }, testInfo) => {
await page.goto('/data');
const downloadPromise = page.waitForEvent('download');
await page.getByRole('button', { name: 'Export' }).click();
const download = await downloadPromise;
const filePath = testInfo.outputPath('export.csv');
await download.saveAs(filePath);
// Read and verify content
const content = fs.readFileSync(filePath, 'utf-8');
expect(content).toContain('Name,Email,Status');
expect(content).toContain('John Doe');
// Verify row count
const rows = content.trim().split('\n');
expect(rows.length).toBeGreaterThan(1);
});
```
### Multiple Downloads
```typescript
test('download multiple files', async ({ page }) => {
await page.goto('/batch-export');
await page.getByRole('checkbox', { name: 'Select All' }).check();
// Collect all downloads
const downloads: Download[] = [];
page.on('download', (download) => downloads.push(download));
await page.getByRole('button', { name: 'Download Selected' }).click();
// Wait for all downloads
await expect.poll(() => downloads.length, { timeout: 30000 }).toBe(5);
// Verify each download
for (const download of downloads) {
expect(download.suggestedFilename()).toMatch(/\.pdf$/);
}
});
```
### Download Fixture
```typescript
// fixtures/download.fixture.ts
import { test as base, Download } from '@playwright/test';
import fs from 'fs';
import path from 'path';
type DownloadFixtures = {
downloadDir: string;
downloadAndVerify: (trigger: () => Promise<void>, expectedFilename: string) => Promise<string>;
};
export const test = base.extend<DownloadFixtures>({
downloadDir: async ({}, use, testInfo) => {
const dir = testInfo.outputPath('downloads');
fs.mkdirSync(dir, { recursive: true });
await use(dir);
},
downloadAndVerify: async ({ page, downloadDir }, use) => {
await use(async (trigger, expectedFilename) => {
const downloadPromise = page.waitForEvent('download');
await trigger();
const download = await downloadPromise;
expect(download.suggestedFilename()).toBe(expectedFilename);
const filePath = path.join(downloadDir, expectedFilename);
await download.saveAs(filePath);
return filePath;
});
}
});
```
## File Uploads
### Basic Upload
```typescript
test('upload profile picture', async ({ page }) => {
await page.goto('/settings/profile');
// Upload file
await page.getByLabel('Profile Picture').setInputFiles('./fixtures/avatar.png');
// Verify preview
await expect(page.getByAltText('Profile preview')).toBeVisible();
await page.getByRole('button', { name: 'Save' }).click();
await expect(page.getByText('Profile updated')).toBeVisible();
});
```
### Multiple File Upload
```typescript
test('upload multiple documents', async ({ page }) => {
await page.goto('/documents/upload');
await page
.getByLabel('Documents')
.setInputFiles(['./fixtures/doc1.pdf', './fixtures/doc2.pdf', './fixtures/doc3.pdf']);
// Verify all files listed
await expect(page.getByText('doc1.pdf')).toBeVisible();
await expect(page.getByText('doc2.pdf')).toBeVisible();
await expect(page.getByText('doc3.pdf')).toBeVisible();
await page.getByRole('button', { name: 'Upload All' }).click();
await expect(page.getByText('3 files uploaded')).toBeVisible();
});
```
### Upload with File Chooser
```typescript
test('upload via file chooser dialog', async ({ page }) => {
await page.goto('/upload');
// Handle file chooser
const fileChooserPromise = page.waitForEvent('filechooser');
await page.getByRole('button', { name: 'Choose File' }).click();
const fileChooser = await fileChooserPromise;
await fileChooser.setFiles('./fixtures/document.pdf');
await expect(page.getByText('document.pdf')).toBeVisible();
});
```
### Clear and Re-upload
```typescript
test('replace uploaded file', async ({ page }) => {
await page.goto('/upload');
const input = page.getByLabel('Document');
// Upload first file
await input.setInputFiles('./fixtures/old.pdf');
await expect(page.getByText('old.pdf')).toBeVisible();
// Clear selection
await input.setInputFiles([]);
// Upload new file
await input.setInputFiles('./fixtures/new.pdf');
await expect(page.getByText('new.pdf')).toBeVisible();
await expect(page.getByText('old.pdf')).toBeHidden();
});
```
### Upload from Buffer
```typescript
test('upload generated file', async ({ page }) => {
await page.goto('/upload');
// Create file content dynamically
const content = 'Name,Email\nJohn,john@example.com';
await page.getByLabel('CSV File').setInputFiles({
name: 'users.csv',
mimeType: 'text/csv',
buffer: Buffer.from(content)
});
await expect(page.getByText('users.csv')).toBeVisible();
});
```
## Drag and Drop
### Drag and Drop Upload
```typescript
test('drag and drop file upload', async ({ page }) => {
await page.goto('/upload');
const dropzone = page.getByTestId('dropzone');
// Create a DataTransfer with the file
const dataTransfer = await page.evaluateHandle(() => new DataTransfer());
// Read file and add to DataTransfer
const buffer = fs.readFileSync('./fixtures/image.png');
await page.evaluate(
async ([dataTransfer, data]) => {
const file = new File([new Uint8Array(data)], 'image.png', {
type: 'image/png'
});
dataTransfer.items.add(file);
},
[dataTransfer, [...buffer]] as const
);
// Dispatch drop event
await dropzone.dispatchEvent('drop', { dataTransfer });
await expect(page.getByText('image.png uploaded')).toBeVisible();
});
```
### Simpler Drag and Drop
```typescript
test('drag and drop with setInputFiles', async ({ page }) => {
await page.goto('/upload');
// Most dropzones have a hidden file input
const input = page.locator('input[type="file"]');
// This works even if the input is hidden
await input.setInputFiles('./fixtures/document.pdf');
await expect(page.getByText('document.pdf')).toBeVisible();
});
```
## File Content Verification
### Verify PDF Content
```typescript
import pdf from 'pdf-parse';
test('verify PDF content', async ({ page }, testInfo) => {
await page.goto('/invoice/123');
const downloadPromise = page.waitForEvent('download');
await page.getByRole('button', { name: 'Download Invoice' }).click();
const download = await downloadPromise;
const path = testInfo.outputPath('invoice.pdf');
await download.saveAs(path);
// Parse PDF
const dataBuffer = fs.readFileSync(path);
const data = await pdf(dataBuffer);
expect(data.text).toContain('Invoice #123');
expect(data.text).toContain('Total: $99.99');
});
```
### Verify Excel Content
```typescript
import XLSX from 'xlsx';
test('verify Excel export', async ({ page }, testInfo) => {
await page.goto('/reports');
const downloadPromise = page.waitForEvent('download');
await page.getByRole('button', { name: 'Export Excel' }).click();
const download = await downloadPromise;
const path = testInfo.outputPath('report.xlsx');
await download.saveAs(path);
// Parse Excel
const workbook = XLSX.readFile(path);
const sheet = workbook.Sheets[workbook.SheetNames[0]];
const data = XLSX.utils.sheet_to_json(sheet);
expect(data).toHaveLength(10);
expect(data[0]).toHaveProperty('Name');
expect(data[0]).toHaveProperty('Email');
});
```
### Verify JSON Download
```typescript
test('verify JSON export', async ({ page }, testInfo) => {
await page.goto('/api-data');
const downloadPromise = page.waitForEvent('download');
await page.getByRole('button', { name: 'Export JSON' }).click();
const download = await downloadPromise;
const path = testInfo.outputPath('data.json');
await download.saveAs(path);
const content = JSON.parse(fs.readFileSync(path, 'utf-8'));
expect(content.users).toHaveLength(5);
expect(content.exportDate).toBeDefined();
});
```
## Anti-Patterns to Avoid
| Anti-Pattern | Problem | Solution |
| ------------------------------------- | ------------------------------- | --------------------------------------------- |
| Not waiting for download | Race condition, test fails | Always use `waitForEvent("download")` |
| Hardcoded download paths | Conflicts in parallel runs | Use `testInfo.outputPath()` |
| Skipping content verification | Download might be empty/corrupt | Verify file content when possible |
| Using `force: true` for hidden inputs | May not trigger proper events | Use `setInputFiles` on hidden inputs directly |
## Related References
- **Fixtures**: See [fixtures-hooks.md](../core/fixtures-hooks.md) for download fixture patterns
- **Debugging**: See [debugging.md](../debugging/debugging.md) for troubleshooting download issues
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |