From e5d686405623488e808b9aaf85083fb24f0894fa Mon Sep 17 00:00:00 2001 From: jrandolf <101637635+jrandolf@users.noreply.github.com> Date: Fri, 21 Apr 2023 14:15:19 +0200 Subject: [PATCH] docs: improve docs on file upload (#10058) --- docs/api/puppeteer.elementhandle.md | 2 +- docs/api/puppeteer.elementhandle.uploadfile.md | 16 ++++++++++------ docs/api/puppeteer.filechooser.accept.md | 14 +++++++++----- docs/api/puppeteer.filechooser.md | 10 +++++----- packages/puppeteer-core/src/api/ElementHandle.ts | 15 ++++++++------- .../puppeteer-core/src/common/FileChooser.ts | 12 +++++++----- 6 files changed, 40 insertions(+), 29 deletions(-) diff --git a/docs/api/puppeteer.elementhandle.md b/docs/api/puppeteer.elementhandle.md index 68f67ceabf1..3e22365b7b8 100644 --- a/docs/api/puppeteer.elementhandle.md +++ b/docs/api/puppeteer.elementhandle.md @@ -80,6 +80,6 @@ The constructor for this class is marked as internal. Third-party code should no | [touchMove(this)](./puppeteer.elementhandle.touchmove.md) | | | | [touchStart(this)](./puppeteer.elementhandle.touchstart.md) | | | | [type(text, options)](./puppeteer.elementhandle.type.md) | |

Focuses the element, and then sends a keydown, keypress/input, and keyup event for each character in the text.

To press a special key, like Control or ArrowDown, use [ElementHandle.press()](./puppeteer.elementhandle.press.md).

| -| [uploadFile(this, filePaths)](./puppeteer.elementhandle.uploadfile.md) | | This method expects elementHandle to point to an [input element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input). | +| [uploadFile(this, paths)](./puppeteer.elementhandle.uploadfile.md) | | Sets the value of an [input element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input) to the given file paths. | | [waitForSelector(selector, options)](./puppeteer.elementhandle.waitforselector.md) | |

Wait for an element matching the given selector to appear in the current element.

Unlike [Frame.waitForSelector()](./puppeteer.frame.waitforselector.md), this method does not work across navigations or if the element is detached from DOM.

| | [waitForXPath(xpath, options)](./puppeteer.elementhandle.waitforxpath.md) | | | diff --git a/docs/api/puppeteer.elementhandle.uploadfile.md b/docs/api/puppeteer.elementhandle.uploadfile.md index 4024eda91d3..f9212438a82 100644 --- a/docs/api/puppeteer.elementhandle.uploadfile.md +++ b/docs/api/puppeteer.elementhandle.uploadfile.md @@ -4,7 +4,7 @@ sidebar_label: ElementHandle.uploadFile # ElementHandle.uploadFile() method -This method expects `elementHandle` to point to an [input element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input). +Sets the value of an [input element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input) to the given file paths. #### Signature: @@ -12,18 +12,22 @@ This method expects `elementHandle` to point to an [input element](https://devel class ElementHandle { uploadFile( this: ElementHandle, - ...filePaths: string[] + ...paths: string[] ): Promise; } ``` ## Parameters -| Parameter | Type | Description | -| --------- | --------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| this | [ElementHandle](./puppeteer.elementhandle.md)<HTMLInputElement> | | -| filePaths | string\[\] | Sets the value of the file input to these paths. If a path is relative, then it is resolved against the [current working directory](https://nodejs.org/api/process.html#process_process_cwd). Note for locals script connecting to remote chrome environments, paths must be absolute. | +| Parameter | Type | Description | +| --------- | --------------------------------------------------------------------- | ----------- | +| this | [ElementHandle](./puppeteer.elementhandle.md)<HTMLInputElement> | | +| paths | string\[\] | | **Returns:** Promise<void> + +## Remarks + +This will not validate whether the file paths exists. Also, if a path is relative, then it is resolved against the [current working directory](https://nodejs.org/api/process.html#process_process_cwd). For locals script connecting to remote chrome environments, paths must be absolute. diff --git a/docs/api/puppeteer.filechooser.accept.md b/docs/api/puppeteer.filechooser.accept.md index 93f573bbb7e..b5cd9e3035a 100644 --- a/docs/api/puppeteer.filechooser.accept.md +++ b/docs/api/puppeteer.filechooser.accept.md @@ -4,22 +4,26 @@ sidebar_label: FileChooser.accept # FileChooser.accept() method -Accept the file chooser request with given paths. +Accept the file chooser request with the given file paths. #### Signature: ```typescript class FileChooser { - accept(filePaths: string[]): Promise; + accept(paths: string[]): Promise; } ``` ## Parameters -| Parameter | Type | Description | -| --------- | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| filePaths | string\[\] | If some of the filePaths are relative paths, then they are resolved relative to the [current working directory](https://nodejs.org/api/process.html#process_process_cwd). | +| Parameter | Type | Description | +| --------- | ---------- | ----------- | +| paths | string\[\] | | **Returns:** Promise<void> + +## Remarks + +This will not validate whether the file paths exists. Also, if a path is relative, then it is resolved against the [current working directory](https://nodejs.org/api/process.html#process_process_cwd). For locals script connecting to remote chrome environments, paths must be absolute. diff --git a/docs/api/puppeteer.filechooser.md b/docs/api/puppeteer.filechooser.md index afa5998c956..9e9dfe718c8 100644 --- a/docs/api/puppeteer.filechooser.md +++ b/docs/api/puppeteer.filechooser.md @@ -32,8 +32,8 @@ await fileChooser.accept(['/tmp/myfile.pdf']); ## Methods -| Method | Modifiers | Description | -| ------------------------------------------------------ | --------- | --------------------------------------------------------------------------------------------------------------------------------------------- | -| [accept(filePaths)](./puppeteer.filechooser.accept.md) | | Accept the file chooser request with given paths. | -| [cancel()](./puppeteer.filechooser.cancel.md) | | Closes the file chooser without selecting any files. | -| [isMultiple()](./puppeteer.filechooser.ismultiple.md) | | Whether file chooser allow for [multiple](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/file#attr-multiple) file selection. | +| Method | Modifiers | Description | +| ----------------------------------------------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------- | +| [accept(paths)](./puppeteer.filechooser.accept.md) | | Accept the file chooser request with the given file paths. | +| [cancel()](./puppeteer.filechooser.cancel.md) | | Closes the file chooser without selecting any files. | +| [isMultiple()](./puppeteer.filechooser.ismultiple.md) | | Whether file chooser allow for [multiple](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/file#attr-multiple) file selection. | diff --git a/packages/puppeteer-core/src/api/ElementHandle.ts b/packages/puppeteer-core/src/api/ElementHandle.ts index 8b9aafccf5c..a229aa98515 100644 --- a/packages/puppeteer-core/src/api/ElementHandle.ts +++ b/packages/puppeteer-core/src/api/ElementHandle.ts @@ -702,18 +702,19 @@ export class ElementHandle< } /** - * This method expects `elementHandle` to point to an - * {@link https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input | input element}. + * Sets the value of an + * {@link https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input | input element} + * to the given file paths. * - * @param filePaths - Sets the value of the file input to these paths. - * If a path is relative, then it is resolved against the + * @remarks This will not validate whether the file paths exists. Also, if a + * path is relative, then it is resolved against the * {@link https://nodejs.org/api/process.html#process_process_cwd | current working directory}. - * Note for locals script connecting to remote chrome environments, - * paths must be absolute. + * For locals script connecting to remote chrome environments, paths must be + * absolute. */ async uploadFile( this: ElementHandle, - ...filePaths: string[] + ...paths: string[] ): Promise; async uploadFile(this: ElementHandle): Promise { throw new Error('Not implemented'); diff --git a/packages/puppeteer-core/src/common/FileChooser.ts b/packages/puppeteer-core/src/common/FileChooser.ts index b776d71e38d..96d6e6eb283 100644 --- a/packages/puppeteer-core/src/common/FileChooser.ts +++ b/packages/puppeteer-core/src/common/FileChooser.ts @@ -67,19 +67,21 @@ export class FileChooser { } /** - * Accept the file chooser request with given paths. + * Accept the file chooser request with the given file paths. * - * @param filePaths - If some of the `filePaths` are relative paths, then - * they are resolved relative to the + * @remarks This will not validate whether the file paths exists. Also, if a + * path is relative, then it is resolved against the * {@link https://nodejs.org/api/process.html#process_process_cwd | current working directory}. + * For locals script connecting to remote chrome environments, paths must be + * absolute. */ - async accept(filePaths: string[]): Promise { + async accept(paths: string[]): Promise { assert( !this.#handled, 'Cannot accept FileChooser which is already handled!' ); this.#handled = true; - await this.#element.uploadFile(...filePaths); + await this.#element.uploadFile(...paths); } /**