From b899d61a516f2a2018c4218d728a732e28611a38 Mon Sep 17 00:00:00 2001 From: Dmitry Gozman Date: Thu, 10 Aug 2023 17:20:39 -0700 Subject: [PATCH] docs: examples that save download with suggested filename (#26425) Fixes #26341. --- docs/src/api/class-download.md | 64 +++++++++++++++++------ docs/src/downloads.md | 39 ++++++-------- packages/playwright-core/types/types.d.ts | 13 +++-- 3 files changed, 74 insertions(+), 42 deletions(-) diff --git a/docs/src/api/class-download.md b/docs/src/api/class-download.md index de09ad8d3384a..2ae2da377cb30 100644 --- a/docs/src/api/class-download.md +++ b/docs/src/api/class-download.md @@ -6,7 +6,7 @@ All the downloaded files belonging to the browser context are deleted when the browser context is closed. -Download event is emitted once the download starts. Download path becomes available once download completes: +Download event is emitted once the download starts. Download path becomes available once download completes. ```js // Start waiting for download before clicking. Note no await. @@ -14,41 +14,51 @@ const downloadPromise = page.waitForEvent('download'); await page.getByText('Download file').click(); const download = await downloadPromise; -// Wait for the download process to complete. -console.log(await download.path()); +// Wait for the download process to complete and save the downloaded file somewhere. +await download.saveAs('/path/to/save/at/' + download.suggestedFilename()); ``` ```java -// wait for download to start +// Wait for the download to start Download download = page.waitForDownload(() -> { - page.getByText("Download file").click(); + // Perform the action that initiates download + page.getByText("Download file").click(); }); -// wait for download to complete -Path path = download.path(); + +// Wait for the download process to complete and save the downloaded file somewhere +download.saveAs(Paths.get("/path/to/save/at/", download.suggestedFilename())); ``` ```python async +# Start waiting for the download async with page.expect_download() as download_info: + # Perform the action that initiates download await page.get_by_text("Download file").click() download = await download_info.value -# waits for download to complete -path = await download.path() + +# Wait for the download process to complete and save the downloaded file somewhere +await download.save_as("/path/to/save/at/" + download.suggested_filename) ``` ```python sync +# Start waiting for the download with page.expect_download() as download_info: + # Perform the action that initiates download page.get_by_text("Download file").click() download = download_info.value -# wait for download to complete -path = download.path() + +# Wait for the download process to complete and save the downloaded file somewhere +download.save_as("/path/to/save/at/" + download.suggested_filename) ``` ```csharp -var download = await page.RunAndWaitForDownloadAsync(async () => -{ - await page.GetByText("Download file").ClickAsync(); -}); -Console.WriteLine(await download.PathAsync()); +// Start the task of waiting for the download before clicking +var waitForDownloadTask = page.WaitForDownloadAsync(); +await page.GetByText("Download file").ClickAsync(); +var download = await waitForDownloadTask; + +// Wait for the download process to complete and save the downloaded file somewhere +await download.SaveAsAsync("/path/to/save/at/" + download.SuggestedFilename); ``` ## async method: Download.cancel @@ -97,6 +107,28 @@ to get suggested file name. Copy the download to a user-specified path. It is safe to call this method while the download is still in progress. Will wait for the download to finish if necessary. +**Usage** + +```js +await download.saveAs('/path/to/save/at/' + download.suggestedFilename()); +``` + +```java +download.saveAs(Paths.get("/path/to/save/at/", download.suggestedFilename())); +``` + +```python async +await download.save_as("/path/to/save/at/" + download.suggested_filename) +``` + +```python sync +download.save_as("/path/to/save/at/" + download.suggested_filename) +``` + +```csharp +await download.SaveAsAsync("/path/to/save/at/" + download.SuggestedFilename); +``` + ### param: Download.saveAs.path * since: v1.8 - `path` <[path]> diff --git a/docs/src/downloads.md b/docs/src/downloads.md index d95531c824a40..12c9a142c02d8 100644 --- a/docs/src/downloads.md +++ b/docs/src/downloads.md @@ -5,7 +5,7 @@ title: "Downloads" -For every attachment downloaded by the page, [`event: Page.download`] event is emitted. All these attachments are downloaded into a temporary folder. You can obtain the download url, file system path and payload stream using the [Download] object from the event. +For every attachment downloaded by the page, [`event: Page.download`] event is emitted. All these attachments are downloaded into a temporary folder. You can obtain the download url, file name and payload stream using the [Download] object from the event. You can specify where to persist downloaded files using the [`option: downloadsPath`] option in [`method: BrowserType.launch`]. @@ -20,10 +20,9 @@ Here is the simplest way to handle the file download: const downloadPromise = page.waitForEvent('download'); await page.getByText('Download file').click(); const download = await downloadPromise; -// Wait for the download process to complete -console.log(await download.path()); -// Save downloaded file somewhere -await download.saveAs('/path/to/save/download/at.txt'); + +// Wait for the download process to complete and save the downloaded file somewhere. +await download.saveAs('/path/to/save/at/' + download.suggestedFilename()); ``` ```java @@ -32,11 +31,9 @@ Download download = page.waitForDownload(() -> { // Perform the action that initiates download page.getByText("Download file").click(); }); -// Wait for the download process to complete -Path path = download.path(); -System.out.println(download.path()); -// Save downloaded file somewhere -download.saveAs(Paths.get("/path/to/save/download/at.txt")); + +// Wait for the download process to complete and save the downloaded file somewhere +download.saveAs(Paths.get("/path/to/save/at/", download.suggestedFilename())); ``` ```python async @@ -45,10 +42,9 @@ async with page.expect_download() as download_info: # Perform the action that initiates download await page.get_by_text("Download file").click() download = await download_info.value -# Wait for the download process to complete -print(await download.path()) -# Save downloaded file somewhere -await download.save_as("/path/to/save/download/at.txt") + +# Wait for the download process to complete and save the downloaded file somewhere +await download.save_as("/path/to/save/at/" + download.suggested_filename) ``` ```python sync @@ -56,12 +52,10 @@ await download.save_as("/path/to/save/download/at.txt") with page.expect_download() as download_info: # Perform the action that initiates download page.get_by_text("Download file").click() -# Wait for the download to start download = download_info.value -# Wait for the download process to complete -print(download.path()) -# Save downloaded file somewhere -download.save_as("/path/to/save/download/at.txt") + +# Wait for the download process to complete and save the downloaded file somewhere +download.save_as("/path/to/save/at/" + download.suggested_filename) ``` ```csharp @@ -69,10 +63,9 @@ download.save_as("/path/to/save/download/at.txt") var waitForDownloadTask = page.WaitForDownloadAsync(); await page.GetByText("Download file").ClickAsync(); var download = await waitForDownloadTask; -// Wait for the download process to complete -Console.WriteLine(await download.PathAsync()); -// Save downloaded file somewhere -await download.SaveAsAsync("/path/to/save/download/at.txt"); + +// Wait for the download process to complete and save the downloaded file somewhere +await download.SaveAsAsync("/path/to/save/at/" + download.SuggestedFilename); ``` #### Variations diff --git a/packages/playwright-core/types/types.d.ts b/packages/playwright-core/types/types.d.ts index 885afeb06297e..77010035b489d 100644 --- a/packages/playwright-core/types/types.d.ts +++ b/packages/playwright-core/types/types.d.ts @@ -16725,7 +16725,7 @@ export interface Dialog { * * All the downloaded files belonging to the browser context are deleted when the browser context is closed. * - * Download event is emitted once the download starts. Download path becomes available once download completes: + * Download event is emitted once the download starts. Download path becomes available once download completes. * * ```js * // Start waiting for download before clicking. Note no await. @@ -16733,8 +16733,8 @@ export interface Dialog { * await page.getByText('Download file').click(); * const download = await downloadPromise; * - * // Wait for the download process to complete. - * console.log(await download.path()); + * // Wait for the download process to complete and save the downloaded file somewhere. + * await download.saveAs('/path/to/save/at/' + download.suggestedFilename()); * ``` * */ @@ -16778,6 +16778,13 @@ export interface Download { /** * Copy the download to a user-specified path. It is safe to call this method while the download is still in progress. * Will wait for the download to finish if necessary. + * + * **Usage** + * + * ```js + * await download.saveAs('/path/to/save/at/' + download.suggestedFilename()); + * ``` + * * @param path Path where the download should be copied. */ saveAs(path: string): Promise;