playwright download event never fired in headless: how to fix

TL;DR

Downloads work headless; the usual miss is clicking before listening. Start page.waitForEvent('download') before the click using Promise.all, and make sure the browser context was created with acceptDownloads set to true.

The query

playwright download event never fired in headless: how to fix

Use this when

• download event never fires in headless mode
• download.path() hangs forever
• export-button tests fail only in CI

Not for

• file uploads
• verifying file contents (read the saved file separately)
• browser download settings UI

Steps

1. Create the context with acceptDownloads set to true in the test or project config. Expected output: the context options include acceptDownloads true.
2. Restructure so the listener starts before the click: await Promise.all with page.waitForEvent('download') and the click together. Expected output: the waitForEvent promise is created before the click promise.
3. Await download.path() to confirm the file landed, and assert on the suggested filename. Expected output: a real file path on disk and the expected filename.
4. If the download opens in a new tab, wait for the new page on the context and listen for the download there. Expected output: the download is captured from the correct page.
5. Run headless and headed to confirm both modes capture the file. Expected output: passing runs in both modes with the file saved.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_4NloQitH8N2NW6AU6oyJKA