Skip to content

zebbern/claude-code-guide / skills/playwright/core

playwright-core

Verified

Battle-tested Playwright patterns for E2E, API, component, visual, accessibility, and security testing. Covers locators, assertions, fixtures, network mocking, auth flows, debugging, and framework recipes for React, Next.js, Vue, and Angular. TypeScript and JavaScript.

FileKindSize
SKILL.mdskill md7.6 KB
accessibility.mdmarkdown53.2 KB
angular.mdmarkdown40.7 KB
api-testing.mdmarkdown51.4 KB
assertions-and-waiting.mdmarkdown26.8 KB
auth-flows.mdmarkdown32.6 KB
authentication.mdmarkdown48.7 KB
browser-apis.mdmarkdown24.0 KB
browser-extensions.mdmarkdown14.6 KB
canvas-and-webgl.mdmarkdown19.8 KB
clock-and-time-mocking.mdmarkdown19.5 KB
common-pitfalls.mdmarkdown44.4 KB
component-testing.mdmarkdown46.4 KB
configuration.mdmarkdown25.0 KB
crud-testing.mdmarkdown31.1 KB
debugging.mdmarkdown26.5 KB
drag-and-drop.mdmarkdown28.7 KB
electron-testing.mdmarkdown22.4 KB
error-and-edge-cases.mdmarkdown39.2 KB
error-index.mdmarkdown58.2 KB
file-operations.mdmarkdown26.1 KB
file-upload-download.mdmarkdown29.6 KB
fixtures-and-hooks.mdmarkdown32.9 KB
flaky-tests.mdmarkdown31.0 KB
forms-and-validation.mdmarkdown39.1 KB
i18n-and-localization.mdmarkdown24.4 KB
iframes-and-shadow-dom.mdmarkdown20.5 KB
locator-strategy.mdmarkdown20.1 KB
locators.mdmarkdown28.3 KB
mobile-and-responsive.mdmarkdown58.2 KB
multi-context-and-popups.mdmarkdown22.3 KB
multi-user-and-collaboration.mdmarkdown20.0 KB
network-mocking.mdmarkdown44.8 KB
nextjs.mdmarkdown36.1 KB
performance-testing.mdmarkdown23.0 KB
react.mdmarkdown38.6 KB
search-and-filter.mdmarkdown43.2 KB
security-testing.mdmarkdown25.2 KB
service-workers-and-pwa.mdmarkdown20.3 KB
test-architecture.mdmarkdown24.5 KB
test-data-management.mdmarkdown35.7 KB
test-organization.mdmarkdown30.5 KB
third-party-integrations.mdmarkdown30.4 KB
visual-regression.mdmarkdown35.4 KB
vue.mdmarkdown38.6 KB
websockets-and-realtime.mdmarkdown20.8 KB
when-to-mock.mdmarkdown28.0 KB

file-operations.md

View on GitHub
# 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
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: 469kUpdated 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: 469kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 469kUpdated 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