Implementation:Microsoft Playwright Client Download

Knowledge Sources	Microsoft_Playwright
Domains	Browser Automation, File Management
Last Updated	2026-02-12 00:00 GMT

Overview

Concrete tool for representing file downloads triggered by browser page interactions provided by the Playwright library.

Description

The Download class implements the api.Download interface and serves as a high-level wrapper around a download event. It stores the originating Page, the download URL, the browser-suggested filename, and an underlying Artifact that provides the actual file operations. All file I/O methods (path(), saveAs(), failure(), createReadStream(), cancel(), delete()) delegate directly to the Artifact instance. This separation allows the download metadata to remain lightweight while the artifact handles streaming and persistence concerns.

Usage

Use the Download class to manage files downloaded during browser automation. Obtain instances by listening to the 'download' event on a Page. The download must be saved or consumed before the browser context is closed.

Code Reference

Source Location

• Repository: Microsoft_Playwright
• File: packages/playwright-core/src/client/download.ts

Signature

export class Download implements api.Download {
  constructor(page: Page, url: string, suggestedFilename: string, artifact: Artifact);

  page(): Page;
  url(): string;
  suggestedFilename(): string;
  async path(): Promise<string>;
  async saveAs(path: string): Promise<void>;
  async failure(): Promise<string | null>;
  async createReadStream(): Promise<Readable>;
  async cancel(): Promise<void>;
  async delete(): Promise<void>;
}

Import

import { Download } from 'playwright-core/src/client/download';

I/O Contract

Inputs

Name	Type	Required	Description
page	Page	Yes	The page that triggered the download
url	string	Yes	The URL of the downloaded resource
suggestedFilename	string	Yes	The filename suggested by the browser
artifact	Artifact	Yes	The underlying artifact managing the downloaded file
path (saveAs)	string	Yes	Destination path for saving the downloaded file

Outputs

Name	Type	Description
page()	Page	The page that initiated the download
url()	string	The URL of the download
suggestedFilename()	string	The browser-suggested filename
path()	Promise<string>	The local file path (throws if remote)
failure()	null>	Error string if download failed, null otherwise

Usage Examples

const downloadPromise = page.waitForEvent('download');
await page.click('a[download]');
const download = await downloadPromise;

console.log('URL:', download.url());
console.log('Suggested filename:', download.suggestedFilename());

// Save to a specific path
await download.saveAs('/tmp/downloads/' + download.suggestedFilename());

// Check for failure
const error = await download.failure();
if (error) {
  console.error('Download failed:', error);
}

// Clean up
await download.delete();

Related Pages

• Environment:Microsoft_Playwright_Node_Runtime_Environment