github/puppeteer
0
0
Fork 0
mirror of https://github.com/puppeteer/puppeteer synced 2024-06-14 14:02:48 +00:00
Code Issues Packages Projects Releases Wiki Activity

[doclint] remove preprocessor's gen:copy and gen:paste commands

Browse Source 
These commands proved to be over-complicating the documentation source.
We should keep documentation source as simple to edit as possible to
make it friendly to contributions.

This patch keeps the gen:version command as it is non-invasive.
This commit is contained in:
Andrey Lushnikov 2017-07-31 21:14:50 -07:00
parent 2acfec0989
commit 337315c5fe
3 changed files with 8 additions and 180 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

70
docs/api.md
View File

@ -312,8 +312,6 @@ Emitted when a request is successfully finished.
Emitted when a [response] is received. Emitted when a [response] is received.
#### page.$(selector, pageFunction, ...args) #### page.$(selector, pageFunction, ...args)
<!-- gen:paste('frame.$') -->
<!-- Text below is automatically copied from "gen:copy('frame.$')" -->
- `selector` <[string]> A [selector] to be matched in the page - `selector` <[string]> A [selector] to be matched in the page
- `pageFunction` <[function]\([Element]\)> Function to be evaluated with first element matching `selector` - `pageFunction` <[function]\([Element]\)> Function to be evaluated with first element matching `selector`
- `...args` <...[string]> Arguments to pass to `pageFunction` - `...args` <...[string]> Arguments to pass to `pageFunction`
@ -322,12 +320,9 @@ Example:
```js ```js
const outerhtml = await page.$('#box', e => e.outerHTML); const outerhtml = await page.$('#box', e => e.outerHTML);
``` ```
<!-- gen:stop -->
Shortcut for [page.mainFrame().$(selector, pageFunction, ...args)](#frameselector-pagefunction-args). Shortcut for [page.mainFrame().$(selector, pageFunction, ...args)](#frameselector-pagefunction-args).
#### page.$$(selector, pageFunction, ...args) #### page.$$(selector, pageFunction, ...args)
<!-- gen:paste('frame.$$') -->
<!-- Text below is automatically copied from "gen:copy('frame.$$')" -->
- `selector` <[string]> A [selector] to be matched in the page - `selector` <[string]> A [selector] to be matched in the page
- `pageFunction` <[function]\([Element]\)> Function to be evaluted for every element matching `selector`. - `pageFunction` <[function]\([Element]\)> Function to be evaluted for every element matching `selector`.
- `...args` <...[string]> Arguments to pass to `pageFunction` - `...args` <...[string]> Arguments to pass to `pageFunction`
@ -337,32 +332,25 @@ Example:
const headings = await page.$$('h1,h2,h3,h4', el => el.textContent); const headings = await page.$$('h1,h2,h3,h4', el => el.textContent);
for (const heading of headings) console.log(heading); for (const heading of headings) console.log(heading);
``` ```
<!-- gen:stop -->
Shortcut for [page.mainFrame().$$(selector, pageFunction, ...args)](#frameselector-pagefunction-args-1). Shortcut for [page.mainFrame().$$(selector, pageFunction, ...args)](#frameselector-pagefunction-args-1).
#### page.addScriptTag(url) #### page.addScriptTag(url)
<!-- gen:paste('frame.addScriptTag') -->
<!-- Text below is automatically copied from "gen:copy('frame.addScriptTag')" -->
- `url` <[string]> Url of a script to be added - `url` <[string]> Url of a script to be added
- returns: <[Promise]> Promise which resolves as the script gets added and loads. - returns: <[Promise]> Promise which resolves as the script gets added and loads.
Adds a `<script>` tag to the frame with the desired url. Alternatively, JavaScript could be injected to the frame via [`frame.injectFile`](#frameinjectfilefilepath) method. Adds a `<script>` tag to the frame with the desired url. Alternatively, JavaScript could be injected to the frame via [`frame.injectFile`](#frameinjectfilefilepath) method.
<!-- gen:stop -->
Shortcut for [page.mainFrame().addScriptTag(url)](#frameaddscripttagurl). Shortcut for [page.mainFrame().addScriptTag(url)](#frameaddscripttagurl).
#### page.click(selector[, options]) #### page.click(selector[, options])
<!-- gen:paste('frame.click') -->
<!-- Text below is automatically copied from "gen:copy('frame.click')" -->
- `selector` <[string]> A query [selector] to search for element to click. If there are multiple elements satisfying the selector, the first will be clicked. - `selector` <[string]> A query [selector] to search for element to click. If there are multiple elements satisfying the selector, the first will be clicked.
- `options` <[Object]> - `options` <[Object]>
- `button` <[string]> `left`, `right`, or `middle`, defaults to `left`. - `button` <[string]> `left`, `right`, or `middle`, defaults to `left`.
- `clickCount` <[number]> defaults to 1 - `clickCount` <[number]> defaults to 1
- `delay` <[number]> Time to wait between `mousedown` and `mouseup` in milliseconds. Defaults to 0. - `delay` <[number]> Time to wait between `mousedown` and `mouseup` in milliseconds. Defaults to 0.
- returns: <[Promise]> Promise which resolves when the element matching `selector` is successfully clicked. Promise gets rejected if there's no element matching `selector`. - returns: <[Promise]> Promise which resolves when the element matching `selector` is successfully clicked. Promise gets rejected if there's no element matching `selector`.
<!-- gen:stop -->
Shortcut for [page.mainFrame().click(selector[, options])](#frameclickselector-options). Shortcut for [page.mainFrame().click(selector[, options])](#frameclickselector-options).
@ -370,8 +358,6 @@ Shortcut for [page.mainFrame().click(selector[, options])](#frameclickselector-o
- returns: <[Promise]> Returns promise which resolves when page gets closed. - returns: <[Promise]> Returns promise which resolves when page gets closed.
#### page.evaluate(pageFunction, ...args) #### page.evaluate(pageFunction, ...args)
<!-- gen:paste('frame.evaluate') -->
<!-- Text below is automatically copied from "gen:copy('frame.evaluate')" -->
- `pageFunction` <[function]|[string]> Function to be evaluated in browser context - `pageFunction` <[function]|[string]> Function to be evaluated in browser context
- `...args` <...[string]> Arguments to pass to `pageFunction` - `...args` <...[string]> Arguments to pass to `pageFunction`
- returns: <[Promise]<[Object]>> Promise which resolves to function return value - returns: <[Promise]<[Object]>> Promise which resolves to function return value
@ -395,7 +381,6 @@ A string can also be passed in instead of a function.
```js ```js
console.log(await page.evaluate('1 + 2')); // prints "3" console.log(await page.evaluate('1 + 2')); // prints "3"
``` ```
<!-- gen:stop -->
Shortcut for [page.mainFrame().evaluate(pageFunction, ...args)](#frameevaluatepagefunction-args). Shortcut for [page.mainFrame().evaluate(pageFunction, ...args)](#frameevaluatepagefunction-args).
@ -411,11 +396,8 @@ Adds a function which would be invoked in one of the following scenarios:
The function is invoked after the document was created but before any of its scripts were run. This is useful to amend JavaScript environment, e.g. to seed [Math.random](https://github.com/GoogleChrome/puppeteer/blob/master/examples/unrandomize.js) The function is invoked after the document was created but before any of its scripts were run. This is useful to amend JavaScript environment, e.g. to seed [Math.random](https://github.com/GoogleChrome/puppeteer/blob/master/examples/unrandomize.js)
#### page.focus(selector) #### page.focus(selector)
<!-- gen:paste('frame.focus') -->
<!-- Text below is automatically copied from "gen:copy('frame.focus')" -->
- `selector` <[string]> A query [selector] of element to focus. If there are multiple elements satisfying the selector, the first will be focused. - `selector` <[string]> A query [selector] of element to focus. If there are multiple elements satisfying the selector, the first will be focused.
- returns: <[Promise]> Promise which resolves when the element matching `selector` is successfully focused. Promise gets rejected if there's no element matching `selector`. - returns: <[Promise]> Promise which resolves when the element matching `selector` is successfully focused. Promise gets rejected if there's no element matching `selector`.
<!-- gen:stop -->
Shortcut for [page.mainFrame().focus(selector)](#framefocusselector). Shortcut for [page.mainFrame().focus(selector)](#framefocusselector).
@ -449,20 +431,14 @@ can not go back, resolves to null.
Navigate to the next page in history. Navigate to the next page in history.
#### page.hover(selector) #### page.hover(selector)
<!-- gen:paste('frame.hover') -->
<!-- Text below is automatically copied from "gen:copy('frame.hover')" -->
- `selector` <[string]> A query [selector] to search for element to hover. If there are multiple elements satisfying the selector, the first will be hovered. - `selector` <[string]> A query [selector] to search for element to hover. If there are multiple elements satisfying the selector, the first will be hovered.
- returns: <[Promise]> Promise which resolves when the element matching `selector` is successfully hovered. Promise gets rejected if there's no element matching `selector`. - returns: <[Promise]> Promise which resolves when the element matching `selector` is successfully hovered. Promise gets rejected if there's no element matching `selector`.
<!-- gen:stop -->
Shortcut for [page.mainFrame().hover(selector)](#framehoverselector). Shortcut for [page.mainFrame().hover(selector)](#framehoverselector).
#### page.injectFile(filePath) #### page.injectFile(filePath)
<!-- gen:paste('frame.injectFile') -->
<!-- Text below is automatically copied from "gen:copy('frame.injectFile')" -->
- `filePath` <[string]> Path to the JavaScript file to be injected into frame. If `filePath` is a relative path, then it is resolved relative to [current working directory](https://nodejs.org/api/process.html#process_process_cwd). - `filePath` <[string]> Path to the JavaScript file to be injected into frame. If `filePath` is a relative path, then it is resolved relative to [current working directory](https://nodejs.org/api/process.html#process_process_cwd).
- returns: <[Promise]> Promise which resolves when file gets successfully evaluated in frame. - returns: <[Promise]> Promise which resolves when file gets successfully evaluated in frame.
<!-- gen:stop -->
Shortcut for [page.mainFrame().injectFile(filePath)](#frameinjectfilefilepath). Shortcut for [page.mainFrame().injectFile(filePath)](#frameinjectfilefilepath).
@ -656,10 +632,7 @@ screenshot (unless a `fullPage` option is given).
In case of multiple pages in one browser, each page can have its own viewport size. In case of multiple pages in one browser, each page can have its own viewport size.
#### page.title() #### page.title()
<!-- gen:paste('frame.title') -->
<!-- Text below is automatically copied from "gen:copy('frame.title')" -->
- returns: <[Promise]<[string]>> Returns page's title. - returns: <[Promise]<[string]>> Returns page's title.
<!-- gen:stop -->
Shortcut for [page.mainFrame().title()](#frametitle). Shortcut for [page.mainFrame().title()](#frametitle).
@ -679,20 +652,14 @@ page.type('World', {delay: 100}); // Types slower, like a user
``` ```
#### page.uploadFile(selector, ...filePaths) #### page.uploadFile(selector, ...filePaths)
<!-- gen:paste('frame.uploadFile') -->
<!-- Text below is automatically copied from "gen:copy('frame.uploadFile')" -->
- `selector` <[string]> A query [selector] to a file input - `selector` <[string]> A query [selector] to a file input
- `...filePaths` <[string]> Sets the value of the file input these paths. If some of the `filePaths` are relative paths, then they are resolved relative to [current working directory](https://nodejs.org/api/process.html#process_process_cwd). - `...filePaths` <[string]> Sets the value of the file input these paths. If some of the `filePaths` are relative paths, then they are resolved relative to [current working directory](https://nodejs.org/api/process.html#process_process_cwd).
- returns: <[Promise]> Promise which resolves when the value is set. - returns: <[Promise]> Promise which resolves when the value is set.
<!-- gen:stop -->
Shortcut for [page.mainFrame().uploadFile(selector, ...filePaths)](#frameuploadfileselector-filepaths). Shortcut for [page.mainFrame().uploadFile(selector, ...filePaths)](#frameuploadfileselector-filepaths).
#### page.url() #### page.url()
<!-- gen:paste('frame.url') -->
<!-- Text below is automatically copied from "gen:copy('frame.url')" -->
- returns: <[string]> - returns: <[string]>
<!-- gen:stop -->
This is a shortcut for [page.mainFrame().url()](#frameurl) This is a shortcut for [page.mainFrame().url()](#frameurl)
@ -700,8 +667,6 @@ This is a shortcut for [page.mainFrame().url()](#frameurl)
- returns: <[Object]> An object with the save fields as described in [page.setViewport](#pagesetviewportviewport) - returns: <[Object]> An object with the save fields as described in [page.setViewport](#pagesetviewportviewport)
#### page.waitFor(selectorOrFunctionOrTimeout[, options]) #### page.waitFor(selectorOrFunctionOrTimeout[, options])
<!-- gen:paste('frame.waitFor') -->
<!-- Text below is automatically copied from "gen:copy('frame.waitFor')" -->
- `selectorOrFunctionOrTimeout` <[string]|[number]|[function]> A [selector], predicate or timeout to wait for - `selectorOrFunctionOrTimeout` <[string]|[number]|[function]> A [selector], predicate or timeout to wait for
- `options` <[Object]> Optional waiting parameters - `options` <[Object]> Optional waiting parameters
- returns: <[Promise]> - returns: <[Promise]>
@ -711,13 +676,10 @@ This method behaves differently with respect to the type of the first parameter:
- if `selectorOrFunctionOrTimeout` is a `function`, than the first argument is treated as a predicate to wait for and the method is a shortcut for [frame.waitForFunction()](#framewaitforfunctionpagefunction-options-args). - if `selectorOrFunctionOrTimeout` is a `function`, than the first argument is treated as a predicate to wait for and the method is a shortcut for [frame.waitForFunction()](#framewaitforfunctionpagefunction-options-args).
- if `selectorOrFunctionOrTimeout` is a `number`, than the first argument is treated as a timeout in milliseconds and the method returns a promise which resolves after the timeout - if `selectorOrFunctionOrTimeout` is a `number`, than the first argument is treated as a timeout in milliseconds and the method returns a promise which resolves after the timeout
- otherwise, an exception is thrown - otherwise, an exception is thrown
<!-- gen:stop -->
Shortcut for [page.mainFrame().waitFor(selectorOrFunctionOrTimeout[, options])](#framewaitforselectororfunctionortimeout-options). Shortcut for [page.mainFrame().waitFor(selectorOrFunctionOrTimeout[, options])](#framewaitforselectororfunctionortimeout-options).
#### page.waitForFunction(pageFunction[, options, ...args]) #### page.waitForFunction(pageFunction[, options, ...args])
<!-- gen:paste('frame.waitForFunction') -->
<!-- Text below is automatically copied from "gen:copy('frame.waitForFunction')" -->
- `pageFunction` <[function]|[string]> Function to be evaluated in browser context - `pageFunction` <[function]|[string]> Function to be evaluated in browser context
- `options` <[Object]> Optional waiting parameters - `options` <[Object]> Optional waiting parameters
- `polling` <[string]|[number]> An interval at which the `pageFunction` is executed, defaults to `raf`. If `polling` is a number, then it is treated as an interval in milliseconds at which the function would be executed. If `polling` is a string, then it could be one of the following values: - `polling` <[string]|[number]> An interval at which the `pageFunction` is executed, defaults to `raf`. If `polling` is a number, then it is treated as an interval in milliseconds at which the function would be executed. If `polling` is a string, then it could be one of the following values:
@ -739,7 +701,6 @@ browser.newPage().then(async page => {
browser.close(); browser.close();
}); });
``` ```
<!-- gen:stop -->
Shortcut for [page.mainFrame().waitForFunction(pageFunction[, options, ...args])](#framewaitforfunctionpagefunction-options-args). Shortcut for [page.mainFrame().waitForFunction(pageFunction[, options, ...args])](#framewaitforfunctionpagefunction-options-args).
#### page.waitForNavigation(options) #### page.waitForNavigation(options)
@ -753,8 +714,6 @@ Shortcut for [page.mainFrame().waitForFunction(pageFunction[, options, ...args])
- returns: <[Promise]<[Response]>> Promise which resolves to the main resource response. In case of multiple redirects, the navigation will resolve with the response of the last redirect. - returns: <[Promise]<[Response]>> Promise which resolves to the main resource response. In case of multiple redirects, the navigation will resolve with the response of the last redirect.
#### page.waitForSelector(selector[, options]) #### page.waitForSelector(selector[, options])
<!-- gen:paste('frame.waitForSelector') -->
<!-- Text below is automatically copied from "gen:copy('frame.waitForSelector')" -->
- `selector` <[string]> CSS selector of awaited element, - `selector` <[string]> CSS selector of awaited element,
- `options` <[Object]> Optional waiting parameters - `options` <[Object]> Optional waiting parameters
- `visible` <[boolean]> wait for 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`. - `visible` <[boolean]> wait for 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`.
@ -778,7 +737,6 @@ browser.newPage().then(async page => {
browser.close(); browser.close();
}); });
``` ```
<!-- gen:stop -->
Shortcut for [page.mainFrame().waitForSelector(selector[, options])](#framewaitforselectorselector-options). Shortcut for [page.mainFrame().waitForSelector(selector[, options])](#framewaitforselectorselector-options).
### class: Keyboard ### class: Keyboard
@ -931,7 +889,6 @@ browser.newPage().then(async page => {
``` ```
#### frame.$(selector, pageFunction, ...args) #### frame.$(selector, pageFunction, ...args)
<!-- gen:copy('frame.$') -->
- `selector` <[string]> A [selector] to be matched in the page - `selector` <[string]> A [selector] to be matched in the page
- `pageFunction` <[function]\([Element]\)> Function to be evaluated with first element matching `selector` - `pageFunction` <[function]\([Element]\)> Function to be evaluated with first element matching `selector`
- `...args` <...[string]> Arguments to pass to `pageFunction` - `...args` <...[string]> Arguments to pass to `pageFunction`
@ -940,11 +897,9 @@ Example:
```js ```js
const outerhtml = await page.$('#box', e => e.outerHTML); const outerhtml = await page.$('#box', e => e.outerHTML);
``` ```
<!-- gen:stop -->
#### frame.$$(selector, pageFunction, ...args) #### frame.$$(selector, pageFunction, ...args)
<!-- gen:copy('frame.$$') -->
- `selector` <[string]> A [selector] to be matched in the page - `selector` <[string]> A [selector] to be matched in the page
- `pageFunction` <[function]\([Element]\)> Function to be evaluted for every element matching `selector`. - `pageFunction` <[function]\([Element]\)> Function to be evaluted for every element matching `selector`.
- `...args` <...[string]> Arguments to pass to `pageFunction` - `...args` <...[string]> Arguments to pass to `pageFunction`
@ -954,32 +909,26 @@ Example:
const headings = await page.$$('h1,h2,h3,h4', el => el.textContent); const headings = await page.$$('h1,h2,h3,h4', el => el.textContent);
for (const heading of headings) console.log(heading); for (const heading of headings) console.log(heading);
``` ```
<!-- gen:stop -->
#### frame.addScriptTag(url) #### frame.addScriptTag(url)
<!-- gen:copy('frame.addScriptTag') -->
- `url` <[string]> Url of a script to be added - `url` <[string]> Url of a script to be added
- returns: <[Promise]> Promise which resolves as the script gets added and loads. - returns: <[Promise]> Promise which resolves as the script gets added and loads.
Adds a `<script>` tag to the frame with the desired url. Alternatively, JavaScript could be injected to the frame via [`frame.injectFile`](#frameinjectfilefilepath) method. Adds a `<script>` tag to the frame with the desired url. Alternatively, JavaScript could be injected to the frame via [`frame.injectFile`](#frameinjectfilefilepath) method.
<!-- gen:stop -->
#### frame.childFrames() #### frame.childFrames()
- returns: <[Array]<[Frame]>> - returns: <[Array]<[Frame]>>
#### frame.click(selector[, options]) #### frame.click(selector[, options])
<!-- gen:copy('frame.click') -->
- `selector` <[string]> A query [selector] to search for element to click. If there are multiple elements satisfying the selector, the first will be clicked. - `selector` <[string]> A query [selector] to search for element to click. If there are multiple elements satisfying the selector, the first will be clicked.
- `options` <[Object]> - `options` <[Object]>
- `button` <[string]> `left`, `right`, or `middle`, defaults to `left`. - `button` <[string]> `left`, `right`, or `middle`, defaults to `left`.
- `clickCount` <[number]> defaults to 1 - `clickCount` <[number]> defaults to 1
- `delay` <[number]> Time to wait between `mousedown` and `mouseup` in milliseconds. Defaults to 0. - `delay` <[number]> Time to wait between `mousedown` and `mouseup` in milliseconds. Defaults to 0.
- returns: <[Promise]> Promise which resolves when the element matching `selector` is successfully clicked. Promise gets rejected if there's no element matching `selector`. - returns: <[Promise]> Promise which resolves when the element matching `selector` is successfully clicked. Promise gets rejected if there's no element matching `selector`.
<!-- gen:stop -->
#### frame.evaluate(pageFunction, ...args) #### frame.evaluate(pageFunction, ...args)
<!-- gen:copy('frame.evaluate') -->
- `pageFunction` <[function]|[string]> Function to be evaluated in browser context - `pageFunction` <[function]|[string]> Function to be evaluated in browser context
- `...args` <...[string]> Arguments to pass to `pageFunction` - `...args` <...[string]> Arguments to pass to `pageFunction`
- returns: <[Promise]<[Object]>> Promise which resolves to function return value - returns: <[Promise]<[Object]>> Promise which resolves to function return value
@ -1003,26 +952,19 @@ A string can also be passed in instead of a function.
```js ```js
console.log(await page.evaluate('1 + 2')); // prints "3" console.log(await page.evaluate('1 + 2')); // prints "3"
``` ```
<!-- gen:stop -->
#### frame.focus(selector) #### frame.focus(selector)
<!-- gen:copy('frame.focus') -->
- `selector` <[string]> A query [selector] of element to focus. If there are multiple elements satisfying the selector, the first will be focused. - `selector` <[string]> A query [selector] of element to focus. If there are multiple elements satisfying the selector, the first will be focused.
- returns: <[Promise]> Promise which resolves when the element matching `selector` is successfully focused. Promise gets rejected if there's no element matching `selector`. - returns: <[Promise]> Promise which resolves when the element matching `selector` is successfully focused. Promise gets rejected if there's no element matching `selector`.
<!-- gen:stop -->
#### frame.hover(selector) #### frame.hover(selector)
<!-- gen:copy('frame.hover') -->
- `selector` <[string]> A query [selector] to search for element to hover. If there are multiple elements satisfying the selector, the first will be hovered. - `selector` <[string]> A query [selector] to search for element to hover. If there are multiple elements satisfying the selector, the first will be hovered.
- returns: <[Promise]> Promise which resolves when the element matching `selector` is successfully hovered. Promise gets rejected if there's no element matching `selector`. - returns: <[Promise]> Promise which resolves when the element matching `selector` is successfully hovered. Promise gets rejected if there's no element matching `selector`.
<!-- gen:stop -->
#### frame.injectFile(filePath) #### frame.injectFile(filePath)
<!-- gen:copy('frame.injectFile') -->
- `filePath` <[string]> Path to the JavaScript file to be injected into frame. If `filePath` is a relative path, then it is resolved relative to [current working directory](https://nodejs.org/api/process.html#process_process_cwd). - `filePath` <[string]> Path to the JavaScript file to be injected into frame. If `filePath` is a relative path, then it is resolved relative to [current working directory](https://nodejs.org/api/process.html#process_process_cwd).
- returns: <[Promise]> Promise which resolves when file gets successfully evaluated in frame. - returns: <[Promise]> Promise which resolves when file gets successfully evaluated in frame.
<!-- gen:stop -->
#### frame.isDetached() #### frame.isDetached()
- returns: <[boolean]> - returns: <[boolean]>
@ -1042,26 +984,19 @@ Note: This value is calculated once when the frame is created, and will not upda
- returns: <[Frame]> Returns parent frame, if any. Detached frames and main frames return `null`. - returns: <[Frame]> Returns parent frame, if any. Detached frames and main frames return `null`.
#### frame.title() #### frame.title()
<!-- gen:copy('frame.title') -->
- returns: <[Promise]<[string]>> Returns page's title. - returns: <[Promise]<[string]>> Returns page's title.
<!-- gen:stop -->
#### frame.uploadFile(selector, ...filePaths) #### frame.uploadFile(selector, ...filePaths)
<!-- gen:copy('frame.uploadFile') -->
- `selector` <[string]> A query [selector] to a file input - `selector` <[string]> A query [selector] to a file input
- `...filePaths` <[string]> Sets the value of the file input these paths. If some of the `filePaths` are relative paths, then they are resolved relative to [current working directory](https://nodejs.org/api/process.html#process_process_cwd). - `...filePaths` <[string]> Sets the value of the file input these paths. If some of the `filePaths` are relative paths, then they are resolved relative to [current working directory](https://nodejs.org/api/process.html#process_process_cwd).
- returns: <[Promise]> Promise which resolves when the value is set. - returns: <[Promise]> Promise which resolves when the value is set.
<!-- gen:stop -->
#### frame.url() #### frame.url()
<!-- gen:copy('frame.url') -->
- returns: <[string]> - returns: <[string]>
<!-- gen:stop -->
Returns frame's url. Returns frame's url.
#### frame.waitFor(selectorOrFunctionOrTimeout[, options]) #### frame.waitFor(selectorOrFunctionOrTimeout[, options])
<!-- gen:copy('frame.waitFor') -->
- `selectorOrFunctionOrTimeout` <[string]|[number]|[function]> A [selector], predicate or timeout to wait for - `selectorOrFunctionOrTimeout` <[string]|[number]|[function]> A [selector], predicate or timeout to wait for
- `options` <[Object]> Optional waiting parameters - `options` <[Object]> Optional waiting parameters
- returns: <[Promise]> - returns: <[Promise]>
@ -1071,11 +1006,9 @@ This method behaves differently with respect to the type of the first parameter:
- if `selectorOrFunctionOrTimeout` is a `function`, than the first argument is treated as a predicate to wait for and the method is a shortcut for [frame.waitForFunction()](#framewaitforfunctionpagefunction-options-args). - if `selectorOrFunctionOrTimeout` is a `function`, than the first argument is treated as a predicate to wait for and the method is a shortcut for [frame.waitForFunction()](#framewaitforfunctionpagefunction-options-args).
- if `selectorOrFunctionOrTimeout` is a `number`, than the first argument is treated as a timeout in milliseconds and the method returns a promise which resolves after the timeout - if `selectorOrFunctionOrTimeout` is a `number`, than the first argument is treated as a timeout in milliseconds and the method returns a promise which resolves after the timeout
- otherwise, an exception is thrown - otherwise, an exception is thrown
<!-- gen:stop -->
#### frame.waitForFunction(pageFunction[, options, ...args]) #### frame.waitForFunction(pageFunction[, options, ...args])
<!-- gen:copy('frame.waitForFunction') -->
- `pageFunction` <[function]|[string]> Function to be evaluated in browser context - `pageFunction` <[function]|[string]> Function to be evaluated in browser context
- `options` <[Object]> Optional waiting parameters - `options` <[Object]> Optional waiting parameters
- `polling` <[string]|[number]> An interval at which the `pageFunction` is executed, defaults to `raf`. If `polling` is a number, then it is treated as an interval in milliseconds at which the function would be executed. If `polling` is a string, then it could be one of the following values: - `polling` <[string]|[number]> An interval at which the `pageFunction` is executed, defaults to `raf`. If `polling` is a number, then it is treated as an interval in milliseconds at which the function would be executed. If `polling` is a string, then it could be one of the following values:
@ -1097,10 +1030,8 @@ browser.newPage().then(async page => {
browser.close(); browser.close();
}); });
``` ```
<!-- gen:stop -->
#### frame.waitForSelector(selector[, options]) #### frame.waitForSelector(selector[, options])
<!-- gen:copy('frame.waitForSelector') -->
- `selector` <[string]> CSS selector of awaited element, - `selector` <[string]> CSS selector of awaited element,
- `options` <[Object]> Optional waiting parameters - `options` <[Object]> Optional waiting parameters
- `visible` <[boolean]> wait for 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`. - `visible` <[boolean]> wait for 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`.
@ -1124,7 +1055,6 @@ browser.newPage().then(async page => {
browser.close(); browser.close();
}); });
``` ```
<!-- gen:stop -->
### class: Request ### class: Request

56
utils/doclint/preprocessor/index.js
View File

@ -45,27 +45,13 @@ module.exports = function(sources) {
commands = validateCommands(commands, messages); commands = validateCommands(commands, messages);
// Extract copied text.
let copyIds = new Map();
for (let command of commands) {
if (command.name !== 'copy')
continue;
const copyText = command.source.text().substring(command.from, command.to);
copyIds.set(command.arg, copyText);
}
let changedSources = new Set(); let changedSources = new Set();
// Iterate commands in reverse order so that edits don't conflict. // Iterate commands in reverse order so that edits don't conflict.
commands.sort((a, b) => b.from - a.from); commands.sort((a, b) => b.from - a.from);
for (let command of commands) { for (let command of commands) {
let newText = command.source.text(); let newText = command.source.text();
if (command.name === 'version') { if (command.name === 'version')
newText = replaceInText(newText, command.from, command.to, PUPPETEER_VERSION); newText = replaceInText(newText, command.from, command.to, PUPPETEER_VERSION);
} else if (command.name === 'paste') {
let copyText = copyIds.get(command.arg);
copyText = `\n<!-- Text below is automatically copied from "gen:copy(${command.arg})" -->` + copyText;
newText = replaceInText(newText, command.from, command.to, copyText);
}
if (command.source.setText(newText)) if (command.source.setText(newText))
changedSources.add(command.source); changedSources.add(command.source);
} }
@ -84,42 +70,9 @@ function validateCommands(commands, outMessages) {
let goodCommands = commands.filter(command => { let goodCommands = commands.filter(command => {
if (command.name === 'version') if (command.name === 'version')
return check(command, !command.arg, `"gen:version" should not have argument`); return check(command, !command.arg, `"gen:version" should not have argument`);
if (command.name === 'copy')
return check(command, command.arg, `"gen:copy" should have argument - copyId`);
if (command.name === 'paste')
return check(command, command.arg, `"gen:paste" should have argument - name of the register to paste from`);
check(command, false, `Unknown command: "gen:${command.name}"`); check(command, false, `Unknown command: "gen:${command.name}"`);
}); });
// Make sure copy commands don't clash ids.
let copyIds = new Map();
goodCommands = goodCommands.filter(command => {
if (command.name !== 'copy')
return true;
const duplicateCopy = copyIds.get(command.arg);
const duplicatePath = duplicateCopy ? duplicateCopy.source.projectPath() : '';
if (check(command, !duplicateCopy, `"gen:copy" tries to re-define copy id "${command.arg}" - previously defined in ${duplicatePath}`)) {
copyIds.set(command.arg, command);
return true;
}
return false;
});
// Make sure paste commands refer to proper ids, and every copyId is used at least
// once.
let unusedCopyIds = new Set(copyIds.keys());
goodCommands = goodCommands.filter(command => {
if (command.name !== 'paste')
return true;
unusedCopyIds.delete(command.arg);
if (check(command, copyIds.has(command.arg), `"gen:paste" refers to unknown copy id "${command.arg}"`))
return true;
return false;
});
for (let copyId of unusedCopyIds) {
let command = copyIds.get(copyId);
check(command, false, `"gen:copy" defines unused copy id "${copyId}"`);
}
return goodCommands; return goodCommands;
function check(command, condition, message) { function check(command, condition, message) {
@ -130,6 +83,13 @@ function validateCommands(commands, outMessages) {
} }
} }
/**
* @param {string} text
* @param {number} from
* @param {number} to
* @param {string} newText
* @return {string}
*/
function replaceInText(text, from, to, newText) { function replaceInText(text, from, to, newText) {
return text.substring(0, from) + newText + text.substring(to); return text.substring(0, from) + newText + text.substring(to);
} }

62
utils/doclint/preprocessor/test.js
View File

@ -19,16 +19,6 @@ const SourceFactory = require('../SourceFactory');
const factory = new SourceFactory(); const factory = new SourceFactory();
const VERSION = require('../../../package.json').version; const VERSION = require('../../../package.json').version;
let COPY_INPUT = `
<!-- gen:copy("test") -->Heyo!<!-- gen:stop -->
<!-- gen:paste("test") --><!-- gen:stop -->
`;
let COPY_EXPECTED = `
<!-- gen:copy("test") -->Heyo!<!-- gen:stop -->
<!-- gen:paste("test") -->
<!-- Text below is automatically copied from "gen:copy("test")" -->Heyo!<!-- gen:stop -->
`;
describe('preprocessor', function() { describe('preprocessor', function() {
it('should throw for unknown command', function() { it('should throw for unknown command', function() {
let source = factory.createForTest('doc.md', getCommand('unknownCommand()')); let source = factory.createForTest('doc.md', getCommand('unknownCommand()'));
@ -62,58 +52,6 @@ describe('preprocessor', function() {
expect(messages[0].text).toContain(`Failed to find 'gen:stop'`); expect(messages[0].text).toContain(`Failed to find 'gen:stop'`);
}); });
}); });
describe('gen:copy', function() {
it('should work', function() {
let source = factory.createForTest('doc.md', COPY_INPUT);
preprocessor([source]);
expect(source.hasUpdatedText()).toBe(true);
expect(source.text()).toBe(COPY_EXPECTED);
});
it('should throw if copy does not have argument', function() {
let source = factory.createForTest('doc.md', getCommand('copy()'));
let messages = preprocessor([source]);
expect(source.hasUpdatedText()).toBe(false);
expect(messages.length).toBe(1);
expect(messages[0].type).toBe('error');
expect(messages[0].text).toContain('should have argument');
});
it('should throw if copyId is not used', function() {
let source = factory.createForTest('doc.md', getCommand('copy(command-id)'));
let messages = preprocessor([source]);
expect(source.hasUpdatedText()).toBe(false);
expect(messages.length).toBe(1);
expect(messages[0].type).toBe('error');
expect(messages[0].text).toContain('unused copy id');
});
it('should throw if duplicate copy id', function() {
const copyCmd = getCommand('copy(foo)');
let source = factory.createForTest('doc.md', copyCmd + copyCmd);
let messages = preprocessor([source]);
messages.sort();
expect(source.hasUpdatedText()).toBe(false);
expect(messages.length).toBe(2);
expect(messages[0].type).toBe('error');
expect(messages[0].text).toContain('re-define copy id');
});
});
describe('gen:paste', function() {
it('should throw if paste does not have argument', function() {
let source = factory.createForTest('doc.md', getCommand('paste()'));
let messages = preprocessor([source]);
expect(source.hasUpdatedText()).toBe(false);
expect(messages.length).toBe(1);
expect(messages[0].type).toBe('error');
expect(messages[0].text).toContain('should have argument');
});
it('should throw if copyId is not defined', function() {
let source = factory.createForTest('doc.md', getCommand('paste(bar)'));
let messages = preprocessor([source]);
expect(source.hasUpdatedText()).toBe(false);
expect(messages.length).toBe(1);
expect(messages[0].type).toBe('error');
expect(messages[0].text).toContain('unknown copy id');
});
});
}); });
function getCommand(name, body = '') { function getCommand(name, body = '') {