how to test file downloads across browsers

TL;DR

Do not assert on real files landing in a downloads folder; it is slow and platform-dependent. Instead, use the framework's download event (Playwright's download event, Cypress's download handling via intercepted responses or plugins), wait for the download to complete, read the file from its temp path, and assert on the contents. Test across Chromium, Firefox, and WebKit because filename encoding and content-disposition handling differ between browsers.

The query

how to test file downloads across browsers

Use this when

• E2E tests cover export, report, or receipt downloads.
• Downloads behave differently per browser.

Not for

• File upload testing.
• Testing the download server itself; use API tests for that.

Steps

1. Set up the framework's download interception and point downloads at a temp directory. Expected output: downloads are captured, not written to the real folder.
2. Trigger the download in the test and wait for the download event to complete. Expected output: the test proceeds only when the file is fully written.
3. Read the file and assert on its contents (parse the CSV, check PDF text, compare bytes). Expected output: content assertions, not just "a file appeared".
4. Run the same test on Chromium, Firefox, and WebKit. Expected output: all three pass, or you have a documented browser difference.
5. Clean up temp files in an after-hook. Expected output: no leftover files between runs.

Provenance

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