Playwright File Download Testing Guide with waitForEvent and saveAs

Playwright file download queries usually come from teams who already automated the UI flow and now need to validate the generated artifact. Exports, statements, reports, and invoices are high-value outputs, so download checks often matter more than one more click-path assertion.

Key Takeaways

Start waiting for the download before clicking the export action.
Save the file to a known location if you need to assert on contents or hand it to another step.
Check filename and file existence, not just that the button was clicked.
Keep generated artifacts inside test output folders so cleanup stays predictable.

Why This Topic Matters in 2026

Download flows validate both the front-end trigger and the backend file generation pipeline.
Good download tests catch empty exports, incorrect filenames, broken MIME behavior, and authorization mistakes.
The CLI skill helps teams inspect export behavior manually before encoding it into reusable automation.

Practical Workflow

Step 1: Wait for the download event first

The event ordering rule is the same as popups and choosers: start listening before the action that triggers the file.

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

Step 2: Persist the artifact when the file matters to the test

If the business logic depends on what was exported, save it and assert on the file path or contents.

await download.saveAs('test-results/reports/export.csv');
expect(await download.suggestedFilename()).toContain('export');

Step 3: Use CLI-driven reproduction for flaky export buttons

This is helpful when you need to prove whether the problem is the browser trigger, the export route, or the generated file itself.

playwright-cli open https://example.com/reports
playwright-cli snapshot
playwright-cli click e9
playwright-cli network

Where the Playwright CLI Skill Fits

This is exactly where Playwright CLI Browser Automation adds value. The skill gives your agent stable guidance for snapshots, uploads, downloads, tab handling, tracing, screenshots, PDFs, and fast browser investigation without forcing you to reinvent the command flow every time.

If you are building out a broader QA workflow, keep the skill installed and pair it with the wider QASkills.sh skills directory catalog so your agent can switch between browser automation, API testing, CI, accessibility, and reporting with less context loss.

Common Mistakes to Avoid

Clicking the export button and only asserting on toast messages instead of the actual download object.
Saving files into random working directories that later break CI cleanup.
Skipping authorization checks on export endpoints for admin-only data.
Treating filename assertions as enough when the file body can still be empty or malformed.

Conclusion

Download testing gets much stronger when you validate the artifact boundary, not just the click. Capture the event correctly, save the file when it matters, and keep the test output path deterministic.