Skip to content

ever-co/ever-works / .agents/skills/playwright-best-practices

playwright-best-practices

Verified

Use 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.

FileKindSize
LICENSE.mdmarkdown1.0 KB
README.mdmarkdown9.9 KB
SKILL.mdskill md25.7 KB
advanced/authentication-flows.mdmarkdown10.4 KB
advanced/authentication.mdmarkdown29.4 KB
advanced/clock-mocking.mdmarkdown9.4 KB
advanced/mobile-testing.mdmarkdown10.3 KB
advanced/multi-context.mdmarkdown8.2 KB
advanced/multi-user.mdmarkdown10.9 KB
advanced/network-advanced.mdmarkdown10.1 KB
advanced/third-party.mdmarkdown11.1 KB
architecture/pom-vs-fixtures.mdmarkdown11.4 KB
architecture/test-architecture.mdmarkdown14.3 KB
architecture/when-to-mock.mdmarkdown11.9 KB
browser-apis/browser-apis.mdmarkdown10.1 KB
browser-apis/iframes.mdmarkdown11.1 KB
browser-apis/service-workers.mdmarkdown13.1 KB
browser-apis/websockets.mdmarkdown9.9 KB
core/annotations.mdmarkdown10.4 KB
core/assertions-waiting.mdmarkdown9.1 KB
core/configuration.mdmarkdown13.7 KB
core/fixtures-hooks.mdmarkdown11.2 KB
core/global-setup.mdmarkdown12.4 KB
core/locators.mdmarkdown6.4 KB
core/page-object-model.mdmarkdown7.7 KB
core/projects-dependencies.mdmarkdown8.1 KB
core/test-data.mdmarkdown11.3 KB
core/test-suite-structure.mdmarkdown9.1 KB
core/test-tags.mdmarkdown6.7 KB
debugging/console-errors.mdmarkdown9.3 KB
debugging/debugging.mdmarkdown14.7 KB
debugging/error-testing.mdmarkdown9.2 KB
debugging/flaky-tests.mdmarkdown14.5 KB
frameworks/angular.mdmarkdown18.9 KB
frameworks/nextjs.mdmarkdown13.4 KB
frameworks/react.mdmarkdown17.5 KB
frameworks/vue.mdmarkdown17.3 KB
infrastructure-ci-cd/ci-cd.mdmarkdown10.4 KB
infrastructure-ci-cd/docker.mdmarkdown7.0 KB
infrastructure-ci-cd/github-actions.mdmarkdown15.1 KB
infrastructure-ci-cd/gitlab.mdmarkdown10.9 KB
infrastructure-ci-cd/other-providers.mdmarkdown14.2 KB
infrastructure-ci-cd/parallel-sharding.mdmarkdown11.6 KB
infrastructure-ci-cd/performance.mdmarkdown11.3 KB
infrastructure-ci-cd/reporting.mdmarkdown11.4 KB
infrastructure-ci-cd/test-coverage.mdmarkdown12.0 KB
testing-patterns/accessibility.mdmarkdown8.7 KB
testing-patterns/api-testing.mdmarkdown23.5 KB
testing-patterns/browser-extensions.mdmarkdown13.0 KB
testing-patterns/canvas-webgl.mdmarkdown12.3 KB
testing-patterns/component-testing.mdmarkdown11.0 KB
testing-patterns/drag-drop.mdmarkdown17.4 KB
testing-patterns/electron.mdmarkdown12.8 KB
testing-patterns/file-operations.mdmarkdown10.0 KB
testing-patterns/file-upload-download.mdmarkdown16.5 KB
testing-patterns/forms-validation.mdmarkdown21.3 KB
testing-patterns/graphql-testing.mdmarkdown8.6 KB
testing-patterns/i18n.mdmarkdown12.3 KB
testing-patterns/performance-testing.mdmarkdown11.5 KB
testing-patterns/security-testing.mdmarkdown11.5 KB
testing-patterns/visual-regression.mdmarkdown18.4 KB

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
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: 471kUpdated Claude CodeCodexVerifiedInstall
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: 471kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall