diff --git a/docs/src/api/class-browsertype.md b/docs/src/api/class-browsertype.md index f0c7973957..66cfeea97b 100644 --- a/docs/src/api/class-browsertype.md +++ b/docs/src/api/class-browsertype.md @@ -182,6 +182,13 @@ Maximum time in milliseconds to wait for the browser instance to start. Defaults disable timeout. ### option: BrowserType.launch.env +* langs: csharp,java +- `env` <[Object]<[string], [string]>> + +Specify environment variables that will be visible to the browser. Defaults to `process.env`. + +### option: BrowserType.launch.env +* langs: js,python - `env` <[Object]<[string], [string]|[float]|[boolean]>> Specify environment variables that will be visible to the browser. Defaults to `process.env`. diff --git a/docs/src/api/class-elementhandle.md b/docs/src/api/class-elementhandle.md index c8120a8a3d..f2d18f99eb 100644 --- a/docs/src/api/class-elementhandle.md +++ b/docs/src/api/class-elementhandle.md @@ -1,7 +1,7 @@ # class: ElementHandle * extends: [JSHandle] -ElementHandle represents an in-page DOM element. ElementHandles can be created with the [`method: Page.$`] method. +ElementHandle represents an in-page DOM element. ElementHandles can be created with the [`method: Page.querySelector`] method. ```js const { chromium } = require('playwright'); // Or 'firefox' or 'webkit'. @@ -54,119 +54,7 @@ with sync_playwright() as playwright: ElementHandle prevents DOM element from garbage collection unless the handle is disposed with [`method: JSHandle.dispose`]. ElementHandles are auto-disposed when their origin frame gets navigated. -ElementHandle instances can be used as an argument in [`method: Page.$eval`] and [`method: Page.evaluate`] methods. - -## async method: ElementHandle.$ -* langs: - - alias-python: query_selector -- returns: <[null]|[ElementHandle]> - -The method finds an element matching the specified selector in the `ElementHandle`'s subtree. See -[Working with selectors](./selectors.md) for more details. If no elements match the selector, -returns `null`. - -### param: ElementHandle.$.selector = %%-query-selector-%% - -## async method: ElementHandle.$$ -* langs: - - alias-python: query_selector_all -- returns: <[Array]<[ElementHandle]>> - -The method finds all elements matching the specified selector in the `ElementHandle`s subtree. See -[Working with selectors](./selectors.md) for more details. If no elements match the selector, -returns empty array. - -### param: ElementHandle.$$.selector = %%-query-selector-%% - -## async method: ElementHandle.$eval -* langs: - - alias-python: eval_on_selector -- returns: <[Serializable]> - -Returns the return value of [`param: pageFunction`] - -The method finds an element matching the specified selector in the `ElementHandle`s subtree and passes it as a first -argument to [`param: pageFunction`]. See [Working with selectors](./selectors.md) for more -details. If no elements match the selector, the method throws an error. - -If [`param: pageFunction`] returns a [Promise], then `frame.$eval` would wait for the promise to resolve and return its -value. - -Examples: - -```js -const tweetHandle = await page.$('.tweet'); -expect(await tweetHandle.$eval('.like', node => node.innerText)).toBe('100'); -expect(await tweetHandle.$eval('.retweets', node => node.innerText)).toBe('10'); -``` - -```python async -tweet_handle = await page.query_selector(".tweet") -assert await tweet_handle.eval_on_selector(".like", "node => node.innerText") == "100" -assert await tweet_handle.eval_on_selector(".retweets", "node => node.innerText") = "10" -``` - -```python sync -tweet_handle = page.query_selector(".tweet") -assert tweet_handle.eval_on_selector(".like", "node => node.innerText") == "100" -assert tweet_handle.eval_on_selector(".retweets", "node => node.innerText") = "10" -``` - -### param: ElementHandle.$eval.selector = %%-query-selector-%% - -### param: ElementHandle.$eval.expression = %%-evaluate-expression-%% - -### param: ElementHandle.$eval.arg -- `arg` <[EvaluationArgument]> - -Optional argument to pass to [`param: pageFunction`] - -## async method: ElementHandle.$$eval -* langs: - - alias-python: eval_on_selector_all -- returns: <[Serializable]> - -Returns the return value of [`param: pageFunction`] - -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 [`param: pageFunction`]. See -[Working with selectors](./selectors.md) for more details. - -If [`param: pageFunction`] returns a [Promise], then `frame.$$eval` would wait for the promise to resolve and return its -value. - -Examples: - -```html -
-
Hello!
-
Hi!
-
-``` - -```js -const feedHandle = await page.$('.feed'); -expect(await feedHandle.$$eval('.tweet', nodes => nodes.map(n => n.innerText))).toEqual(['Hello!', 'Hi!']); -``` - -```python async -feed_handle = await page.query_selector(".feed") -assert await feed_handle.eval_on_selector_all(".tweet", "nodes => nodes.map(n => n.innerText)") == ["hello!", "hi!"] -``` - -```python sync -feed_handle = page.query_selector(".feed") -assert feed_handle.eval_on_selector_all(".tweet", "nodes => nodes.map(n => n.innerText)") == ["hello!", "hi!"] -``` - -### param: ElementHandle.$$eval.selector = %%-query-selector-%% - -### param: ElementHandle.$$eval.expression = %%-evaluate-expression-%% - -### param: ElementHandle.$$eval.arg -- `arg` <[EvaluationArgument]> - -Optional argument to pass to [`param: pageFunction`] +ElementHandle instances can be used as an argument in [`method: Page.evalOnSelector`] and [`method: Page.evaluate`] methods. ## async method: ElementHandle.boundingBox - returns: <[null]|[Object]> @@ -353,6 +241,98 @@ DOM event type: `"click"`, `"dragstart"`, etc. Optional event-specific initialization properties. +## async method: ElementHandle.evalOnSelector +* langs: + - alias-python: eval_on_selector + - alias-js: $eval +- returns: <[Serializable]> + +Returns the return value of [`param: pageFunction`] + +The method finds an element matching the specified selector in the `ElementHandle`s subtree and passes it as a first +argument to [`param: pageFunction`]. See [Working with selectors](./selectors.md) for more +details. If no elements match the selector, the method throws an error. + +If [`param: pageFunction`] returns a [Promise], then [`method: ElementHandle.evalOnSelector`] would wait for the promise to resolve and return its +value. + +Examples: + +```js +const tweetHandle = await page.$('.tweet'); +expect(await tweetHandle.$eval('.like', node => node.innerText)).toBe('100'); +expect(await tweetHandle.$eval('.retweets', node => node.innerText)).toBe('10'); +``` + +```python async +tweet_handle = await page.query_selector(".tweet") +assert await tweet_handle.eval_on_selector(".like", "node => node.innerText") == "100" +assert await tweet_handle.eval_on_selector(".retweets", "node => node.innerText") = "10" +``` + +```python sync +tweet_handle = page.query_selector(".tweet") +assert tweet_handle.eval_on_selector(".like", "node => node.innerText") == "100" +assert tweet_handle.eval_on_selector(".retweets", "node => node.innerText") = "10" +``` + +### param: ElementHandle.evalOnSelector.selector = %%-query-selector-%% + +### param: ElementHandle.evalOnSelector.expression = %%-evaluate-expression-%% + +### param: ElementHandle.evalOnSelector.arg +- `arg` <[EvaluationArgument]> + +Optional argument to pass to [`param: pageFunction`] + +## async method: ElementHandle.evalOnSelectorAll +* langs: + - alias-python: eval_on_selector_all + - alias-js: $$eval +- returns: <[Serializable]> + +Returns the return value of [`param: pageFunction`] + +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 [`param: pageFunction`]. See +[Working with selectors](./selectors.md) for more details. + +If [`param: pageFunction`] returns a [Promise], then [`method: ElementHandle.evalOnSelectorAll`] would wait for the promise to resolve and return its +value. + +Examples: + +```html +
+
Hello!
+
Hi!
+
+``` + +```js +const feedHandle = await page.$('.feed'); +expect(await feedHandle.$$eval('.tweet', nodes => nodes.map(n => n.innerText))).toEqual(['Hello!', 'Hi!']); +``` + +```python async +feed_handle = await page.query_selector(".feed") +assert await feed_handle.eval_on_selector_all(".tweet", "nodes => nodes.map(n => n.innerText)") == ["hello!", "hi!"] +``` + +```python sync +feed_handle = page.query_selector(".feed") +assert feed_handle.eval_on_selector_all(".tweet", "nodes => nodes.map(n => n.innerText)") == ["hello!", "hi!"] +``` + +### param: ElementHandle.evalOnSelectorAll.selector = %%-query-selector-%% + +### param: ElementHandle.evalOnSelectorAll.expression = %%-evaluate-expression-%% + +### param: ElementHandle.evalOnSelectorAll.arg +- `arg` <[EvaluationArgument]> + +Optional argument to pass to [`param: pageFunction`] + ## async method: ElementHandle.fill This method waits for [actionability](./actionability.md) checks, focuses the element, fills it and triggers an `input` event after filling. @@ -485,6 +465,30 @@ Time to wait between `keydown` and `keyup` in milliseconds. Defaults to 0. ### option: ElementHandle.press.timeout = %%-input-timeout-%% +## async method: ElementHandle.querySelector +* langs: + - alias-python: query_selector + - alias-js: $ +- returns: <[null]|[ElementHandle]> + +The method finds an element matching the specified selector in the `ElementHandle`'s subtree. See +[Working with selectors](./selectors.md) for more details. If no elements match the selector, +returns `null`. + +### param: ElementHandle.querySelector.selector = %%-query-selector-%% + +## async method: ElementHandle.querySelectorAll +* langs: + - alias-python: query_selector_all + - alias-js: $$ +- returns: <[Array]<[ElementHandle]>> + +The method finds all elements matching the specified selector in the `ElementHandle`s subtree. See +[Working with selectors](./selectors.md) for more details. If no elements match the selector, +returns empty array. + +### param: ElementHandle.querySelectorAll.selector = %%-query-selector-%% + ## async method: ElementHandle.screenshot - returns: <[Buffer]> diff --git a/docs/src/api/class-frame.md b/docs/src/api/class-frame.md index 7546aa97bf..2bd127ef02 100644 --- a/docs/src/api/class-frame.md +++ b/docs/src/api/class-frame.md @@ -74,112 +74,6 @@ with sync_playwright() as playwright: run(playwright) ``` -## async method: Frame.$ -* langs: - - alias-python: query_selector -- returns: <[null]|[ElementHandle]> - -Returns the ElementHandle pointing to the frame element. - -The method finds an element matching the specified selector within the frame. See -[Working with selectors](./selectors.md) for more details. If no elements match the selector, -returns `null`. - -### param: Frame.$.selector = %%-query-selector-%% - -## async method: Frame.$$ -* langs: - - alias-python: query_selector_all -- returns: <[Array]<[ElementHandle]>> - -Returns the ElementHandles pointing to the frame elements. - -The method finds all elements matching the specified selector within the frame. See -[Working with selectors](./selectors.md) for more details. If no elements match the selector, -returns empty array. - -### param: Frame.$$.selector = %%-query-selector-%% - -## async method: Frame.$eval -* langs: - - alias-python: eval_on_selector -- returns: <[Serializable]> - -Returns the return value of [`param: pageFunction`] - -The method finds an element matching the specified selector within the frame and passes it as a first argument to -[`param: pageFunction`]. See [Working with selectors](./selectors.md) for more details. If no -elements match the selector, the method throws an error. - -If [`param: pageFunction`] returns a [Promise], then `frame.$eval` would wait for the promise to resolve and return its -value. - -Examples: - -```js -const searchValue = await frame.$eval('#search', el => el.value); -const preloadHref = await frame.$eval('link[rel=preload]', el => el.href); -const html = await frame.$eval('.main-container', (e, suffix) => e.outerHTML + suffix, 'hello'); -``` - -```python async -search_value = await frame.eval_on_selector("#search", "el => el.value") -preload_href = await frame.eval_on_selector("link[rel=preload]", "el => el.href") -html = await frame.eval_on_selector(".main-container", "(e, suffix) => e.outerHTML + suffix", "hello") -``` - -```python sync -search_value = frame.eval_on_selector("#search", "el => el.value") -preload_href = frame.eval_on_selector("link[rel=preload]", "el => el.href") -html = frame.eval_on_selector(".main-container", "(e, suffix) => e.outerHTML + suffix", "hello") -``` - -### param: Frame.$eval.selector = %%-query-selector-%% - -### param: Frame.$eval.expression = %%-evaluate-expression-%% - -### param: Frame.$eval.arg -- `arg` <[EvaluationArgument]> - -Optional argument to pass to [`param: pageFunction`] - -## async method: Frame.$$eval -* langs: - - alias-python: eval_on_selector_all -- returns: <[Serializable]> - -Returns the return value of [`param: 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 [`param: pageFunction`]. See [Working with selectors](./selectors.md) for -more details. - -If [`param: pageFunction`] returns a [Promise], then `frame.$$eval` would wait for the promise to resolve and return its -value. - -Examples: - -```js -const divsCounts = await frame.$$eval('div', (divs, min) => divs.length >= min, 10); -``` - -```python async -divs_counts = await frame.eval_on_selector_all("div", "(divs, min) => divs.length >= min", 10) -``` - -```python sync -divs_counts = frame.eval_on_selector_all("div", "(divs, min) => divs.length >= min", 10) -``` - -### param: Frame.$$eval.selector = %%-query-selector-%% - -### param: Frame.$$eval.expression = %%-evaluate-expression-%% - -### param: Frame.$$eval.arg -- `arg` <[EvaluationArgument]> - -Optional argument to pass to [`param: pageFunction`] - ## async method: Frame.addScriptTag - returns: <[ElementHandle]> @@ -400,6 +294,88 @@ Optional event-specific initialization properties. ### option: Frame.dispatchEvent.timeout = %%-input-timeout-%% +## async method: Frame.evalOnSelector +* langs: + - alias-python: eval_on_selector + - alias-js: $eval +- returns: <[Serializable]> + +Returns the return value of [`param: pageFunction`] + +The method finds an element matching the specified selector within the frame and passes it as a first argument to +[`param: pageFunction`]. See [Working with selectors](./selectors.md) for more details. If no +elements match the selector, the method throws an error. + +If [`param: pageFunction`] returns a [Promise], then [`method: Frame.evalOnSelector`] would wait for the promise to resolve and return its +value. + +Examples: + +```js +const searchValue = await frame.$eval('#search', el => el.value); +const preloadHref = await frame.$eval('link[rel=preload]', el => el.href); +const html = await frame.$eval('.main-container', (e, suffix) => e.outerHTML + suffix, 'hello'); +``` + +```python async +search_value = await frame.eval_on_selector("#search", "el => el.value") +preload_href = await frame.eval_on_selector("link[rel=preload]", "el => el.href") +html = await frame.eval_on_selector(".main-container", "(e, suffix) => e.outerHTML + suffix", "hello") +``` + +```python sync +search_value = frame.eval_on_selector("#search", "el => el.value") +preload_href = frame.eval_on_selector("link[rel=preload]", "el => el.href") +html = frame.eval_on_selector(".main-container", "(e, suffix) => e.outerHTML + suffix", "hello") +``` + +### param: Frame.evalOnSelector.selector = %%-query-selector-%% + +### param: Frame.evalOnSelector.expression = %%-evaluate-expression-%% + +### param: Frame.evalOnSelector.arg +- `arg` <[EvaluationArgument]> + +Optional argument to pass to [`param: pageFunction`] + +## async method: Frame.evalOnSelectorAll +* langs: + - alias-python: eval_on_selector_all + - alias-js: $$eval +- returns: <[Serializable]> + +Returns the return value of [`param: 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 [`param: pageFunction`]. See [Working with selectors](./selectors.md) for +more details. + +If [`param: pageFunction`] returns a [Promise], then [`method: Frame.evalOnSelectorAll`] would wait for the promise to resolve and return its +value. + +Examples: + +```js +const divsCounts = await frame.$$eval('div', (divs, min) => divs.length >= min, 10); +``` + +```python async +divs_counts = await frame.eval_on_selector_all("div", "(divs, min) => divs.length >= min", 10) +``` + +```python sync +divs_counts = frame.eval_on_selector_all("div", "(divs, min) => divs.length >= min", 10) +``` + +### param: Frame.evalOnSelectorAll.selector = %%-query-selector-%% + +### param: Frame.evalOnSelectorAll.expression = %%-evaluate-expression-%% + +### param: Frame.evalOnSelectorAll.arg +- `arg` <[EvaluationArgument]> + +Optional argument to pass to [`param: pageFunction`] + ## async method: Frame.evaluate - returns: <[Serializable]> @@ -817,6 +793,34 @@ Time to wait between `keydown` and `keyup` in milliseconds. Defaults to 0. ### option: Frame.press.timeout = %%-input-timeout-%% +## async method: Frame.querySelector +* langs: + - alias-python: query_selector + - alias-js: $ +- returns: <[null]|[ElementHandle]> + +Returns the ElementHandle pointing to the frame element. + +The method finds an element matching the specified selector within the frame. See +[Working with selectors](./selectors.md) for more details. If no elements match the selector, +returns `null`. + +### param: Frame.querySelector.selector = %%-query-selector-%% + +## async method: Frame.querySelectorAll +* langs: + - alias-python: query_selector_all + - alias-js: $$ +- returns: <[Array]<[ElementHandle]>> + +Returns the ElementHandles pointing to the frame elements. + +The method finds all elements matching the specified selector within the frame. See +[Working with selectors](./selectors.md) for more details. If no elements match the selector, +returns empty array. + +### param: Frame.querySelectorAll.selector = %%-query-selector-%% + ## async method: Frame.selectOption - returns: <[Array]<[string]>> diff --git a/docs/src/api/class-jshandle.md b/docs/src/api/class-jshandle.md index de0ff1c5f7..c4e67acf8a 100644 --- a/docs/src/api/class-jshandle.md +++ b/docs/src/api/class-jshandle.md @@ -22,7 +22,7 @@ JSHandle prevents the referenced JavaScript object being garbage collected unles [`method: JSHandle.dispose`]. JSHandles are auto-disposed when their origin frame gets navigated or the parent context gets destroyed. -JSHandle instances can be used as an argument in [`method: Page.$eval`], [`method: Page.evaluate`] and +JSHandle instances can be used as an argument in [`method: Page.evalOnSelector`], [`method: Page.evaluate`] and [`method: Page.evaluateHandle`] methods. ## method: JSHandle.asElement diff --git a/docs/src/api/class-page.md b/docs/src/api/class-page.md index c5125bb817..d7373b3f58 100644 --- a/docs/src/api/class-page.md +++ b/docs/src/api/class-page.md @@ -309,107 +309,6 @@ Emitted when <[WebSocket]> request is sent. Emitted when a dedicated [WebWorker](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API) is spawned by the page. -## async method: Page.$ -* langs: - - alias-python: query_selector -- returns: <[null]|[ElementHandle]> - -The method finds an element matching the specified selector within the page. If no elements match the selector, the -return value resolves to `null`. - -Shortcut for main frame's [`method: Frame.$`]. - -### param: Page.$.selector = %%-query-selector-%% - -## async method: Page.$$ -* langs: - - alias-python: query_selector_all -- returns: <[Array]<[ElementHandle]>> - -The method finds all elements matching the specified selector within the page. If no elements match the selector, the -return value resolves to `[]`. - -Shortcut for main frame's [`method: Frame.$$`]. - -### param: Page.$$.selector = %%-query-selector-%% - -## async method: Page.$eval -* langs: - - alias-python: eval_on_selector -- returns: <[Serializable]> - -The method finds an element matching the specified selector within the page and passes it as a first argument to -[`param: pageFunction`]. If no elements match the selector, the method throws an error. Returns the value of -[`param: pageFunction`]. - -If [`param: pageFunction`] returns a [Promise], then [`method: Page.$eval`] would wait for the promise to resolve and -return its value. - -Examples: - -```js -const searchValue = await page.$eval('#search', el => el.value); -const preloadHref = await page.$eval('link[rel=preload]', el => el.href); -const html = await page.$eval('.main-container', (e, suffix) => e.outerHTML + suffix, 'hello'); -``` - -```python async -search_value = await page.eval_on_selector("#search", "el => el.value") -preload_href = await page.eval_on_selector("link[rel=preload]", "el => el.href") -html = await page.eval_on_selector(".main-container", "(e, suffix) => e.outer_html + suffix", "hello") -``` - -```python sync -search_value = page.eval_on_selector("#search", "el => el.value") -preload_href = page.eval_on_selector("link[rel=preload]", "el => el.href") -html = page.eval_on_selector(".main-container", "(e, suffix) => e.outer_html + suffix", "hello") -``` - -Shortcut for main frame's [`method: Frame.$eval`]. - -### param: Page.$eval.selector = %%-query-selector-%% - -### param: Page.$eval.expression = %%-evaluate-expression-%% - -### param: Page.$eval.arg -- `arg` <[EvaluationArgument]> - -Optional argument to pass to [`param: pageFunction`] - -## async method: Page.$$eval -* langs: - - alias-python: eval_on_selector_all -- returns: <[Serializable]> - -The method finds all elements matching the specified selector within the page and passes an array of matched elements as -a first argument to [`param: pageFunction`]. Returns the result of [`param: pageFunction`] invocation. - -If [`param: pageFunction`] returns a [Promise], then [`method: Page.$$eval`] would wait for the promise to resolve and -return its value. - -Examples: - -```js -const divCounts = await page.$$eval('div', (divs, min) => divs.length >= min, 10); -``` - -```python async -div_counts = await page.eval_on_selector_all("div", "(divs, min) => divs.length >= min", 10) -``` - -```python sync -div_counts = page.eval_on_selector_all("div", "(divs, min) => divs.length >= min", 10) -``` - -### param: Page.$$eval.selector = %%-query-selector-%% - -### param: Page.$$eval.expression = %%-evaluate-expression-%% - -### param: Page.$$eval.arg -- `arg` <[EvaluationArgument]> - -Optional argument to pass to [`param: pageFunction`] - ## property: Page.accessibility - type: <[Accessibility]> @@ -821,6 +720,85 @@ Passing `null` disables CSS media emulation. Emulates `'prefers-colors-scheme'` media feature, supported values are `'light'`, `'dark'`, `'no-preference'`. Passing `null` disables color scheme emulation. +## async method: Page.evalOnSelector +* langs: + - alias-python: eval_on_selector + - alias-js: $eval +- returns: <[Serializable]> + +The method finds an element matching the specified selector within the page and passes it as a first argument to +[`param: pageFunction`]. If no elements match the selector, the method throws an error. Returns the value of +[`param: pageFunction`]. + +If [`param: pageFunction`] returns a [Promise], then [`method: Page.evalOnSelector`] would wait for the promise to resolve and +return its value. + +Examples: + +```js +const searchValue = await page.$eval('#search', el => el.value); +const preloadHref = await page.$eval('link[rel=preload]', el => el.href); +const html = await page.$eval('.main-container', (e, suffix) => e.outerHTML + suffix, 'hello'); +``` + +```python async +search_value = await page.eval_on_selector("#search", "el => el.value") +preload_href = await page.eval_on_selector("link[rel=preload]", "el => el.href") +html = await page.eval_on_selector(".main-container", "(e, suffix) => e.outer_html + suffix", "hello") +``` + +```python sync +search_value = page.eval_on_selector("#search", "el => el.value") +preload_href = page.eval_on_selector("link[rel=preload]", "el => el.href") +html = page.eval_on_selector(".main-container", "(e, suffix) => e.outer_html + suffix", "hello") +``` + +Shortcut for main frame's [`method: Frame.evalOnSelector`]. + +### param: Page.evalOnSelector.selector = %%-query-selector-%% + +### param: Page.evalOnSelector.expression = %%-evaluate-expression-%% + +### param: Page.evalOnSelector.arg +- `arg` <[EvaluationArgument]> + +Optional argument to pass to [`param: pageFunction`] + +## async method: Page.evalOnSelectorAll +* langs: + - alias-python: eval_on_selector_all + - alias-js: $$eval +- returns: <[Serializable]> + +The method finds all elements matching the specified selector within the page and passes an array of matched elements as +a first argument to [`param: pageFunction`]. Returns the result of [`param: pageFunction`] invocation. + +If [`param: pageFunction`] returns a [Promise], then [`method: Page.evalOnSelectorAll`] would wait for the promise to resolve and +return its value. + +Examples: + +```js +const divCounts = await page.$$eval('div', (divs, min) => divs.length >= min, 10); +``` + +```python async +div_counts = await page.eval_on_selector_all("div", "(divs, min) => divs.length >= min", 10) +``` + +```python sync +div_counts = page.eval_on_selector_all("div", "(divs, min) => divs.length >= min", 10) +``` + +### param: Page.evalOnSelectorAll.selector = %%-query-selector-%% + +### param: Page.evalOnSelectorAll.expression = %%-evaluate-expression-%% + +### param: Page.evalOnSelectorAll.arg +- `arg` <[EvaluationArgument]> + +Optional argument to pass to [`param: pageFunction`] + ## async method: Page.evaluate - returns: <[Serializable]> @@ -1717,6 +1695,32 @@ Time to wait between `keydown` and `keyup` in milliseconds. Defaults to 0. ### option: Page.press.timeout = %%-input-timeout-%% +## async method: Page.querySelector +* langs: + - alias-python: query_selector + - alias-js: $ +- returns: <[null]|[ElementHandle]> + +The method finds an element matching the specified selector within the page. If no elements match the selector, the +return value resolves to `null`. + +Shortcut for main frame's [`method: Frame.querySelector`]. + +### param: Page.querySelector.selector = %%-query-selector-%% + +## async method: Page.querySelectorAll +* langs: + - alias-python: query_selector_all + - alias-js: $$ +- returns: <[Array]<[ElementHandle]>> + +The method finds all elements matching the specified selector within the page. If no elements match the selector, the +return value resolves to `[]`. + +Shortcut for main frame's [`method: Frame.querySelectorAll`]. + +### param: Page.querySelectorAll.selector = %%-query-selector-%% + ## async method: Page.reload - returns: <[null]|[Response]> diff --git a/docs/src/api/javascript.md b/docs/src/api/javascript.md index fbeb10fca6..3dbcfdb8da 100644 --- a/docs/src/api/javascript.md +++ b/docs/src/api/javascript.md @@ -1,14 +1,14 @@ -### param: ElementHandle.$eval.expression = %%-js-evalonselector-pagefunction-%% -### param: ElementHandle.$$eval.expression = %%-js-evalonselectorall-pagefunction-%% -### param: Frame.$eval.expression = %%-js-evalonselector-pagefunction-%% -### param: Frame.$$eval.expression = %%-js-evalonselectorall-pagefunction-%% +### param: ElementHandle.evalOnSelector.expression = %%-js-evalonselector-pagefunction-%% +### param: ElementHandle.evalOnSelectorAll.expression = %%-js-evalonselectorall-pagefunction-%% +### param: Frame.evalOnSelector.expression = %%-js-evalonselector-pagefunction-%% +### param: Frame.evalOnSelectorAll.expression = %%-js-evalonselectorall-pagefunction-%% ### param: Frame.evaluate.expression = %%-js-evaluate-pagefunction-%% ### param: Frame.evaluateHandle.expression = %%-js-evaluate-pagefunction-%% ### param: Frame.waitForFunction.expression = %%-js-evaluate-pagefunction-%% ### param: JSHandle.evaluate.expression = %%-js-evaluate-pagefunction-%% ### param: JSHandle.evaluateHandle.expression = %%-js-evaluate-pagefunction-%% -### param: Page.$eval.expression = %%-js-evalonselector-pagefunction-%% -### param: Page.$$eval.expression = %%-js-evalonselectorall-pagefunction-%% +### param: Page.evalOnSelector.expression = %%-js-evalonselector-pagefunction-%% +### param: Page.evalOnSelectorAll.expression = %%-js-evalonselectorall-pagefunction-%% ### param: Page.evaluate.expression = %%-js-evaluate-pagefunction-%% ### param: Page.evaluateHandle.expression = %%-js-evaluate-pagefunction-%% ### param: Page.waitForFunction.expression = %%-js-evaluate-pagefunction-%% diff --git a/docs/src/api/python.md b/docs/src/api/python.md index c7a3ec1471..dfe6817e39 100644 --- a/docs/src/api/python.md +++ b/docs/src/api/python.md @@ -275,17 +275,17 @@ Will throw an error if the socket is closed before the `event` is fired. ### option: WebSocket.waitForEvent2.predicate = %%-python-wait-for-event-predicate-%% ### option: WebSocket.waitForEvent2.timeout = %%-python-wait-for-event-timeout-%% -### param: ElementHandle.$eval.foce_expression = %%-python-evaluate-force-expression-%% -### param: ElementHandle.$$eval.foce_expression = %%-python-evaluate-force-expression-%% -### param: Frame.$eval.foce_expression = %%-python-evaluate-force-expression-%% -### param: Frame.$$eval.foce_expression = %%-python-evaluate-force-expression-%% +### param: ElementHandle.evalOnSelector.foce_expression = %%-python-evaluate-force-expression-%% +### param: ElementHandle.evalOnSelectorAll.foce_expression = %%-python-evaluate-force-expression-%% +### param: Frame.evalOnSelector.foce_expression = %%-python-evaluate-force-expression-%% +### param: Frame.evalOnSelectorAll.foce_expression = %%-python-evaluate-force-expression-%% ### param: Frame.evaluate.foce_expression = %%-python-evaluate-force-expression-%% ### param: Frame.evaluateHandle.foce_expression = %%-python-evaluate-force-expression-%% ### param: Frame.waitForFunction.foce_expression = %%-python-evaluate-force-expression-%% ### param: JSHandle.evaluate.foce_expression = %%-python-evaluate-force-expression-%% ### param: JSHandle.evaluateHandle.foce_expression = %%-python-evaluate-force-expression-%% -### param: Page.$eval.foce_expression = %%-python-evaluate-force-expression-%% -### param: Page.$$eval.foce_expression = %%-python-evaluate-force-expression-%% +### param: Page.evalOnSelector.foce_expression = %%-python-evaluate-force-expression-%% +### param: Page.evalOnSelectorAll.foce_expression = %%-python-evaluate-force-expression-%% ### param: Page.evaluate.foce_expression = %%-python-evaluate-force-expression-%% ### param: Page.evaluateHandle.foce_expression = %%-python-evaluate-force-expression-%% ### param: Page.waitForFunction.foce_expression = %%-python-evaluate-force-expression-%% diff --git a/docs/src/assertions.md b/docs/src/assertions.md index 3127683727..1c4c74b51c 100644 --- a/docs/src/assertions.md +++ b/docs/src/assertions.md @@ -107,7 +107,7 @@ assert content == "home" ``` ### API reference -- [`method: Page.$eval`] +- [`method: Page.evalOnSelector`] - [`method: JSHandle.evaluate`] ## Inner HTML @@ -238,11 +238,11 @@ assert length == 3 ### API reference - [`method: Page.evaluate`] -- [`method: Page.$eval`] -- [`method: Page.$$eval`] +- [`method: Page.evalOnSelector`] +- [`method: Page.evalOnSelectorAll`] - [`method: Frame.evaluate`] -- [`method: Frame.$eval`] -- [`method: Frame.$$eval`] -- [`method: ElementHandle.$eval`] -- [`method: ElementHandle.$$eval`] +- [`method: Frame.evalOnSelector`] +- [`method: Frame.evalOnSelectorAll`] +- [`method: ElementHandle.evalOnSelector`] +- [`method: ElementHandle.evalOnSelectorAll`] - [EvaluationArgument] diff --git a/docs/src/handles.md b/docs/src/handles.md index e9dff34cd3..20532f2b2f 100644 --- a/docs/src/handles.md +++ b/docs/src/handles.md @@ -172,8 +172,8 @@ my_array_handle.dispose() ## Handle Lifecycle Handles can be acquired using the page methods such as [`method: Page.evaluateHandle`], -[`method: Page.$`] or [`method: Page.$$`] or their frame counterparts -[`method: Frame.evaluateHandle`], [`method: Frame.$`] or [`method: Frame.$$`]. Once +[`method: Page.querySelector`] or [`method: Page.querySelectorAll`] or their frame counterparts +[`method: Frame.evaluateHandle`], [`method: Frame.querySelector`] or [`method: Frame.querySelectorAll`]. Once created, handles will retain object from [garbage collection](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Memory_Management) unless page navigates or the handle is manually disposed via the [`method: JSHandle.dispose`] method. @@ -189,5 +189,5 @@ unless page navigates or the handle is manually disposed via the [`method: JSHan - [`method: ElementHandle.textContent`] - [`method: JSHandle.evaluate`] - [`method: Page.evaluateHandle`] -- [`method: Page.$`] -- [`method: Page.$$`] +- [`method: Page.querySelector`] +- [`method: Page.querySelectorAll`] diff --git a/types/types.d.ts b/types/types.d.ts index 0a0ea1f217..28e20bfcbf 100644 --- a/types/types.d.ts +++ b/types/types.d.ts @@ -3289,7 +3289,9 @@ export interface Frame { * `pageFunction`. See [Working with selectors](https://playwright.dev/docs/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. + * If `pageFunction` returns a [Promise], then + * [frame.$eval(selector, pageFunction[, arg])](https://playwright.dev/docs/api/class-frame#frameevalselector-pagefunction-arg) + * would wait for the promise to resolve and return its value. * * Examples: * @@ -3314,7 +3316,9 @@ export interface Frame { * 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](https://playwright.dev/docs/selectors) for more details. * - * If `pageFunction` returns a [Promise], then `frame.$$eval` would wait for the promise to resolve and return its value. + * If `pageFunction` returns a [Promise], then + * [frame.$$eval(selector, pageFunction[, arg])](https://playwright.dev/docs/api/class-frame#frameevalselector-pagefunction-arg) + * would wait for the promise to resolve and return its value. * * Examples: * @@ -5302,7 +5306,9 @@ export interface ElementHandle extends JSHandle { * argument to `pageFunction`. See [Working with selectors](https://playwright.dev/docs/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. + * If `pageFunction` returns a [Promise], then + * [elementHandle.$eval(selector, pageFunction[, arg])](https://playwright.dev/docs/api/class-elementhandle#elementhandleevalselector-pagefunction-arg) + * would wait for the promise to resolve and return its value. * * Examples: * @@ -5327,7 +5333,9 @@ export interface ElementHandle extends JSHandle { * 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](https://playwright.dev/docs/selectors) for more details. * - * If `pageFunction` returns a [Promise], then `frame.$$eval` would wait for the promise to resolve and return its value. + * If `pageFunction` returns a [Promise], then + * [elementHandle.$$eval(selector, pageFunction[, arg])](https://playwright.dev/docs/api/class-elementhandle#elementhandleevalselector-pagefunction-arg) + * would wait for the promise to resolve and return its value. * * Examples: * diff --git a/utils/doclint/api_parser.js b/utils/doclint/api_parser.js index bcdddc912b..6effc1664a 100644 --- a/utils/doclint/api_parser.js +++ b/utils/doclint/api_parser.js @@ -115,10 +115,12 @@ class ApiParser { */ parseArgument(spec) { const match = spec.text.match(/(param|option): ([^.]+)\.([^.]+)\.(.*)/); + if(!match) + throw `Something went wrong with matching ${spec.text}`; const clazz = this.classes.get(match[2]); if (!clazz) throw new Error('Invalid class ' + match[2]); - const method = clazz.membersArray.find(m => m.kind === 'method' && m.name === match[3]); + const method = clazz.membersArray.find(m => m.kind === 'method' && m.alias === match[3]); if (!method) throw new Error('Invalid method ' + match[2] + '.' + match[3]); const name = match[4]; diff --git a/utils/generate_types/index.js b/utils/generate_types/index.js index 9a202c87f6..fce286c1b0 100644 --- a/utils/generate_types/index.js +++ b/utils/generate_types/index.js @@ -79,7 +79,7 @@ let hadChanges = false; return writeComment(docClassForName(className).comment) + '\n'; }, (className, methodName) => { const docClass = docClassForName(className); - const method = docClass.methods.get(methodName); + const method = docClass.methodsArray.find(m => m.alias === methodName); handledMethods.add(`${className}.${methodName}`); if (!method) { if (new Set(['on', 'addListener', 'off', 'removeListener', 'once']).has(methodName))