Downloading files is a common task in test automation. It is useful when you need to check if your app is generating or exporting data correctly. With Playwright, this process is simple and reliable. In this guide, you will learn how to download a file in Playwright step by step. You will also see clear examples for both beginners and professionals.
Playwright has built-in methods to handle file downloads. You don’t need messy workarounds. You can capture the file path, validate the file name, or check its content.
By the end of this tutorial, you will know how to set up, trigger, and verify file downloads in your automated tests.
If you are new to Playwright, you might want to start with our detailed Playwright Automation Tutorial before diving into file downloads.
Introduction to File Downloads in Playwright
When automating tests, file downloads are often important. They help verify your application’s functionality. For example, you may need to test if a report, invoice, or CSV export works correctly. In many frameworks, handling downloads can be tricky. This is often due to browser restrictions. But Playwright makes it easy and dependable.
With Playwright, you can listen for the file download event. You can capture the file path and save it to a specific location. This allows you to trigger the download and check if the correct file is received. Whether you work with PDFs, images, CSVs, Excel, or data exports, Playwright handles downloads with accuracy. This also helps you avoid flaky test failures.
Steps to Download a File in Playwright
File downloading in Playwright has three main steps.
- Download the file from the browser.
- Save the file to your desired location on your system.
- Check the downloaded file exists
Let’s look at all three steps one by one
Step #1: Download File Using waitForEvent(‘download’) Method
The waitForEvent(‘download’) method is the most common way to handle file downloads in Playwright. It works by listening for a specific browser event that signals a download has started. This ensures your script waits for the download to begin before taking further actions.
In a typical case, you first listen for the download event before clicking the button or link. When the event occurs, Playwright quickly captures the download object. Then, you can check the file name, suggested path, or save it to a custom location.
This method is highly reliable. It removes the guesswork of adding arbitrary delays or sleeps in your tests. Instead of waiting blindly, your code reacts exactly when the browser begins the download.
Syntax to Download File:
//Waiting for download event occurs
const downloadPromise = page.waitForEvent('download');
//Start download
await page.getByRole('link', { name: 'Download PDF' }).click(); //You can use another locator.
//Await the download object
const download = await downloadPromise;The above syntax will click on the Download PDF link to start download.
Here’s the basic workflow:
- Start waiting for the download event.
- Trigger the download action (for example, click a “Download” button).
- Access the download object to get information like the file path or name.
Because it listens directly to the browser event, waitForEvent(‘download’) works across different file types such as PDFs, images, and CSVs. It’s one of the most dependable techniques for verifying file downloads in automated tests.
Step #2: Save the File to Your Desired Location
After capturing a file download in Playwright, the next step is to save it. Playwright provides a built-in method called saveAs() for this task.
The saveAs() method lets you store the file in a specific location on your system. You can choose the exact folder and file name. This is useful when you want organized storage for test files.
Saving the file makes it easy to review, share, or use for further validations. For example, you can open the file later to check its content or confirm that it matches the expected format.
Syntax to save the Downloaded File:
const suggested = await download.suggestedFilename();
const filePath = `./downloads/${suggested}`;
await download.saveAs(filePath);The above syntax will save the downloaded file in the downloads folder located in your workspace.
Step #3: Verify the downloaded file exists
After you download and save a file, it’s important to confirm that the file is actually there in the location you expected. This step ensures the download was successful and the file is ready to use. You can quickly check this with the simple code example shown below.
Syntax to assert if the file exists:
const fileExists = fs.existsSync(filePath);
await expect.soft(fileExists, `File should be saved at ${filePath}`).toBeTruthy();The above syntax makes sure the file is available at the given file path, so you know the download worked correctly.
Playwright File Download Test Complete Example
Here’s a complete example that downloads a file, saves it, and then verifies whether it was successfully saved at the desired location.
const { test, expect } = require('@playwright/test');
const fs = require('fs');
test('Playwright download file example', async ({ page }) => {
await page.goto('https://only-testing-blog.blogspot.com/2014/05/login.html');
// Wait for download event
const downloadPromise = page.waitForEvent('download');
await page.getByRole('link', { name: 'Download Text File' }).click();
const download = await downloadPromise;
// Save the file in the desired location
const suggested = await download.suggestedFilename();
const filePath = `./downloads/${suggested}`;
await download.saveAs(filePath);
// Soft assertion: Check if file exists
const fileExists = fs.existsSync(filePath);
await expect.soft(fileExists, `File should be saved at ${filePath}`).toBeTruthy();
});When you run the above example, it will download the file, save it, and then verify that it exists.
Best Practices for File Downloads
- Always wait for the download event before saving the file.
- Store files in a dedicated downloads folder for easy cleanup.
- Use assertions to verify that the downloaded file matches the expected format or size.
- Run tests in headless mode for CI/CD pipelines unless debugging.
Final Words
Learning how to download a File in Playwright is a valuable skill for automating modern web testing. With the right syntax, you can easily trigger downloads, save them to a specific folder, and verify the file’s presence. This process ensures your tests are more reliable, accurate, and closer to real user interactions. Whether you are a beginner or an experienced tester, mastering this feature will help you handle file-based workflows with confidence.
FAQs – Playwright File Download
How do I download a file in Playwright?
You can use page.waitForEvent('download') to wait for the download, then use download.saveAs() to save it.
Can I get the file name of a downloaded file in Playwright?
Yes, use download.suggestedFilename() to retrieve the file name suggested by the browser.
Does Playwright support file downloads in headless mode?
Yes, file downloads work in both headless and headed modes without extra configuration.
Where does Playwright store downloaded files by default?
By default, Playwright stores files in a temporary location, but you can save them anywhere using saveAs().
Hi, I’m Aravind — a seasoned Automation Test Engineer with over 17 years of hands-on experience in the software testing industry. I specialize in tech troubleshooting and tools like Selenium, Playwright, Appium, JMeter, and Excel automation. Through this blog, I share practical tutorials, expert tips, and real-world insights to help testers and developers improve their automation skills.In addition to software testing, I also explore tech trends and user-focused topics, including Snapchat guides, codeless test automation, and more.
