diff --git a/docs/api.md b/docs/api.md index 34b1ea57396..de388e24942 100644 --- a/docs/api.md +++ b/docs/api.md @@ -31,6 +31,7 @@ + [event: 'response'](#event-response) + [page.$(selector)](#pageselector) + [page.$$(selector)](#pageselector) + + [page.$eval(selector, pageFunction[, ...args])](#pageevalselector-pagefunction-args) + [page.addScriptTag(url)](#pageaddscripttagurl) + [page.click(selector[, options])](#pageclickselector-options) + [page.close()](#pageclose) @@ -94,6 +95,7 @@ * [class: Frame](#class-frame) + [frame.$(selector)](#frameselector) + [frame.$$(selector)](#frameselector) + + [frame.$eval(selector, pageFunction[, ...args])](#frameevalselector-pagefunction-args) + [frame.addScriptTag(url)](#frameaddscripttagurl) + [frame.childFrames()](#framechildframes) + [frame.evaluate(pageFunction, ...args)](#frameevaluatepagefunction-args) @@ -107,7 +109,6 @@ + [frame.waitForFunction(pageFunction[, options, ...args])](#framewaitforfunctionpagefunction-options-args) + [frame.waitForSelector(selector[, options])](#framewaitforselectorselector-options) * [class: ElementHandle](#class-elementhandle) - + [elementHandle.attribute(key)](#elementhandleattributekey) + [elementHandle.click([options])](#elementhandleclickoptions) + [elementHandle.dispose()](#elementhandledispose) + [elementHandle.evaluate(pageFunction, ...args)](#elementhandleevaluatepagefunction-args) @@ -308,7 +309,7 @@ Emitted when a request finishes successfully. Emitted when a [response] is received. #### page.$(selector) -- `selector` <[string]> Selector to query page for +- `selector` <[string]> A [selector] to query page for - returns: <[Promise]<[ElementHandle]>> The method runs `document.querySelector` within the page. If no element matches the selector, the return value resolve to `null`. @@ -316,13 +317,32 @@ The method runs `document.querySelector` within the page. If no element matches Shortcut for [page.mainFrame().$(selector)](#frameselector). #### page.$$(selector) -- `selector` <[string]> Selector to query page for +- `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 resolve to `[]`. Shortcut for [page.mainFrame().$$(selector)](#frameselector-1). +#### page.$eval(selector, pageFunction[, ...args]) +- `selector` <[string]> A [selector] to query page for +- `pageFunction` <[function]> Function to be evaluated in browser context +- `...args` <...[Serializable]> Arguments 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. + +If `pageFunction` returns a [Promise], then `page.$eval` would wait for the promise to resolve and return it's 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 => e.outerHTML); +``` + +Shortcut for [page.mainFrame().$eval(selector, pageFunction)](#frameevalselector-pagefunction-args). + #### page.addScriptTag(url) - `url` <[string]> Url of the `