From 3fefa7b7ffe21e157d5ff384127b15a8d0c9f198 Mon Sep 17 00:00:00 2001 From: Dmitry Gozman Date: Wed, 29 Apr 2020 15:24:59 -0700 Subject: [PATCH] docs: fix docs for $foo methods that assumed css selectors (#2039) --- docs/api.md | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/docs/api.md b/docs/api.md index c7d0a81cc4..3e4bd97264 100644 --- a/docs/api.md +++ b/docs/api.md @@ -845,7 +845,7 @@ Emitted when a dedicated [WebWorker](https://developer.mozilla.org/en-US/docs/We - `selector` <[string]> A selector to query page for - returns: <[Promise]> -The method runs `document.querySelector` within the page. If no element matches the selector, the return value resolves to `null`. +The method finds an element matching the specified selector within the page. See [Working with selectors](#working-with-selectors) for more details. If no elements match the selector, the return value resolves to `null`. Shortcut for [page.mainFrame().$(selector)](#frameselector). @@ -853,7 +853,7 @@ Shortcut for [page.mainFrame().$(selector)](#frameselector). - `selector` <[string]> A selector to query page for - returns: <[Promise]<[Array]<[ElementHandle]>>> -The method runs `document.querySelectorAll` within the page. If no elements match the selector, the return value resolves to `[]`. +The method finds all elements matching the specified selector within the page. See [Working with selectors](#working-with-selectors) for more details. If no elements match the selector, the return value resolves to `[]`. Shortcut for [page.mainFrame().$$(selector)](#frameselector-1). @@ -863,7 +863,7 @@ Shortcut for [page.mainFrame().$$(selector)](#frameselector-1). - `arg` <[Serializable]|[JSHandle]> Optional argument to pass to `pageFunction` - returns: <[Promise]<[Serializable]>> Promise which resolves to the return value of `pageFunction` -This method runs `document.querySelector` within the page and passes it as the first argument to `pageFunction`. If there's no element matching `selector`, the method throws an error. +The method finds an element matching the specified selector within the page and passes it as a first argument to `pageFunction`. See [Working with selectors](#working-with-selectors) for more details. If no elements match the selector, the method throws an error. If `pageFunction` returns a [Promise], then `page.$eval` would wait for the promise to resolve and return its value. @@ -882,7 +882,7 @@ Shortcut for [page.mainFrame().$eval(selector, pageFunction)](#frameevalselector - `arg` <[Serializable]|[JSHandle]> Optional argument to pass to `pageFunction` - returns: <[Promise]<[Serializable]>> Promise which resolves to the return value of `pageFunction` -This method runs `Array.from(document.querySelectorAll(selector))` within the page and passes it as the first argument to `pageFunction`. +The method finds all elements matching the specified selector within the page and passes an array of matched elements as a first argument to `pageFunction`. See [Working with selectors](#working-with-selectors) for more details. If `pageFunction` returns a [Promise], then `page.$$eval` would wait for the promise to resolve and return its value. @@ -1941,13 +1941,13 @@ An example of getting text from an iframe element: - `selector` <[string]> A selector to query frame for - returns: <[Promise]> Promise which resolves to ElementHandle pointing to the frame element. -The method queries frame for the selector. If there's no such element within the frame, the method will resolve to `null`. +The method finds an element matching the specified selector within the frame. See [Working with selectors](#working-with-selectors) for more details. If no elements match the selector, the return value resolves to `null`. #### frame.$$(selector) - `selector` <[string]> A selector to query frame for - returns: <[Promise]<[Array]<[ElementHandle]>>> Promise which resolves to ElementHandles pointing to the frame elements. -The method runs `document.querySelectorAll` within the frame. If no elements match the selector, the return value resolves to `[]`. +The method finds all elements matching the specified selector within the frame. See [Working with selectors](#working-with-selectors) for more details. If no elements match the selector, the return value resolves to `[]`. #### frame.$eval(selector, pageFunction[, arg]) - `selector` <[string]> A selector to query frame for @@ -1955,7 +1955,7 @@ The method runs `document.querySelectorAll` within the frame. If no elements mat - `arg` <[Serializable]|[JSHandle]> Optional argument to pass to `pageFunction` - returns: <[Promise]<[Serializable]>> Promise which resolves to the return value of `pageFunction` -This method runs `document.querySelector` within the frame and passes it as the first argument to `pageFunction`. If there's no element matching `selector`, the method throws an error. +The method finds an element matching the specified selector within the frame and passes it as a first argument to `pageFunction`. See [Working with selectors](#working-with-selectors) for more details. If no elements match the 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. @@ -1972,7 +1972,7 @@ const html = await frame.$eval('.main-container', (e, suffix) => e.outerHTML + s - `arg` <[Serializable]|[JSHandle]> Optional argument to pass to `pageFunction` - returns: <[Promise]<[Serializable]>> Promise which resolves to the return value of `pageFunction` -This method runs `Array.from(document.querySelectorAll(selector))` within the frame and passes it as the first argument to `pageFunction`. +The method finds all elements matching the specified selector within the frame and passes an array of matched elements as a first argument to `pageFunction`. See [Working with selectors](#working-with-selectors) for more details. If `pageFunction` returns a [Promise], then `frame.$$eval` would wait for the promise to resolve and return its value. @@ -2538,13 +2538,13 @@ ElementHandle instances can be used as an argument in [`page.$eval()`](#pageeval - `selector` <[string]> A selector to query element for - returns: <[Promise]> -The method runs `element.querySelector` within the page. If no element matches the selector, the return value resolves to `null`. +The method finds an element matching the specified selector in the `ElementHandle`'s subtree. See [Working with selectors](#working-with-selectors) for more details. If no elements match the selector, the return value resolves to `null`. #### elementHandle.$$(selector) - `selector` <[string]> A selector to query element for - returns: <[Promise]<[Array]<[ElementHandle]>>> -The method runs `element.querySelectorAll` within the page. If no elements match the selector, the return value resolves to `[]`. +The method finds all elements matching the specified selector in the `ElementHandle`s subtree. See [Working with selectors](#working-with-selectors) for more details. If no elements match the selector, the return value resolves to `[]`. #### elementHandle.$eval(selector, pageFunction[, arg]) - `selector` <[string]> A selector to query page for @@ -2552,7 +2552,7 @@ The method runs `element.querySelectorAll` within the page. If no elements match - `arg` <[Serializable]|[JSHandle]> Optional argument to pass to `pageFunction` - returns: <[Promise]<[Serializable]>> Promise which resolves to the return value of `pageFunction` -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. +The method finds an element matching the specified selector in the `ElementHandle`s subtree and passes it as a first argument to `pageFunction`. See [Working with selectors](#working-with-selectors) for more details. If no elements match the 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. @@ -2569,7 +2569,7 @@ expect(await tweetHandle.$eval('.retweets', node => node.innerText)).toBe('10'); - `arg` <[Serializable]|[JSHandle]> Optional argument to pass to `pageFunction` - returns: <[Promise]<[Serializable]>> Promise which resolves to the return value of `pageFunction` -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. +The method finds all elements matching the specified selector in the `ElementHandle`'s subtree and passes an array of matched elements as a first argument to `pageFunction`. See [Working with selectors](#working-with-selectors) for more details. If `pageFunction` returns a [Promise], then `frame.$$eval` would wait for the promise to resolve and return its value.