docs: examples that save download with suggested filename (#26425)

Fixes #26341.
microsoft · Aug 11, 2023 · b899d61 · b899d61
1 parent d0fec20
commit b899d61
Show file tree

Hide file tree

Showing 3 changed files with 74 additions and 42 deletions.
diff --git a/docs/src/api/class-download.md b/docs/src/api/class-download.md
@@ -6,49 +6,59 @@
 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.
 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
@@ -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,34 +42,30 @@ 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
 # 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()
-# 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
 // 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
-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
@@ -16725,16 +16725,16 @@ 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.
  * 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());
  * ```
  *
  */
@@ -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<void>;