How do you test file downloads?

A download is not a navigation, so a click alone does not give you the file. Start waiting for the download event before the action that triggers it, then use the Download object to save or read the file.

const downloadPromise = page.waitForEvent("download");
await page.getByRole("button", { name: "Export CSV" }).click();

const download = await downloadPromise;
await download.saveAs("downloads/export.csv");

expect(download.suggestedFilename()).toContain(".csv");

What you can do with a download

• download.saveAs(path) copies the file to a location you control
• download.path() returns the temporary file path for reading
• download.suggestedFilename() returns the server's suggested name
• download.failure() returns the failure reason, or null on success
• Set acceptDownloads: false in the context if a test should reject downloads

If the test needs to verify content, read the saved file with Node's file APIs and parse it. That turns a download test from checking that a click happened into checking that the exported data is correct.

import { readFile } from "node:fs/promises";

const downloadPromise = page.waitForEvent("download");
await page.getByRole("button", { name: "Export JSON" }).click();
const download = await downloadPromise;

const path = await download.path();
const raw = await readFile(path, "utf8");
const data = JSON.parse(raw);

expect(data.orders).toHaveLength(3);