diff --git a/docs/api/index.md b/docs/api/index.md index af448142..88e7d46f 100644 --- a/docs/api/index.md +++ b/docs/api/index.md @@ -39,7 +39,7 @@ sidebar_label: API | [TimeoutError](./puppeteer.timeouterror.md) | TimeoutError is emitted whenever certain operations are terminated due to timeout. | | [Touchscreen](./puppeteer.touchscreen.md) | The Touchscreen class exposes touchscreen events. | | [Tracing](./puppeteer.tracing.md) | The Tracing class exposes the tracing audit interface. | -| [WebWorker](./puppeteer.webworker.md) | The WebWorker class represents a [WebWorker](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API). | +| [WebWorker](./puppeteer.webworker.md) | This class represents a [WebWorker](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API). | ## Enumerations diff --git a/docs/api/puppeteer.elementhandle._.md b/docs/api/puppeteer.elementhandle._.md index 2d2f3b3a..c3984a95 100644 --- a/docs/api/puppeteer.elementhandle._.md +++ b/docs/api/puppeteer.elementhandle._.md @@ -4,7 +4,7 @@ sidebar_label: ElementHandle.$ # ElementHandle.$() method -Runs `element.querySelector` within the page. +Queries the current element for an element matching the given selector. **Signature:** @@ -18,16 +18,12 @@ class ElementHandle { ## Parameters -| Parameter | Type | Description | -| --------- | -------- | --------------------------- | -| selector | Selector | The selector to query with. | +| Parameter | Type | Description | +| --------- | -------- | -------------------------- | +| selector | Selector | The selector to query for. | **Returns:** Promise<[ElementHandle](./puppeteer.elementhandle.md)<[NodeFor](./puppeteer.nodefor.md)<Selector>> \| null> -`null` if no element matches the selector. - -## Exceptions - -`Error` if the selector has no associated query handler. +A [element handle](./puppeteer.elementhandle.md) to the first element matching the given selector. Otherwise, `null`. diff --git a/docs/api/puppeteer.elementhandle.__.md b/docs/api/puppeteer.elementhandle.__.md index 5d18f3cb..18ff9489 100644 --- a/docs/api/puppeteer.elementhandle.__.md +++ b/docs/api/puppeteer.elementhandle.__.md @@ -4,7 +4,7 @@ sidebar_label: ElementHandle.$$ # ElementHandle.$$() method -Runs `element.querySelectorAll` within the page. +Queries the current element for all elements matching the given selector. **Signature:** @@ -18,16 +18,12 @@ class ElementHandle { ## Parameters -| Parameter | Type | Description | -| --------- | -------- | --------------------------- | -| selector | Selector | The selector to query with. | +| Parameter | Type | Description | +| --------- | -------- | -------------------------- | +| selector | Selector | The selector to query for. | **Returns:** Promise<Array<[ElementHandle](./puppeteer.elementhandle.md)<[NodeFor](./puppeteer.nodefor.md)<Selector>>>> -`[]` if no element matches the selector. - -## Exceptions - -`Error` if the selector has no associated query handler. +An array of [element handles](./puppeteer.elementhandle.md) that point to elements matching the given selector. diff --git a/docs/api/puppeteer.elementhandle.__eval.md b/docs/api/puppeteer.elementhandle.__eval.md index 837be87b..d34a4175 100644 --- a/docs/api/puppeteer.elementhandle.__eval.md +++ b/docs/api/puppeteer.elementhandle.__eval.md @@ -4,9 +4,9 @@ sidebar_label: ElementHandle.$$eval # ElementHandle.$$eval() method -This method runs `document.querySelectorAll` within the element and passes it as the first argument to `pageFunction`. If there's no element matching `selector`, the method throws an error. +Runs the given function on an array of elements matching the given selector in the current element. -If `pageFunction` returns a Promise, then `frame.$$eval` would wait for the promise to resolve and return its value. +If the given function returns a promise, then this method will wait till the promise resolves. **Signature:** @@ -28,17 +28,21 @@ class ElementHandle { ## Parameters -| Parameter | Type | Description | -| ------------ | -------------- | ----------- | -| selector | Selector | | -| pageFunction | Func \| string | | -| args | Params | | +| Parameter | Type | Description | +| ------------ | -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| selector | Selector | The selector to query for. | +| pageFunction | Func \| string | The function to be evaluated in the element's page's context. An array of elements matching the given selector will be passed to the function as its first argument. | +| args | Params | Additional arguments to pass to pageFunction. | **Returns:** Promise<Awaited<ReturnType<Func>>> -## Example 1 +A promise to the result of the function. + +## Example + +HTML: ```html
@@ -47,9 +51,9 @@ Promise<Awaited<ReturnType<Func>>>
``` -## Example 2 +JavaScript: -```ts +```js const feedHandle = await page.$('.feed'); expect( await feedHandle.$$eval('.tweet', nodes => nodes.map(n => n.innerText)) diff --git a/docs/api/puppeteer.elementhandle._eval.md b/docs/api/puppeteer.elementhandle._eval.md index f6731918..11cb427b 100644 --- a/docs/api/puppeteer.elementhandle._eval.md +++ b/docs/api/puppeteer.elementhandle._eval.md @@ -4,9 +4,9 @@ sidebar_label: ElementHandle.$eval # ElementHandle.$eval() method -This method runs `document.querySelector` within the element and passes it as the first argument to `pageFunction`. If there's no element matching `selector`, the method throws an error. +Runs the given function on the first element matching the given selector in the current element. -If `pageFunction` returns a Promise, then `frame.$eval` would wait for the promise to resolve and return its value. +If the given function returns a promise, then this method will wait till the promise resolves. **Signature:** @@ -28,16 +28,18 @@ class ElementHandle { ## Parameters -| Parameter | Type | Description | -| ------------ | -------------- | ----------- | -| selector | Selector | | -| pageFunction | Func \| string | | -| args | Params | | +| Parameter | Type | Description | +| ------------ | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | +| selector | Selector | The selector to query for. | +| pageFunction | Func \| string | The function to be evaluated in this element's page's context. The first element matching the selector will be passed in as the first argument. | +| args | Params | Additional arguments to pass to pageFunction. | **Returns:** Promise<Awaited<ReturnType<Func>>> +A promise to the result of the function. + ## Example ```ts diff --git a/docs/api/puppeteer.elementhandle.md b/docs/api/puppeteer.elementhandle.md index e741b62b..1a0b95bd 100644 --- a/docs/api/puppeteer.elementhandle.md +++ b/docs/api/puppeteer.elementhandle.md @@ -41,32 +41,32 @@ The constructor for this class is marked as internal. Third-party code should no ## Methods -| Method | Modifiers | Description | -| -------------------------------------------------------------------------------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| [$(selector)](./puppeteer.elementhandle._.md) | | Runs element.querySelector within the page. | -| [$$(selector)](./puppeteer.elementhandle.__.md) | | Runs element.querySelectorAll within the page. | -| [$$eval(selector, pageFunction, args)](./puppeteer.elementhandle.__eval.md) | |

This method runs document.querySelectorAll within the element and passes it as the first argument to pageFunction. If there's no element matching selector, the method throws an error.

If pageFunction returns a Promise, then frame.$$eval would wait for the promise to resolve and return its value.

| -| [$eval(selector, pageFunction, args)](./puppeteer.elementhandle._eval.md) | |

This method runs document.querySelector within the element and passes it as the first argument to pageFunction. If there's no element matching selector, the method throws an error.

If pageFunction returns a Promise, then frame.$eval would wait for the promise to resolve and return its value.

| -| [$x(expression)](./puppeteer.elementhandle._x.md) | | | -| [asElement()](./puppeteer.elementhandle.aselement.md) | | | -| [boundingBox()](./puppeteer.elementhandle.boundingbox.md) | | This method returns the bounding box of the element (relative to the main frame), or null if the element is not visible. | -| [boxModel()](./puppeteer.elementhandle.boxmodel.md) | | This method returns boxes of the element, or null if the element is not visible. | -| [click(this, options)](./puppeteer.elementhandle.click.md) | | This method scrolls element into view if needed, and then uses [Page.mouse](./puppeteer.page.mouse.md) to click in the center of the element. If the element is detached from DOM, the method throws an error. | -| [clickablePoint(offset)](./puppeteer.elementhandle.clickablepoint.md) | | Returns the middle point within an element unless a specific offset is provided. | -| [contentFrame()](./puppeteer.elementhandle.contentframe.md) | | Resolves to the content frame for element handles referencing iframe nodes, or null otherwise | -| [drag(this, target)](./puppeteer.elementhandle.drag.md) | | This method creates and captures a dragevent from the element. | -| [dragAndDrop(this, target, options)](./puppeteer.elementhandle.draganddrop.md) | | This method triggers a dragenter, dragover, and drop on the element. | -| [dragEnter(this, data)](./puppeteer.elementhandle.dragenter.md) | | This method creates a dragenter event on the element. | -| [dragOver(this, data)](./puppeteer.elementhandle.dragover.md) | | This method creates a dragover event on the element. | -| [drop(this, data)](./puppeteer.elementhandle.drop.md) | | This method triggers a drop on the element. | -| [focus()](./puppeteer.elementhandle.focus.md) | | Calls [focus](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/focus) on the element. | -| [hover(this)](./puppeteer.elementhandle.hover.md) | | This method scrolls element into view if needed, and then uses [Page.mouse](./puppeteer.page.mouse.md) to hover over the center of the element. If the element is detached from DOM, the method throws an error. | -| [isIntersectingViewport(this, options)](./puppeteer.elementhandle.isintersectingviewport.md) | | Resolves to true if the element is visible in the current viewport. | -| [press(key, options)](./puppeteer.elementhandle.press.md) | | Focuses the element, and then uses [Keyboard.down()](./puppeteer.keyboard.down.md) and [Keyboard.up()](./puppeteer.keyboard.up.md). | -| [screenshot(this, options)](./puppeteer.elementhandle.screenshot.md) | | This method scrolls element into view if needed, and then uses [Page.screenshot()](./puppeteer.page.screenshot.md) to take a screenshot of the element. If the element is detached from DOM, the method throws an error. | -| [select(values)](./puppeteer.elementhandle.select.md) | | Triggers a change and input event once all the provided options have been selected. If there's no <select> element matching selector, the method throws an error. | -| [tap(this)](./puppeteer.elementhandle.tap.md) | | This method scrolls element into view if needed, and then uses [Touchscreen.tap()](./puppeteer.touchscreen.tap.md) to tap in the center of the element. If the element is detached from DOM, the method throws an error. | -| [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). | -| [waitForSelector(selector, options)](./puppeteer.elementhandle.waitforselector.md) | |

Wait for the selector to appear within the element. If at the moment of calling the method the selector already exists, the method will return immediately. If the selector doesn't appear after the timeout milliseconds of waiting, the function will throw.

This method does not work across navigations or if the element is detached from DOM.

| -| [waitForXPath(xpath, options)](./puppeteer.elementhandle.waitforxpath.md) | | | +| Method | Modifiers | Description | +| -------------------------------------------------------------------------------------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [$(selector)](./puppeteer.elementhandle._.md) | | Queries the current element for an element matching the given selector. | +| [$$(selector)](./puppeteer.elementhandle.__.md) | | Queries the current element for all elements matching the given selector. | +| [$$eval(selector, pageFunction, args)](./puppeteer.elementhandle.__eval.md) | |

Runs the given function on an array of elements matching the given selector in the current element.

If the given function returns a promise, then this method will wait till the promise resolves.

| +| [$eval(selector, pageFunction, args)](./puppeteer.elementhandle._eval.md) | |

Runs the given function on the first element matching the given selector in the current element.

If the given function returns a promise, then this method will wait till the promise resolves.

| +| [$x(expression)](./puppeteer.elementhandle._x.md) | | | +| [asElement()](./puppeteer.elementhandle.aselement.md) | | | +| [boundingBox()](./puppeteer.elementhandle.boundingbox.md) | | This method returns the bounding box of the element (relative to the main frame), or null if the element is not visible. | +| [boxModel()](./puppeteer.elementhandle.boxmodel.md) | | This method returns boxes of the element, or null if the element is not visible. | +| [click(this, options)](./puppeteer.elementhandle.click.md) | | This method scrolls element into view if needed, and then uses [Page.mouse](./puppeteer.page.mouse.md) to click in the center of the element. If the element is detached from DOM, the method throws an error. | +| [clickablePoint(offset)](./puppeteer.elementhandle.clickablepoint.md) | | Returns the middle point within an element unless a specific offset is provided. | +| [contentFrame()](./puppeteer.elementhandle.contentframe.md) | | Resolves to the content frame for element handles referencing iframe nodes, or null otherwise | +| [drag(this, target)](./puppeteer.elementhandle.drag.md) | | This method creates and captures a dragevent from the element. | +| [dragAndDrop(this, target, options)](./puppeteer.elementhandle.draganddrop.md) | | This method triggers a dragenter, dragover, and drop on the element. | +| [dragEnter(this, data)](./puppeteer.elementhandle.dragenter.md) | | This method creates a dragenter event on the element. | +| [dragOver(this, data)](./puppeteer.elementhandle.dragover.md) | | This method creates a dragover event on the element. | +| [drop(this, data)](./puppeteer.elementhandle.drop.md) | | This method triggers a drop on the element. | +| [focus()](./puppeteer.elementhandle.focus.md) | | Calls [focus](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/focus) on the element. | +| [hover(this)](./puppeteer.elementhandle.hover.md) | | This method scrolls element into view if needed, and then uses [Page.mouse](./puppeteer.page.mouse.md) to hover over the center of the element. If the element is detached from DOM, the method throws an error. | +| [isIntersectingViewport(this, options)](./puppeteer.elementhandle.isintersectingviewport.md) | | Resolves to true if the element is visible in the current viewport. | +| [press(key, options)](./puppeteer.elementhandle.press.md) | | Focuses the element, and then uses [Keyboard.down()](./puppeteer.keyboard.down.md) and [Keyboard.up()](./puppeteer.keyboard.up.md). | +| [screenshot(this, options)](./puppeteer.elementhandle.screenshot.md) | | This method scrolls element into view if needed, and then uses [Page.screenshot()](./puppeteer.page.screenshot.md) to take a screenshot of the element. If the element is detached from DOM, the method throws an error. | +| [select(values)](./puppeteer.elementhandle.select.md) | | Triggers a change and input event once all the provided options have been selected. If there's no <select> element matching selector, the method throws an error. | +| [tap(this)](./puppeteer.elementhandle.tap.md) | | This method scrolls element into view if needed, and then uses [Touchscreen.tap()](./puppeteer.touchscreen.tap.md) to tap in the center of the element. If the element is detached from DOM, the method throws an error. | +| [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). | +| [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.waitforselector.md b/docs/api/puppeteer.elementhandle.waitforselector.md index 22617c4b..5f905d17 100644 --- a/docs/api/puppeteer.elementhandle.waitforselector.md +++ b/docs/api/puppeteer.elementhandle.waitforselector.md @@ -4,9 +4,9 @@ sidebar_label: ElementHandle.waitForSelector # ElementHandle.waitForSelector() method -Wait for the `selector` to appear within the element. If at the moment of calling the method the `selector` already exists, the method will return immediately. If the `selector` doesn't appear after the `timeout` milliseconds of waiting, the function will throw. +Wait for an element matching the given selector to appear in the current element. -This method does not work across navigations or if the element is detached from DOM. +Unlike [Frame.waitForSelector()](./puppeteer.frame.waitforselector.md), this method does not work across navigations or if the element is detached from DOM. **Signature:** @@ -21,23 +21,42 @@ class ElementHandle { ## Parameters -| Parameter | Type | Description | -| --------- | -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ | -| selector | Selector | A [selector](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors) of an element to wait for | -| options | Exclude<[WaitForSelectorOptions](./puppeteer.waitforselectoroptions.md), 'root'> | (Optional) Optional waiting parameters | +| Parameter | Type | Description | +| --------- | -------------------------------------------------------------------------------------- | ----------------------------------------------------------- | +| selector | Selector | The selector to query and wait for. | +| options | Exclude<[WaitForSelectorOptions](./puppeteer.waitforselectoroptions.md), 'root'> | (Optional) Options for customizing waiting behavior. | **Returns:** Promise<[ElementHandle](./puppeteer.elementhandle.md)<[NodeFor](./puppeteer.nodefor.md)<Selector>> \| null> -Promise which resolves when element specified by selector string is added to DOM. Resolves to `null` if waiting for hidden: `true` and selector is not found in DOM. +An element matching the given selector. -## Remarks +## Exceptions -The optional parameters in `options` are: +Throws if an element matching the given selector doesn't appear. -- `visible`: wait for the selected element to be present in DOM and to be visible, i.e. to not have `display: none` or `visibility: hidden` CSS properties. Defaults to `false`. +## Example -- `hidden`: wait for the selected element to not be found in the DOM or to be hidden, i.e. have `display: none` or `visibility: hidden` CSS properties. Defaults to `false`. +```ts +const puppeteer = require('puppeteer'); -- `timeout`: maximum time to wait in milliseconds. Defaults to `30000` (30 seconds). Pass `0` to disable timeout. The default value can be changed by using the [Page.setDefaultTimeout()](./puppeteer.page.setdefaulttimeout.md) method. +(async () => { + const browser = await puppeteer.launch(); + const page = await browser.newPage(); + let currentURL; + page + .mainFrame() + .waitForSelector('img') + .then(() => console.log('First URL with image: ' + currentURL)); + + for (currentURL of [ + 'https://example.com', + 'https://google.com', + 'https://bbc.com', + ]) { + await page.goto(currentURL); + } + await browser.close(); +})(); +``` diff --git a/docs/api/puppeteer.filechooser.md b/docs/api/puppeteer.filechooser.md index 8eaae182..589056b1 100644 --- a/docs/api/puppeteer.filechooser.md +++ b/docs/api/puppeteer.filechooser.md @@ -14,14 +14,14 @@ export declare class FileChooser ## Remarks -`FileChooser` objects are returned via the `page.waitForFileChooser` method. +`FileChooser` instances are returned via the [Page.waitForFileChooser()](./puppeteer.page.waitforfilechooser.md) method. + +In browsers, only one file chooser can be opened at a time. All file choosers must be accepted or canceled. Not doing so will prevent subsequent file choosers from appearing. The constructor for this class is marked as internal. Third-party code should not call the constructor directly or create subclasses that extend the `FileChooser` class. ## Example -An example of using `FileChooser`: - ```ts const [fileChooser] = await Promise.all([ page.waitForFileChooser(), @@ -30,8 +30,6 @@ const [fileChooser] = await Promise.all([ await fileChooser.accept(['/tmp/myfile.pdf']); ``` -\*\*NOTE\*\* In browsers, only one file chooser can be opened at a time. All file choosers must be accepted or canceled. Not doing so will prevent subsequent file choosers from appearing. - ## Methods | Method | Modifiers | Description | diff --git a/docs/api/puppeteer.frame._.md b/docs/api/puppeteer.frame._.md index 1e29bcb8..d9f5cb88 100644 --- a/docs/api/puppeteer.frame._.md +++ b/docs/api/puppeteer.frame._.md @@ -4,7 +4,7 @@ sidebar_label: Frame.$ # Frame.$() method -This method queries the frame for the given selector. +Queries the frame for an element matching the given selector. **Signature:** @@ -18,12 +18,12 @@ class Frame { ## Parameters -| Parameter | Type | Description | -| --------- | -------- | ------------------------ | -| selector | Selector | a selector to query for. | +| Parameter | Type | Description | +| --------- | -------- | -------------------------- | +| selector | Selector | The selector to query for. | **Returns:** Promise<[ElementHandle](./puppeteer.elementhandle.md)<[NodeFor](./puppeteer.nodefor.md)<Selector>> \| null> -A promise which resolves to an `ElementHandle` pointing at the element, or `null` if it was not found. +A [element handle](./puppeteer.elementhandle.md) to the first element matching the given selector. Otherwise, `null`. diff --git a/docs/api/puppeteer.frame.__.md b/docs/api/puppeteer.frame.__.md index 7b296cbd..66cc1899 100644 --- a/docs/api/puppeteer.frame.__.md +++ b/docs/api/puppeteer.frame.__.md @@ -4,7 +4,7 @@ sidebar_label: Frame.$$ # Frame.$$() method -This runs `document.querySelectorAll` in the frame and returns the result. +Queries the frame for all elements matching the given selector. **Signature:** @@ -18,12 +18,12 @@ class Frame { ## Parameters -| Parameter | Type | Description | -| --------- | -------- | ------------------------ | -| selector | Selector | a selector to search for | +| Parameter | Type | Description | +| --------- | -------- | -------------------------- | +| selector | Selector | The selector to query for. | **Returns:** Promise<Array<[ElementHandle](./puppeteer.elementhandle.md)<[NodeFor](./puppeteer.nodefor.md)<Selector>>>> -An array of element handles pointing to the found frame elements. +An array of [element handles](./puppeteer.elementhandle.md) that point to elements matching the given selector. diff --git a/docs/api/puppeteer.frame.__eval.md b/docs/api/puppeteer.frame.__eval.md index 6db54e4e..2007e355 100644 --- a/docs/api/puppeteer.frame.__eval.md +++ b/docs/api/puppeteer.frame.__eval.md @@ -4,6 +4,10 @@ sidebar_label: Frame.$$eval # Frame.$$eval() method +Runs the given function on an array of elements matching the given selector in the frame. + +If the given function returns a promise, then this method will wait till the promise resolves. + **Signature:** ```typescript @@ -24,24 +28,20 @@ class Frame { ## Parameters -| Parameter | Type | Description | -| ------------ | -------------- | --------------------------------------------------------- | -| selector | Selector | the selector to query for | -| pageFunction | Func \| string | the function to be evaluated in the frame's context | -| args | Params | additional arguments to pass to pageFunction | +| Parameter | Type | Description | +| ------------ | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | +| selector | Selector | The selector to query for. | +| pageFunction | Func \| string | The function to be evaluated in the frame's context. An array of elements matching the given selector will be passed to the function as its first argument. | +| args | Params | Additional arguments to pass to pageFunction. | **Returns:** Promise<Awaited<ReturnType<Func>>> -## Remarks - -This method runs `Array.from(document.querySelectorAll(selector))` within the frame and passes it as the first argument to `pageFunction`. - -If `pageFunction` returns a Promise, then `frame.$$eval` would wait for the promise to resolve and return its value. +A promise to the result of the function. ## Example -```ts +```js const divsCounts = await frame.$$eval('div', divs => divs.length); ``` diff --git a/docs/api/puppeteer.frame._eval.md b/docs/api/puppeteer.frame._eval.md index 28ead092..0c6589a1 100644 --- a/docs/api/puppeteer.frame._eval.md +++ b/docs/api/puppeteer.frame._eval.md @@ -4,6 +4,10 @@ sidebar_label: Frame.$eval # Frame.$eval() method +Runs the given function on the first element matching the given selector in the frame. + +If the given function returns a promise, then this method will wait till the promise resolves. + **Signature:** ```typescript @@ -24,21 +28,17 @@ class Frame { ## Parameters -| Parameter | Type | Description | -| ------------ | -------------- | --------------------------------------------------------- | -| selector | Selector | the selector to query for | -| pageFunction | Func \| string | the function to be evaluated in the frame's context | -| args | Params | additional arguments to pass to pageFunction | +| Parameter | Type | Description | +| ------------ | -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | +| selector | Selector | The selector to query for. | +| pageFunction | Func \| string | The function to be evaluated in the frame's context. The first element matching the selector will be passed to the function as its first argument. | +| args | Params | Additional arguments to pass to pageFunction. | **Returns:** Promise<Awaited<ReturnType<Func>>> -## Remarks - -This method runs `document.querySelector` within the frame and passes it as the first argument to `pageFunction`. - -If `pageFunction` returns a Promise, then `frame.$eval` would wait for the promise to resolve and return its value. +A promise to the result of the function. ## Example diff --git a/docs/api/puppeteer.frame._x.md b/docs/api/puppeteer.frame._x.md index e2290048..dd7a17b4 100644 --- a/docs/api/puppeteer.frame._x.md +++ b/docs/api/puppeteer.frame._x.md @@ -4,7 +4,11 @@ sidebar_label: Frame.$x # Frame.$x() method -This method evaluates the given XPath expression and returns the results. +> Warning: This API is now obsolete. +> +> Use [Frame.$$()](./puppeteer.frame.__.md) with the `xpath` prefix. +> +> This method evaluates the given XPath expression and returns the results. **Signature:** diff --git a/docs/api/puppeteer.frame.addscripttag.md b/docs/api/puppeteer.frame.addscripttag.md index 3baf564e..67e26385 100644 --- a/docs/api/puppeteer.frame.addscripttag.md +++ b/docs/api/puppeteer.frame.addscripttag.md @@ -18,9 +18,9 @@ class Frame { ## Parameters -| Parameter | Type | Description | -| --------- | ------------------------------------------------------------------- | ---------------------------------------- | -| options | [FrameAddScriptTagOptions](./puppeteer.frameaddscripttagoptions.md) | configure the script to add to the page. | +| Parameter | Type | Description | +| --------- | ------------------------------------------------------------------- | ----------------------- | +| options | [FrameAddScriptTagOptions](./puppeteer.frameaddscripttagoptions.md) | Options for the script. | **Returns:** diff --git a/docs/api/puppeteer.frame.addstyletag.md b/docs/api/puppeteer.frame.addstyletag.md index e5a13076..5b00d734 100644 --- a/docs/api/puppeteer.frame.addstyletag.md +++ b/docs/api/puppeteer.frame.addstyletag.md @@ -10,18 +10,20 @@ Adds a `` tag into the page with the desired url or a `>; + addStyleTag( + options: FrameAddStyleTagOptions + ): Promise>; } ``` ## Parameters -| Parameter | Type | Description | -| --------- | ----------------------------------------------------------------- | ------------------------------------- | -| options | [FrameAddStyleTagOptions](./puppeteer.frameaddstyletagoptions.md) | configure the CSS to add to the page. | +| Parameter | Type | Description | +| --------- | ----------------------------------------------------------------- | --------------------------- | +| options | [FrameAddStyleTagOptions](./puppeteer.frameaddstyletagoptions.md) | Options for the style link. | **Returns:** -Promise<[ElementHandle](./puppeteer.elementhandle.md)<Node>> +Promise<[ElementHandle](./puppeteer.elementhandle.md)<HTMLStyleElement \| HTMLLinkElement>> a promise that resolves to the added tag when the stylesheets's `onload` event fires or when the CSS content was injected into the frame. diff --git a/docs/api/puppeteer.frame.click.md b/docs/api/puppeteer.frame.click.md index fe3a8f06..b250ef5c 100644 --- a/docs/api/puppeteer.frame.click.md +++ b/docs/api/puppeteer.frame.click.md @@ -4,7 +4,7 @@ sidebar_label: Frame.click # Frame.click() method -This method clicks the first element found that matches `selector`. +Clicks the first element found that matches `selector`. **Signature:** @@ -23,10 +23,10 @@ class Frame { ## Parameters -| Parameter | Type | Description | -| --------- | -------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | -| selector | string | the selector to search for to click. If there are multiple elements, the first will be clicked. | -| options | { delay?: number; button?: [MouseButton](./puppeteer.mousebutton.md); clickCount?: number; } | (Optional) | +| Parameter | Type | Description | +| --------- | -------------------------------------------------------------------------------------------- | -------------------------- | +| selector | string | The selector to query for. | +| options | { delay?: number; button?: [MouseButton](./puppeteer.mousebutton.md); clickCount?: number; } | (Optional) | **Returns:** @@ -34,11 +34,9 @@ Promise<void> ## Remarks -This method scrolls the element into view if needed, and then uses [Page.mouse](./puppeteer.page.mouse.md) to click in the center of the element. If there's no element matching `selector`, the method throws an error. +If `click()` triggers a navigation event and there's a separate `page.waitForNavigation()` promise to be resolved, you may end up with a race condition that yields unexpected results. The correct pattern for click and wait for navigation is the following: -Bear in mind that if `click()` triggers a navigation event and there's a separate `page.waitForNavigation()` promise to be resolved, you may end up with a race condition that yields unexpected results. The correct pattern for click and wait for navigation is the following: - -```javascript +```ts const [response] = await Promise.all([ page.waitForNavigation(waitOptions), frame.click(selector, clickOptions), diff --git a/docs/api/puppeteer.frame.content.md b/docs/api/puppeteer.frame.content.md index 7d443728..61640b6d 100644 --- a/docs/api/puppeteer.frame.content.md +++ b/docs/api/puppeteer.frame.content.md @@ -16,4 +16,4 @@ class Frame { Promise<string> -the full HTML contents of the frame, including the doctype. +The full HTML contents of the frame, including the DOCTYPE. diff --git a/docs/api/puppeteer.frame.evaluate.md b/docs/api/puppeteer.frame.evaluate.md index 5e72e6e7..400f752f 100644 --- a/docs/api/puppeteer.frame.evaluate.md +++ b/docs/api/puppeteer.frame.evaluate.md @@ -4,6 +4,8 @@ sidebar_label: Frame.evaluate # Frame.evaluate() method +Behaves identically to [Page.evaluate()](./puppeteer.page.evaluate.md) except it's run within the the context of this frame. + **Signature:** ```typescript @@ -28,7 +30,3 @@ class Frame { **Returns:** Promise<Awaited<ReturnType<Func>>> - -## Remarks - -This method behaves identically to [Page.evaluate()](./puppeteer.page.evaluate.md) except it's run within the context of the `frame`, rather than the entire page. diff --git a/docs/api/puppeteer.frame.evaluatehandle.md b/docs/api/puppeteer.frame.evaluatehandle.md index 2b4df04f..b9ea0d82 100644 --- a/docs/api/puppeteer.frame.evaluatehandle.md +++ b/docs/api/puppeteer.frame.evaluatehandle.md @@ -4,6 +4,8 @@ sidebar_label: Frame.evaluateHandle # Frame.evaluateHandle() method +Behaves identically to [Page.evaluateHandle()](./puppeteer.page.evaluatehandle.md) except it's run within the context of this frame. + **Signature:** ```typescript @@ -28,9 +30,3 @@ class Frame { **Returns:** Promise<[HandleFor](./puppeteer.handlefor.md)<Awaited<ReturnType<Func>>>> - -## Remarks - -The only difference between [Frame.evaluate()](./puppeteer.frame.evaluate.md) and `frame.evaluateHandle` is that `evaluateHandle` will return the value wrapped in an in-page object. - -This method behaves identically to [Page.evaluateHandle()](./puppeteer.page.evaluatehandle.md) except it's run within the context of the `frame`, rather than the entire page. diff --git a/docs/api/puppeteer.frame.focus.md b/docs/api/puppeteer.frame.focus.md index 9872157d..952fee0e 100644 --- a/docs/api/puppeteer.frame.focus.md +++ b/docs/api/puppeteer.frame.focus.md @@ -4,7 +4,7 @@ sidebar_label: Frame.focus # Frame.focus() method -This method fetches an element with `selector` and focuses it. +Focuses the first element that matches the `selector`. **Signature:** @@ -16,14 +16,14 @@ class Frame { ## Parameters -| Parameter | Type | Description | -| --------- | ------ | ------------------------------------------------------------------------------------------------- | -| selector | string | the selector for the element to focus. If there are multiple elements, the first will be focused. | +| Parameter | Type | Description | +| --------- | ------ | -------------------------- | +| selector | string | The selector to query for. | **Returns:** Promise<void> -## Remarks +## Exceptions -If there's no element matching `selector`, the method throws an error. +Throws if there's no element matching `selector`. diff --git a/docs/api/puppeteer.frame.goto.md b/docs/api/puppeteer.frame.goto.md index 205d3538..02c4930f 100644 --- a/docs/api/puppeteer.frame.goto.md +++ b/docs/api/puppeteer.frame.goto.md @@ -4,6 +4,8 @@ sidebar_label: Frame.goto # Frame.goto() method +Navigates a frame to the given url. + **Signature:** ```typescript @@ -32,20 +34,20 @@ Promise<[HTTPResponse](./puppeteer.httpresponse.md) \| null> A promise which resolves to the main resource response. In case of multiple redirects, the navigation will resolve with the response of the last redirect. +## Exceptions + +This method will throw an error if: + +- there's an SSL error (e.g. in case of self-signed certificates). - target URL is invalid. - the `timeout` is exceeded during navigation. - the remote server does not respond or is unreachable. - the main resource failed to load. + +This method will not throw an error when any valid HTTP status code is returned by the remote server, including 404 "Not Found" and 500 "Internal Server Error". The status code for such responses can be retrieved by calling [HTTPResponse.status()](./puppeteer.httpresponse.status.md). + ## Remarks -`frame.goto` will throw an error if: - there's an SSL error (e.g. in case of self-signed certificates). +Navigation to `about:blank` or navigation to the same URL with a different hash will succeed and return `null`. -- target URL is invalid. +:::warning -- the `timeout` is exceeded during navigation. +Headless mode doesn't support navigation to a PDF document. See the [upstream issue](https://bugs.chromium.org/p/chromium/issues/detail?id=761295). -- the remote server does not respond or is unreachable. - -- the main resource failed to load. - -`frame.goto` will not throw an error when any valid HTTP status code is returned by the remote server, including 404 "Not Found" and 500 "Internal Server Error". The status code for such responses can be retrieved by calling [HTTPResponse.status()](./puppeteer.httpresponse.status.md). - -NOTE: `frame.goto` either throws an error or returns a main resource response. The only exceptions are navigation to `about:blank` or navigation to the same URL with a different hash, which would succeed and return `null`. - -NOTE: Headless mode doesn't support navigation to a PDF document. See the [upstream issue](https://bugs.chromium.org/p/chromium/issues/detail?id=761295). +::: diff --git a/docs/api/puppeteer.frame.hover.md b/docs/api/puppeteer.frame.hover.md index 6555d289..b4f1fd7c 100644 --- a/docs/api/puppeteer.frame.hover.md +++ b/docs/api/puppeteer.frame.hover.md @@ -4,7 +4,7 @@ sidebar_label: Frame.hover # Frame.hover() method -This method fetches an element with `selector`, scrolls it into view if needed, and then uses [Page.mouse](./puppeteer.page.mouse.md) to hover over the center of the element. +Hovers the pointer over the center of the first element that matches the `selector`. **Signature:** @@ -16,14 +16,14 @@ class Frame { ## Parameters -| Parameter | Type | Description | -| --------- | ------ | ------------------------------------------------------------------------------------------------- | -| selector | string | the selector for the element to hover. If there are multiple elements, the first will be hovered. | +| Parameter | Type | Description | +| --------- | ------ | -------------------------- | +| selector | string | The selector to query for. | **Returns:** Promise<void> -## Remarks +## Exceptions -If there's no element matching `selector`, the method throws an +Throws if there's no element matching `selector`. diff --git a/docs/api/puppeteer.frame.isoopframe.md b/docs/api/puppeteer.frame.isoopframe.md index 83d2a759..323e2c10 100644 --- a/docs/api/puppeteer.frame.isoopframe.md +++ b/docs/api/puppeteer.frame.isoopframe.md @@ -17,5 +17,3 @@ class Frame { boolean `true` if the frame is an OOP frame, or `false` otherwise. - -## Remarks diff --git a/docs/api/puppeteer.frame.md b/docs/api/puppeteer.frame.md index a69bb57d..c8732d22 100644 --- a/docs/api/puppeteer.frame.md +++ b/docs/api/puppeteer.frame.md @@ -16,11 +16,7 @@ export declare class Frame `Frame` object lifecycles are controlled by three events that are all dispatched on the page object: -- [PageEmittedEvents.FrameAttached](./puppeteer.pageemittedevents.md) - -- [PageEmittedEvents.FrameNavigated](./puppeteer.pageemittedevents.md) - -- [PageEmittedEvents.FrameDetached](./puppeteer.pageemittedevents.md) +- [PageEmittedEvents.FrameAttached](./puppeteer.pageemittedevents.md) - [PageEmittedEvents.FrameNavigated](./puppeteer.pageemittedevents.md) - [PageEmittedEvents.FrameDetached](./puppeteer.pageemittedevents.md) The constructor for this class is marked as internal. Third-party code should not call the constructor directly or create subclasses that extend the `Frame` class. @@ -59,37 +55,37 @@ console.log(text); ## Methods -| Method | Modifiers | Description | -| ------------------------------------------------------------------------------------ | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| [$(selector)](./puppeteer.frame._.md) | | This method queries the frame for the given selector. | -| [$$(selector)](./puppeteer.frame.__.md) | | This runs document.querySelectorAll in the frame and returns the result. | -| [$$eval(selector, pageFunction, args)](./puppeteer.frame.__eval.md) | | | -| [$eval(selector, pageFunction, args)](./puppeteer.frame._eval.md) | | | -| [$x(expression)](./puppeteer.frame._x.md) | | This method evaluates the given XPath expression and returns the results. | -| [addScriptTag(options)](./puppeteer.frame.addscripttag.md) | | Adds a <script> tag into the page with the desired url or content. | -| [addStyleTag(options)](./puppeteer.frame.addstyletag.md) | | Adds a <link rel="stylesheet"> tag into the page with the desired url or a <style type="text/css"> tag with the content. | -| [childFrames()](./puppeteer.frame.childframes.md) | | | -| [click(selector, options)](./puppeteer.frame.click.md) | | This method clicks the first element found that matches selector. | -| [content()](./puppeteer.frame.content.md) | | | -| [evaluate(pageFunction, args)](./puppeteer.frame.evaluate.md) | | | -| [evaluateHandle(pageFunction, args)](./puppeteer.frame.evaluatehandle.md) | | | -| [executionContext()](./puppeteer.frame.executioncontext.md) | | | -| [focus(selector)](./puppeteer.frame.focus.md) | | This method fetches an element with selector and focuses it. | -| [goto(url, options)](./puppeteer.frame.goto.md) | | | -| [hover(selector)](./puppeteer.frame.hover.md) | | This method fetches an element with selector, scrolls it into view if needed, and then uses [Page.mouse](./puppeteer.page.mouse.md) to hover over the center of the element. | -| [isDetached()](./puppeteer.frame.isdetached.md) | | | -| [isOOPFrame()](./puppeteer.frame.isoopframe.md) | | | -| [name()](./puppeteer.frame.name.md) | | | -| [page()](./puppeteer.frame.page.md) | | | -| [parentFrame()](./puppeteer.frame.parentframe.md) | | | -| [select(selector, values)](./puppeteer.frame.select.md) | | Triggers a change and input event once all the provided options have been selected. | -| [setContent(html, options)](./puppeteer.frame.setcontent.md) | | Set the content of the frame. | -| [tap(selector)](./puppeteer.frame.tap.md) | | This method fetches an element with selector, scrolls it into view if needed, and then uses [Page.touchscreen](./puppeteer.page.touchscreen.md) to tap in the center of the element. | -| [title()](./puppeteer.frame.title.md) | | | -| [type(selector, text, options)](./puppeteer.frame.type.md) | | Sends a keydown, keypress/input, and keyup event for each character in the text. | -| [url()](./puppeteer.frame.url.md) | | | -| [waitForFunction(pageFunction, options, args)](./puppeteer.frame.waitforfunction.md) | | | -| [waitForNavigation(options)](./puppeteer.frame.waitfornavigation.md) | | | -| [waitForSelector(selector, options)](./puppeteer.frame.waitforselector.md) | | | -| [waitForTimeout(milliseconds)](./puppeteer.frame.waitfortimeout.md) | | Causes your script to wait for the given number of milliseconds. | -| [waitForXPath(xpath, options)](./puppeteer.frame.waitforxpath.md) | | | +| Method | Modifiers | Description | +| ------------------------------------------------------------------------------------ | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [$(selector)](./puppeteer.frame._.md) | | Queries the frame for an element matching the given selector. | +| [$$(selector)](./puppeteer.frame.__.md) | | Queries the frame for all elements matching the given selector. | +| [$$eval(selector, pageFunction, args)](./puppeteer.frame.__eval.md) | |

Runs the given function on an array of elements matching the given selector in the frame.

If the given function returns a promise, then this method will wait till the promise resolves.

| +| [$eval(selector, pageFunction, args)](./puppeteer.frame._eval.md) | |

Runs the given function on the first element matching the given selector in the frame.

If the given function returns a promise, then this method will wait till the promise resolves.

| +| [$x(expression)](./puppeteer.frame._x.md) | | | +| [addScriptTag(options)](./puppeteer.frame.addscripttag.md) | | Adds a <script> tag into the page with the desired url or content. | +| [addStyleTag(options)](./puppeteer.frame.addstyletag.md) | | Adds a <link rel="stylesheet"> tag into the page with the desired url or a <style type="text/css"> tag with the content. | +| [childFrames()](./puppeteer.frame.childframes.md) | | | +| [click(selector, options)](./puppeteer.frame.click.md) | | Clicks the first element found that matches selector. | +| [content()](./puppeteer.frame.content.md) | | | +| [evaluate(pageFunction, args)](./puppeteer.frame.evaluate.md) | | Behaves identically to [Page.evaluate()](./puppeteer.page.evaluate.md) except it's run within the the context of this frame. | +| [evaluateHandle(pageFunction, args)](./puppeteer.frame.evaluatehandle.md) | | Behaves identically to [Page.evaluateHandle()](./puppeteer.page.evaluatehandle.md) except it's run within the context of this frame. | +| [executionContext()](./puppeteer.frame.executioncontext.md) | | | +| [focus(selector)](./puppeteer.frame.focus.md) | | Focuses the first element that matches the selector. | +| [goto(url, options)](./puppeteer.frame.goto.md) | | Navigates a frame to the given url. | +| [hover(selector)](./puppeteer.frame.hover.md) | | Hovers the pointer over the center of the first element that matches the selector. | +| [isDetached()](./puppeteer.frame.isdetached.md) | | | +| [isOOPFrame()](./puppeteer.frame.isoopframe.md) | | | +| [name()](./puppeteer.frame.name.md) | | | +| [page()](./puppeteer.frame.page.md) | | | +| [parentFrame()](./puppeteer.frame.parentframe.md) | | | +| [select(selector, values)](./puppeteer.frame.select.md) | | Selects a set of value on the first <select> element that matches the selector. | +| [setContent(html, options)](./puppeteer.frame.setcontent.md) | | Set the content of the frame. | +| [tap(selector)](./puppeteer.frame.tap.md) | | Taps the first element that matches the selector. | +| [title()](./puppeteer.frame.title.md) | | | +| [type(selector, text, options)](./puppeteer.frame.type.md) | | Sends a keydown, keypress/input, and keyup event for each character in the text. | +| [url()](./puppeteer.frame.url.md) | | | +| [waitForFunction(pageFunction, options, args)](./puppeteer.frame.waitforfunction.md) | | | +| [waitForNavigation(options)](./puppeteer.frame.waitfornavigation.md) | |

Waits for the frame to navigate. It is useful for when you run code which will indirectly cause the frame to navigate.

Usage of the [History API](https://developer.mozilla.org/en-US/docs/Web/API/History_API) to change the URL is considered a navigation.

| +| [waitForSelector(selector, options)](./puppeteer.frame.waitforselector.md) | |

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

This method works across navigations.

| +| [waitForTimeout(milliseconds)](./puppeteer.frame.waitfortimeout.md) | | Causes your script to wait for the given number of milliseconds. | +| [waitForXPath(xpath, options)](./puppeteer.frame.waitforxpath.md) | | | diff --git a/docs/api/puppeteer.frame.name.md b/docs/api/puppeteer.frame.name.md index cb6e657d..b21daba9 100644 --- a/docs/api/puppeteer.frame.name.md +++ b/docs/api/puppeteer.frame.name.md @@ -16,10 +16,8 @@ class Frame { string -the frame's `name` attribute as specified in the tag. +The frame's `name` attribute as specified in the tag. ## Remarks -If the name is empty, it returns the `id` attribute instead. - -Note: This value is calculated once when the frame is created, and will not update if the attribute is changed later. +This value is calculated once when the frame is created, and will not update if the attribute is changed later. diff --git a/docs/api/puppeteer.frame.page.md b/docs/api/puppeteer.frame.page.md index 201dd209..476b98c3 100644 --- a/docs/api/puppeteer.frame.page.md +++ b/docs/api/puppeteer.frame.page.md @@ -16,4 +16,4 @@ class Frame { [Page](./puppeteer.page.md) -a page associated with the frame. +The page associated with the frame. diff --git a/docs/api/puppeteer.frame.select.md b/docs/api/puppeteer.frame.select.md index 15216f07..804ddb79 100644 --- a/docs/api/puppeteer.frame.select.md +++ b/docs/api/puppeteer.frame.select.md @@ -4,7 +4,7 @@ sidebar_label: Frame.select # Frame.select() method -Triggers a `change` and `input` event once all the provided options have been selected. +Selects a set of value on the first `` element matching `selector`, the method throws an error. +Throws if there's no `