Skip to content

Commit

Permalink
docs: improve docs on file upload (#10058)
Browse files Browse the repository at this point in the history
  • Loading branch information
@jrandolf
jrandolf committed Apr 21, 2023
1 parent 23d6a95 commit e5d6864
Show file tree
Hide file tree
Showing 6 changed files with 40 additions and 29 deletions.
2 changes: 1 addition & 1 deletion docs/api/puppeteer.elementhandle.md
View file
Expand Up @@ -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) | | <p>Focuses the element, and then sends a <code>keydown</code>, <code>keypress</code>/<code>input</code>, and <code>keyup</code> event for each character in the text.</p><p>To press a special key, like <code>Control</code> or <code>ArrowDown</code>, use [ElementHandle.press()](./puppeteer.elementhandle.press.md).</p> |
| [uploadFile(this, filePaths)](./puppeteer.elementhandle.uploadfile.md) | | This method expects <code>elementHandle</code> 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) | | <p>Wait for an element matching the given selector to appear in the current element.</p><p>Unlike [Frame.waitForSelector()](./puppeteer.frame.waitforselector.md), this method does not work across navigations or if the element is detached from DOM.</p> |
| [waitForXPath(xpath, options)](./puppeteer.elementhandle.waitforxpath.md) | | |
16 changes: 10 additions & 6 deletions docs/api/puppeteer.elementhandle.uploadfile.md
View file
Expand Up @@ -4,26 +4,30 @@ 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:

```typescript
class ElementHandle {
uploadFile(
this: ElementHandle<HTMLInputElement>,
...filePaths: string[]
...paths: string[]
): Promise<void>;
}
```

## Parameters

| Parameter | Type | Description |
| --------- | --------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| this | [ElementHandle](./puppeteer.elementhandle.md)&lt;HTMLInputElement&gt; | |
| 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)&lt;HTMLInputElement&gt; | |
| paths | string\[\] | |

**Returns:**

Promise&lt;void&gt;

## 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.
14 changes: 9 additions & 5 deletions docs/api/puppeteer.filechooser.accept.md
View file
Expand Up @@ -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<void>;
accept(paths: string[]): Promise<void>;
}
```

## Parameters

| Parameter | Type | Description |
| --------- | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| filePaths | string\[\] | If some of the <code>filePaths</code> 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&lt;void&gt;

## 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.
10 changes: 5 additions & 5 deletions docs/api/puppeteer.filechooser.md
View file
Expand Up @@ -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. |
15 changes: 8 additions & 7 deletions packages/puppeteer-core/src/api/ElementHandle.ts
View file
Expand Up @@ -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<HTMLInputElement>,
...filePaths: string[]
...paths: string[]
): Promise<void>;
async uploadFile(this: ElementHandle<HTMLInputElement>): Promise<void> {
throw new Error('Not implemented');
Expand Down
12 changes: 7 additions & 5 deletions packages/puppeteer-core/src/common/FileChooser.ts
View file
Expand Up @@ -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<void> {
async accept(paths: string[]): Promise<void> {
assert(
!this.#handled,
'Cannot accept FileChooser which is already handled!'
);
this.#handled = true;
await this.#element.uploadFile(...filePaths);
await this.#element.uploadFile(...paths);
}

/**
Expand Down

0 comments on commit e5d6864

Please sign in to comment.