Advanced File Uploads in Playwright: Buffers, Directories, and Choosers

An upload test should prove more than the file input accepted a path. Real systems validate names, MIME hints, bytes, size limits, directory structure, malware status, and asynchronous processing. Playwright can supply all of those inputs, but the test must continue until the application exposes a durable accepted or rejected result.

Choose the narrowest upload surface that represents the user workflow. Address a stable file input directly when it exists. Capture a file chooser when the product creates the input dynamically. Generate bytes in memory when the content is the variable under test. Each choice changes what can fail and what evidence the trace will contain.

Map the Upload Lifecycle

The Playwright input documentation supports a path, multiple paths, a directory path, an empty array to clear selection, and in-memory payloads through setInputFiles. Those APIs model selection. Your application's queue, preview, validation, HTTP transfer, scanning, and persistence happen afterward.

Name a terminal state for every test. A displayed filename may be only an optimistic preview. A useful assertion reaches Uploaded, Rejected, or another business status and then checks the detail that matters.

Generate Focused Files in Memory

An in-memory payload removes fixture-directory coupling and makes content intent obvious. The payload needs a filename, MIME type, and Buffer. Treat the MIME type as an input to test, not as proof of the bytes' format; secure servers inspect content independently.

import { test, expect } from '@playwright/test'

test('imports a UTF-8 customer CSV', async ({ page }) => {
  await page.goto('/admin/imports/customers')

  const csv = [
    'email,plan',
    'alex@example.test,starter',
    'sam@example.test,pro',
  ].join('\n')

  await page.getByLabel('Customer CSV').setInputFiles({
    name: 'customers.csv',
    mimeType: 'text/csv',
    buffer: Buffer.from(csv, 'utf8'),
  })

  await page.getByRole('button', { name: 'Start import' }).click()
  await expect(page.getByRole('status')).toHaveText('Import complete')
  await expect(page.getByTestId('import-summary')).toContainText('2 customers created')
})

Memory payloads are ideal for boundary cases: empty files, duplicate CSV headers, a misleading extension, malformed JSON, and exact byte-order markers. For large binary fixtures where streaming and size are the concern, a checked-in or generated disk fixture may use memory more responsibly.

Upload Multiple Files and Directories Intentionally

Pass an array when the input supports multiple files. Keep fixture names unique enough that a failed row identifies the source. Then assert order only if product requirements promise it; browsers and servers may normalize lists differently.

import path from 'node:path'
import { fileURLToPath } from 'node:url'

const here = path.dirname(fileURLToPath(import.meta.url))

test('preserves an evidence directory hierarchy', async ({ page }) => {
  const evidenceTree = path.join(here, 'fixtures', 'incident-204')

  await page.goto('/incidents/204/evidence')
  await page.getByLabel('Evidence directory').setInputFiles(evidenceTree)
  await page.getByRole('button', { name: 'Upload evidence' }).click()

  await expect(page.getByRole('status')).toHaveText('Upload complete')
  await expect(page.getByText('screenshots/home.png')).toBeVisible()
  await expect(page.getByText('logs/browser.log')).toBeVisible()
})

Directory selection depends on an input configured for directory upload. Give the fixture tree its own test-owned directory, avoid secrets, and keep file permissions portable across developer machines and CI containers.

Capture a Dynamic File Chooser Without a Race

Some interfaces hide or create the input only when the user presses an upload button. In that case, start page.waitForEvent('filechooser') before the click, then call setFiles on the captured chooser. This is the same event-ordering discipline used for downloads and popups.

test('attaches a generated diagnostic report', async ({ page }) => {
  await page.goto('/support/tickets/new')

  const chooserPromise = page.waitForEvent('filechooser')
  await page.getByRole('button', { name: 'Attach diagnostics' }).click()
  const chooser = await chooserPromise

  await chooser.setFiles({
    name: 'diagnostics.json',
    mimeType: 'application/json',
    buffer: Buffer.from(JSON.stringify({ build: 'ci', errors: ['E_CONN'] })),
  })

  await expect(page.getByRole('listitem', { name: /diagnostics\.json/ })).toContainText('Ready')
})

Do not use a broad permanent chooser listener for a single action. It can consume a later chooser and make the relationship between click and selected file unclear.

Assert Processing Beyond the Browser Selection

Separate client-side preview from server completion. A robust upload test often observes three states: the file appears in the queue, progress or processing begins, and a terminal outcome arrives. Only the last state should unlock downstream assertions.

If the server offers a test-safe API, verify the durable record by an identifier returned in the UI or response. Check useful facts such as original name, computed checksum, parsed row count, media dimensions, and rejection category. Avoid asserting temporary storage paths or generated database identifiers unless those are public contracts.

For background scanning, do not guess a fixed duration. Poll a status endpoint with a bounded assertion or wait for a UI status driven by that endpoint. Capture the final server error when a file is rejected so the test explains whether parsing, policy, or transport failed.

Exercise Metadata and Content Mismatches

File upload security is full of mismatched signals. Test a .png name carrying text bytes, an executable MIME hint on harmless content, duplicate extensions, reserved names, zero-byte content, and names near the product limit. The expected outcome belongs to the application's policy, not to Playwright.

Keep these fixtures inert. A test does not need live malware or destructive content to verify rejection paths; use an approved antivirus test string or a server-side stub only when your security process explicitly permits it. Assert that unsafe content is quarantined or rejected and that error text does not reveal internal paths.

Cover Removal, Replacement, and Retry Semantics

Selection is reversible. A user may remove one item from a multiple-file queue, replace a chosen document, or clear the input before submission. Playwright can pass an empty array to setInputFiles to clear browser selection, but the product may also maintain its own upload queue. Assert both surfaces through the UI behavior customers use.

For replacement, upload two files with different names and content-derived markers, remove the first, and verify that only the second reaches processing. For retry, force a controlled transient server response, confirm that the failed row preserves enough identity for the user, then invoke the supported retry action. The backend should not create duplicate records when the first request completed but its response was lost.

Chunked and resumable uploads need an even clearer contract. Verify the session identifier, completed-part accounting, final checksum, and cancellation behavior through test-safe APIs or telemetry. Do not infer resume correctness from a progress bar reaching 100 percent. A server may have assembled corrupt or duplicated parts while the client displayed completion.

Cleanup should distinguish selected-but-unsent files from persisted uploads. Clearing the browser input cannot delete an object already stored by the server, so test teardown must use the uploaded resource identifier rather than its potentially nonunique filename.

Diagnose Upload Failures by Stage

If setInputFiles fails, verify that the locator reaches an input with type file, that it is unique, and that paths resolve from the process working directory. If a chooser wait times out, inspect whether the click was actionable and whether the product opened a native chooser at all.

If selection succeeds but no request appears, inspect client validation and disabled submit state. If the request fails, retain response status and application error details. If processing never finishes, query the job record, worker logs, queue state, and object storage metadata. Increasing a UI timeout cannot fix a dead background worker.

Parallel-only failures usually indicate shared fixture paths, filename collisions, or backend deduplication. In-memory files and per-test entity identifiers reduce those collisions without adding arbitrary sleeps.

Balance Helpers Against Visible Test Intent

A helper that builds a payload can centralize encoding and default MIME types. A page object can expose the input and final status. Keep the scenario's content and expected policy visible, especially for negative tests.

type UploadPayload = {
  name: string
  mimeType: string
  buffer: Buffer
}

function textFile(name: string, text: string, mimeType = 'text/plain'): UploadPayload {
  return { name, mimeType, buffer: Buffer.from(text, 'utf8') }
}

Do not build one helper that uploads, waits, calls an API, and asserts a generic success toast. That design makes a parsing test and a storage test look identical and hides the stage that failed.

Run the Upload Operations Checklist

• Decide whether the contract requires a direct input, chooser, file list, or directory.
• Use deterministic bytes and names, with per-test identity where collisions matter.
• Register the file chooser promise before its trigger.
• Assert queue state separately from completed processing.
• Validate a content-derived fact, not only the displayed filename.
• Cover type, size, empty content, malformed content, and duplicate-policy failures.
• Keep fixture trees portable and free of credentials or personal data.
• Preserve request, job, and rejection evidence when CI fails.

End at a Durable Upload Result

Build every upload test around a terminal product outcome. Select the payload through the simplest faithful surface, retain the file's intentional metadata, and follow it through validation and processing. When the test can say exactly which stage rejected or accepted the bytes, it becomes useful for client regressions, API defects, worker failures, and security policy changes instead of merely confirming that a filename appeared.