Skip to main content
Free plan, no cardStart free

EngineeringHow-to guide

How to Test File Downloads with Playwright: the Download Event, the Race It Must Win, and the WebKit Case

A download test has two halves: catching the event, and checking the file. We ran both in three engines, and one engine never raised the event for a plain attachment link.

Summarise with AI

Opens a new chat with only this request: Summarise the key points of this article: https://dokimore.com/blog/how-to-test-file-downloads-with-playwright

1,000 rowsThe CSV the attachment test saved and counted, 16,135 bytes, SHA-256 matching the server’s
1.55 sA download that started 1.5 s after the click, still caught because the wait was armed first
0 eventsDownload events WebKit 26.5 raised for a plain attachment link in two runs of 8 and 30 s
124 msThe same WebKit, same file, when the link carried the HTML download attribute

In short

  • Arm the wait first, then click: `const [download] = await Promise.all([page.waitForEvent('download'), page.click('#export')])`. A download that begins after a delay (1.5 s in our fixture) is still caught this way; a wait registered after the click can miss one that starts at once.
  • Check the file, not the event: save it with download.saveAs(), read it back, and compare its hash, size or row count with what the server sent. Our 1,000-row CSV matched byte for byte in Chromium and Firefox.
  • Engines differ. In Playwright 1.62.1’s WebKit 26.5 build on Linux, clicking a plain link to a Content-Disposition: attachment response raised no download event at all, while the same link with the HTML download attribute raised one in 124 ms. Decide what your users’ Safari must do, then test it in WebKit, not only in Chromium.

About this article

Format
How-to guide: a procedure to follow, step by step.
Written for
SDETs and automation engineers · Developers who own their tests · QA leads and test managers
Where it applies
Every market. The rules that differ by country are on the country pages.

A browser test cannot look inside the operating system’s download folder, and it should not try. Playwright turns a download into an event on the page: a Download object with the URL it came from, the file name the server suggested, and a way to save the bytes where the test can read them. Everything after that is ordinary file checking.

This guide was run before it was written: a fixture page with five download shapes and a fixture server, driven by Playwright 1.62.1 in Chromium 151, Firefox 153 and WebKit 26.5. The numbers, the file names and the one engine that behaved differently are from that run; the scripts and the raw output are linked at the end.

The shape of every download test

Three steps, in this order: arm the wait for the download event, trigger the download, then await the event. The order matters because the event can fire before the click resolves; Playwright’s own documentation puts the wait first for this reason. Then save the file somewhere the test owns and assert on the content.

download.spec.ts — an attachment link, saved and checked
import { test, expect } from '@playwright/test';
import { createHash } from 'node:crypto';
import { readFileSync } from 'node:fs';

test('the CSV export downloads with the right name and every row', async ({ page }, testInfo) => {
  await page.goto('/exports');

  const [download] = await Promise.all([
    page.waitForEvent('download'),                  // armed before the click
    page.getByRole('link', { name: 'Export CSV' }).click(),
  ]);

  expect(download.suggestedFilename()).toBe('orders-2026-11-04.csv');
  const saved = testInfo.outputPath('orders.csv');
  await download.saveAs(saved);
  expect(await download.failure()).toBeNull();     // null means the download completed

  const bytes = readFileSync(saved);
  const rows = bytes.toString('utf8').trim().split('\n').length - 1; // minus the header
  expect(rows).toBe(1000);
  expect(createHash('sha256').update(bytes).digest('hex')).toBe(process.env.EXPECTED_SHA256);
});

Five download shapes, three engines

Chromium and Firefox agreed on every case. The inline PDF is worth a line: both engines raised a popup event for the new tab and a download event for the PDF, and in Chromium the order differed between two runs, so a test for that page should wait for both with their own timeouts rather than race them.

Measured on 2026-11-04, Playwright 1.62.1; the attachment is a 1,000-row CSV of 16,135 bytes
CaseChromium 151Firefox 153WebKit 26.5
Link to Content-Disposition: attachmentevent; name, bytes and hash matchevent; name, bytes and hash matchno event in 30 s (run 1) and 8 s (run 2)
Blob built in the page, anchor with download="notes.txt"event; blob: URL; content matchesevent; blob: URL; content matchesnot reached: the run stopped at the first case
Download started 1.5 s after the clickevent at 1,552 ms; hash matchesevent at 1,581 ms; hash matchesnot reached
Inline PDF opened in a new tab (target=_blank)both a popup and a download event (order varied between runs)both; the download event came firstnot reached
Export route answers 500no download event; the page navigated to the errorno download event; the page navigated to the errornot reached
WebKit probe: same attachment link with the HTML download attribute——event in 124 ms, name x.csv
WebKit probe: page.goto() straight to the attachment URL——a Response object, no download event

The WebKit case

In WebKit the first case stalled: a click on a plain link to a Content-Disposition: attachment response raised no download event within 30 seconds in the first run and 8 seconds in the second, and the click itself did not resolve. A second script tried four ways of starting the same download in WebKit alone. The link with the HTML download attribute raised the event in 124 ms and saved the file. A plain link, a page.goto() to the attachment URL and a click dispatched from page.evaluate() all raised nothing; the goto returned an ordinary Response.

This is a property of the Playwright WebKit build on Linux in headless mode as we ran it, in Playwright 1.62.1; it is not necessarily what Safari on a Mac does, and the Playwright issue tracker has long held reports of WebKit showing files inline rather than downloading them. What it means for a test: if your users are on Safari, decide what the product must do there, give download links the download attribute where the file is same-origin (the attribute is ignored for cross-origin URLs), and run the download tests in WebKit rather than assuming the Chromium result carries over.

The late download, the blob and the failure

Three cases a suite usually forgets. A download that begins after work on the server, 1.5 seconds in the fixture, is caught by the armed wait with a timeout generous enough for the real server. A file generated in the browser, a Blob behind an anchor with the download attribute, arrives through the same event with a blob: URL. And a server that fails the export does not raise a download event at all: the page navigates to the error response. A test must treat the absence of the event as the failure, which means a bounded wait and an assertion on the response status, not an unbounded wait that times out the whole suite.

download.spec.ts — a failing export is a failed test, quickly
test('a failing export is reported, not waited for', async ({ page }) => {
  await page.goto('/exports');
  const [response] = await Promise.all([
    page.waitForResponse((r) => r.url().endsWith('/broken.csv')),
    page.getByRole('link', { name: 'Broken export' }).click(),
  ]);
  expect(response.status()).toBe(500);
  // No download event fires for a 500; assert on the response and move on.
});

In the product

What to assert on a downloaded file

  • The suggested file name, because the product promised it and a date in it is often wrong by a time zone.
  • The size and a hash against what the server produced, or a row count for a CSV, a page count for a PDF, a record count for JSON.
  • download.failure() is null; a non-null value is the browser’s reason the download did not complete.
  • The content, not only the shape: open the CSV, parse it, check the first and last rows; the generated file can be well formed and wrong.
  • The failure path: a 500, a 403 for a user who may not export, an empty result set, each with a bounded wait.

How Dokimore handles downloads

A recorded step that triggers a download keeps the network call that produced the file, so the replay can assert on the response status and size without the download folder, and the run detail shows the request beside the step. For file content, the workflow canvas’s document steps read the downloaded file and assert on rows or text. The recorder’s five engines include WebKit, which is where a Safari-specific download behaviour like the one above shows up before a customer sees it.

What to do next

  1. Rewrite every download test as arm-the-wait, click, await, saveAs, assert on content; a wait registered after the click is the race that produces the flaky one.
  2. Give same-origin download links the HTML download attribute; it is what made WebKit raise the event in our run, and it costs nothing in the other engines.
  3. Add the failure case for every export: a bounded wait for the response, an assertion on the status, and no download event expected.
  4. Run the download suite in WebKit once before a release if your users are on Safari; the engine differed where the others agreed.
  5. Copy the scripts under "How we measured this" to reproduce the five cases against your own export page.

Questions people ask

How do I wait for a download in Playwright?

Start waiting before you click: `const [download] = await Promise.all([page.waitForEvent('download'), page.click('#export')])`. Then `await download.saveAs(path)` and read the file. In our run this caught a download that started 1.5 seconds after the click; a wait registered after the click can miss one that starts immediately.

How do I verify the downloaded file’s content?

Save it with download.saveAs(), read it back, and compare a hash, the size or a row count with what the server produced. The 1,000-row CSV in our fixture matched the server’s SHA-256 in Chromium and Firefox. Also check download.failure() is null; a value there is the browser’s reason the download did not finish.

Why does my download test fail in WebKit but pass in Chromium?

In Playwright 1.62.1’s WebKit 26.5 build on Linux, a plain link to a Content-Disposition: attachment response raised no download event in our runs, while the same link with the HTML download attribute raised one in 124 ms. Add the attribute for same-origin files, and test what your users’ Safari must do in WebKit rather than assuming the Chromium result.

What happens when the server fails the export?

No download event fires; the page navigates to the error response. Wait for the response with page.waitForResponse, assert its status, and keep the wait bounded. An unbounded wait for a download that never starts times out the whole test for the wrong reason.

How we measured this

  • Run on 2026-11-04 with Playwright 1.62.1 and its pinned builds (Chromium 151.0.7922.34, Firefox 153.0, WebKit 26.5), inside the image that carries those builds, networking disabled, fixtures on 127.0.0.1. Scripts and raw output: docs/marketing/keyword-research/research/playwright-guides-2026-11-04 (e2-download.js, e2b-webkit.js, out/e2-download.json, out/e2b-webkit.json).
  • Two runs of the main script: the first stopped WebKit at its first case after 30 s; the second wrapped each case so a failure would be recorded and still stopped WebKit at the attachment case after 8 s. The WebKit probe then tried four ways of starting the same download with an 8 s bound each. Chromium and Firefox results are from the second run; the inline-PDF event order is reported as it varied between the two runs.
  • The measurements used the library API; the snippets wrap the same calls in Playwright Test. Milliseconds are Date.now() around the click and the event as seen by the test, one run per case per engine.
  • Dokimore’s behaviour is the product code on the article date: a recorded download step keeps its network call and the run detail shows it; the workflow canvas reads downloaded files for content assertions.

Sources

  1. Playwright documentation, Downloads: the download event, waiting before the click, saveAs and suggestedFilename read
  2. MDN, Content-Disposition header: the attachment disposition and the filename parameter read
  3. MDN, the anchor element: the download attribute applies to same-origin, blob: and data: URLs and is ignored elsewhere read
  4. Playwright issue #5396 (closed February 2021): WebKit opened ZIP, PDF and JSON files inline rather than downloading them; the maintainers’ answer and the macOS fix in 1.9.0 read
  5. Playwright documentation, Browsers: each release pins its own browser builds read

See it on your own project

Every new account starts a 14-day Solo Pro trial, then 14 days on the Free plan. No card. Record one flow and measure the difference on your own numbers.

  • Free plan, no card
  • 14-day Solo Pro trial
  • Demo replies within one business day
  • Data hosted in India