From 55f2f5a7ecde5897ca71c6194acdc78a37a1c118 Mon Sep 17 00:00:00 2001 From: Pavel Feldman Date: Tue, 7 Jan 2020 13:57:37 -0800 Subject: [PATCH] chore: move capabilities around for better docs (#407) --- docs/api.md | 226 ++++++++++++++++++------------------- src/api.ts | 4 +- src/chromium/crApi.ts | 2 - src/chromium/crCoverage.ts | 4 +- src/chromium/crPage.ts | 27 ++--- src/chromium/crPdf.ts | 19 +--- src/chromium/crWorkers.ts | 5 +- src/firefox/ffPage.ts | 6 +- src/page.ts | 28 +++++ src/platform.ts | 2 +- src/types.ts | 22 ++++ src/webkit/wkBrowser.ts | 2 +- src/webkit/wkPage.ts | 6 +- 13 files changed, 192 insertions(+), 161 deletions(-) diff --git a/docs/api.md b/docs/api.md index 459ecc4639..da19d58b5f 100644 --- a/docs/api.md +++ b/docs/api.md @@ -21,7 +21,7 @@ * [browserContext.newPage()](#browsercontextnewpage) * [browserContext.pages()](#browsercontextpages) * [browserContext.setCookies(cookies)](#browsercontextsetcookiescookies) - * [browserContext.setGeolocation(options)](#browsercontextsetgeolocationoptions) + * [browserContext.setGeolocation(geolocation)](#browsercontextsetgeolocationgeolocation) * [browserContext.setPermissions(origin, permissions[])](#browsercontextsetpermissionsorigin-permissions) - [class: BrowserFetcher](#class-browserfetcher) * [browserFetcher.canDownload(revision)](#browserfetchercandownloadrevision) @@ -146,6 +146,7 @@ * [page.$eval(selector, pageFunction[, ...args])](#pageevalselector-pagefunction-args-1) * [page.$wait(selector, pageFunction[, options[, ...args]])](#pagewaitselector-pagefunction-options-args) * [page.$x(expression)](#pagexexpression) + * [page.accessibility](#pageaccessibility) * [page.addScriptTag(options)](#pageaddscripttagoptions) * [page.addStyleTag(options)](#pageaddstyletagoptions) * [page.authenticate(credentials)](#pageauthenticatecredentials) @@ -153,6 +154,7 @@ * [page.click(selector[, options])](#pageclickselector-options) * [page.close([options])](#pagecloseoptions) * [page.content()](#pagecontent) + * [page.coverage](#pagecoverage) * [page.dblclick(selector[, options])](#pagedblclickselector-options) * [page.emulateMedia(options)](#pageemulatemediaoptions) * [page.evaluate(pageFunction[, ...args])](#pageevaluatepagefunction-args) @@ -170,6 +172,7 @@ * [page.keyboard](#pagekeyboard) * [page.mainFrame()](#pagemainframe) * [page.mouse](#pagemouse) + * [page.pdf([options])](#pagepdfoptions) * [page.reload([options])](#pagereloadoptions) * [page.screenshot([options])](#pagescreenshotoptions) * [page.select(selector, value, options)](#pageselectselector-value-options) @@ -222,8 +225,8 @@ * [response.text()](#responsetext) * [response.url()](#responseurl) - [class: TimeoutError](#class-timeouterror) -- [class: ChromiumAccessibility](#class-chromiumaccessibility) - * [chromiumAccessibility.snapshot([options])](#chromiumaccessibilitysnapshotoptions) +- [class: Accessibility](#class-accessibility) + * [accessibility.snapshot([options])](#accessibilitysnapshotoptions) - [class: ChromiumBrowser](#class-chromiumbrowser) * [event: 'targetchanged'](#event-targetchanged) * [event: 'targetcreated'](#event-targetcreated) @@ -235,11 +238,11 @@ * [chromiumBrowser.stopTracing()](#chromiumbrowserstoptracing) * [chromiumBrowser.targets(context)](#chromiumbrowsertargetscontext) * [chromiumBrowser.waitForTarget(predicate[, options])](#chromiumbrowserwaitfortargetpredicate-options) -- [class: ChromiumCoverage](#class-chromiumcoverage) - * [chromiumCoverage.startCSSCoverage([options])](#chromiumcoveragestartcsscoverageoptions) - * [chromiumCoverage.startJSCoverage([options])](#chromiumcoveragestartjscoverageoptions) - * [chromiumCoverage.stopCSSCoverage()](#chromiumcoveragestopcsscoverage) - * [chromiumCoverage.stopJSCoverage()](#chromiumcoveragestopjscoverage) +- [class: Coverage](#class-coverage) + * [coverage.startCSSCoverage([options])](#coveragestartcsscoverageoptions) + * [coverage.startJSCoverage([options])](#coveragestartjscoverageoptions) + * [coverage.stopCSSCoverage()](#coveragestopcsscoverage) + * [coverage.stopJSCoverage()](#coveragestopjscoverage) - [class: ChromiumPlaywright](#class-chromiumplaywright) * [chromiumPlaywright.connect(options)](#chromiumplaywrightconnectoptions) * [chromiumPlaywright.createBrowserFetcher([options])](#chromiumplaywrightcreatebrowserfetcheroptions) @@ -250,11 +253,6 @@ * [chromiumPlaywright.executablePath()](#chromiumplaywrightexecutablepath) * [chromiumPlaywright.launch([options])](#chromiumplaywrightlaunchoptions) * [chromiumPlaywright.launchServer([options])](#chromiumplaywrightlaunchserveroptions) -- [class: ChromiumPage](#class-chromiumpage) - * [chromiumPage.accessibility](#chromiumpageaccessibility) - * [chromiumPage.coverage](#chromiumpagecoverage) - * [chromiumPage.interception](#chromiumpageinterception) - * [chromiumPage.pdf([options])](#chromiumpagepdfoptions) - [class: ChromiumSession](#class-chromiumsession) * [chromiumSession.detach()](#chromiumsessiondetach) * [chromiumSession.send(method[, params])](#chromiumsessionsendmethod-params) @@ -265,10 +263,10 @@ * [chromiumTarget.page()](#chromiumtargetpage) * [chromiumTarget.type()](#chromiumtargettype) * [chromiumTarget.url()](#chromiumtargeturl) -- [class: ChromiumWorker](#class-chromiumworker) - * [chromiumWorker.evaluate(pageFunction[, ...args])](#chromiumworkerevaluatepagefunction-args) - * [chromiumWorker.evaluateHandle(pageFunction[, ...args])](#chromiumworkerevaluatehandlepagefunction-args) - * [chromiumWorker.url()](#chromiumworkerurl) +- [class: Worker](#class-worker) + * [worker.evaluate(pageFunction[, ...args])](#workerevaluatepagefunction-args) + * [worker.evaluateHandle(pageFunction[, ...args])](#workerevaluatehandlepagefunction-args) + * [worker.url()](#workerurl) - [class: FirefoxBrowser](#class-firefoxbrowser) - [class: WebKitBrowser](#class-webkitbrowser) - [Working with selectors](#working-with-selectors) @@ -351,10 +349,12 @@ Indicates that the browser is connected. - `hasTouch`<[boolean]> Specifies if viewport supports touch events. Defaults to `false` - `isLandscape` <[boolean]> Specifies if viewport is in landscape mode. Defaults to `false`. - `userAgent` Specific user agent to use in this page - - `mediaType` Changes the CSS media type of the page. - - `colorScheme` Emulates `'prefers-colors-scheme'` media feature. - `javaScriptEnabled` Whether or not to enable or disable JavaScript in the page. Defaults to true. - `timezoneId` Changes the timezone of the page. See [ICU’s `metaZones.txt`](https://cs.chromium.org/chromium/src/third_party/icu/source/data/misc/metaZones.txt?rcl=faee8bc70570192d82d2978a71e2a615788597d1) for a list of supported timezone IDs. + - `geolocation` <[Object]> + - `latitude` <[number]> Latitude between -90 and 90. + - `longitude` <[number]> Longitude between -180 and 180. + - `accuracy` <[number]> Optional non-negative accuracy value. - returns: <[Promise]<[BrowserContext]>> Creates a new browser context. It won't share cookies/cache with other browser contexts. @@ -465,8 +465,8 @@ An array of all pages inside the browser context. await browserContext.setCookies([cookieObject1, cookieObject2]); ``` -#### browserContext.setGeolocation(options) -- `options` <[Object]> +#### browserContext.setGeolocation(geolocation) +- `geolocation` <[Object]> - `latitude` <[number]> Latitude between -90 and 90. - `longitude` <[number]> Longitude between -180 and 180. - `accuracy` <[number]> Optional non-negative accuracy value. @@ -1218,7 +1218,7 @@ If the name is empty, returns the id attribute instead. #### frame.select(selector, value, options) - `selector` <[string]> A selector to query frame for. -- `value` <[string]|[ElementHandle]|[Object]|[Array]<[string]>|[Array]<[ElementHandle]>|[Array]<[Object]>> Options to select. If the `` has the `multiple` attribute, all matching options are selected, otherwise only the first option matching one of the passed options is selected. String values are equivalent to `{value:'string'}`. Option is considered matching if all specified properties match. - `value` <[string]> Matches by `option.value`. - `label` <[string]> Matches by `option.label`. - `index` <[number]> Matches by the index. @@ -1928,6 +1928,9 @@ The method evaluates the XPath expression. Shortcut for [page.mainFrame().$x(expression)](#framexexpression) +#### page.accessibility +- returns: <[Accessibility]> + #### page.addScriptTag(options) - `options` <[Object]> - `url` <[string]> URL of a script to be added. @@ -2012,6 +2015,10 @@ By default, `page.close()` **does not** run beforeunload handlers. Gets the full HTML contents of the page, including the doctype. +#### page.coverage + +- returns: <[Coverage]> + #### page.dblclick(selector[, options]) - `selector` <[string]> A selector to search for element to double click. If there are multiple elements satisfying the selector, the first will be double clicked. - `options` <[Object]> @@ -2333,6 +2340,74 @@ Page is guaranteed to have a main frame which persists during navigations. - returns: <[Mouse]> +#### page.pdf([options]) +- `options` <[Object]> Options object which might have the following properties: + - `path` <[string]> The file path to save the PDF to. If `path` is a relative path, then it is resolved relative to [current working directory](https://nodejs.org/api/process.html#process_process_cwd). If no path is provided, the PDF won't be saved to the disk. + - `scale` <[number]> Scale of the webpage rendering. Defaults to `1`. Scale amount must be between 0.1 and 2. + - `displayHeaderFooter` <[boolean]> Display header and footer. Defaults to `false`. + - `headerTemplate` <[string]> HTML template for the print header. Should be valid HTML markup with following classes used to inject printing values into them: + - `'date'` formatted print date + - `'title'` document title + - `'url'` document location + - `'pageNumber'` current page number + - `'totalPages'` total pages in the document + - `footerTemplate` <[string]> HTML template for the print footer. Should use the same format as the `headerTemplate`. + - `printBackground` <[boolean]> Print background graphics. Defaults to `false`. + - `landscape` <[boolean]> Paper orientation. Defaults to `false`. + - `pageRanges` <[string]> Paper ranges to print, e.g., '1-5, 8, 11-13'. Defaults to the empty string, which means print all pages. + - `format` <[string]> Paper format. If set, takes priority over `width` or `height` options. Defaults to 'Letter'. + - `width` <[string]|[number]> Paper width, accepts values labeled with units. + - `height` <[string]|[number]> Paper height, accepts values labeled with units. + - `margin` <[Object]> Paper margins, defaults to none. + - `top` <[string]|[number]> Top margin, accepts values labeled with units. + - `right` <[string]|[number]> Right margin, accepts values labeled with units. + - `bottom` <[string]|[number]> Bottom margin, accepts values labeled with units. + - `left` <[string]|[number]> Left margin, accepts values labeled with units. + - `preferCSSPageSize` <[boolean]> Give any CSS `@page` size declared in the page priority over what is declared in `width` and `height` or `format` options. Defaults to `false`, which will scale the content to fit the paper size. +- returns: <[Promise]<[Buffer]>> Promise which resolves with PDF buffer. + +> **NOTE** Generating a pdf is currently only supported in Chrome headless. + +`page.pdf()` generates a pdf of the page with `print` css media. To generate a pdf with `screen` media, call [page.emulateMedia({ type: 'screen' })](#pageemulatemedia) before calling `page.pdf()`: + +> **NOTE** By default, `page.pdf()` generates a pdf with modified colors for printing. Use the [`-webkit-print-color-adjust`](https://developer.mozilla.org/en-US/docs/Web/CSS/-webkit-print-color-adjust) property to force rendering of exact colors. + +```js +// Generates a PDF with 'screen' media type. +await page.emulateMedia({type: 'screen'}); +await page.pdf({path: 'page.pdf'}); +``` + +The `width`, `height`, and `margin` options accept values labeled with units. Unlabeled values are treated as pixels. + +A few examples: +- `page.pdf({width: 100})` - prints with width set to 100 pixels +- `page.pdf({width: '100px'})` - prints with width set to 100 pixels +- `page.pdf({width: '10cm'})` - prints with width set to 10 centimeters. + +All possible units are: +- `px` - pixel +- `in` - inch +- `cm` - centimeter +- `mm` - millimeter + +The `format` options are: +- `Letter`: 8.5in x 11in +- `Legal`: 8.5in x 14in +- `Tabloid`: 11in x 17in +- `Ledger`: 17in x 11in +- `A0`: 33.1in x 46.8in +- `A1`: 23.4in x 33.1in +- `A2`: 16.54in x 23.4in +- `A3`: 11.7in x 16.54in +- `A4`: 8.27in x 11.7in +- `A5`: 5.83in x 8.27in +- `A6`: 4.13in x 5.83in + +> **NOTE** `headerTemplate` and `footerTemplate` markup have the following limitations: +> 1. Script tags inside templates are not evaluated. +> 2. Page styles are not visible inside templates. + #### page.reload([options]) - `options` <[Object]> Navigation parameters which might have the following properties: - `timeout` <[number]> Maximum navigation time in milliseconds, defaults to 30 seconds, pass `0` to disable timeout. The default value can be changed by using the [page.setDefaultNavigationTimeout(timeout)](#pagesetdefaultnavigationtimeouttimeout) or [page.setDefaultTimeout(timeout)](#pagesetdefaulttimeouttimeout) methods. @@ -2361,7 +2436,7 @@ Page is guaranteed to have a main frame which persists during navigations. #### page.select(selector, value, options) - `selector` <[string]> A selector to query frame for. -- `value` <[string]|[ElementHandle]|[Object]|[Array]<[string]>|[Array]<[ElementHandle]>|[Array]<[Object]>> Options to select. If the `` has the `multiple` attribute, all matching options are selected, otherwise only the first option matching one of the passed options is selected. String values are equivalent to `{value:'string'}`. Option is considered matching if all specified properties match. - `value` <[string]> Matches by `option.value`. - `label` <[string]> Matches by `option.label`. - `index` <[number]> Matches by the index. @@ -2964,7 +3039,7 @@ Contains the URL of the response. TimeoutError is emitted whenever certain operations are terminated due to timeout, e.g. [page.waitForSelector(selector[, options])](#pagewaitforselectorselector-options) or [playwright.launch([options])](#playwrightlaunchoptions). -### class: ChromiumAccessibility +### class: Accessibility The Accessibility class provides methods for inspecting Chromium's accessibility tree. The accessibility tree is used by assistive technology such as [screen readers](https://en.wikipedia.org/wiki/Screen_reader) or [switches](https://en.wikipedia.org/wiki/Switch_access). @@ -2975,7 +3050,7 @@ access to the Blink Accessibility Tree. Most of the accessibility tree gets filtered out when converting from Blink AX Tree to Platform-specific AX-Tree or by assistive technologies themselves. By default, Playwright tries to approximate this filtering, exposing only the "interesting" nodes of the tree. -#### chromiumAccessibility.snapshot([options]) +#### accessibility.snapshot([options]) - `options` <[Object]> - `interestingOnly` <[boolean]> Prune uninteresting nodes from the tree. Defaults to `true`. - `root` <[ElementHandle]> The root DOM element for the snapshot. Defaults to the whole page. @@ -3120,7 +3195,7 @@ await page.evaluate(() => window.open('https://www.example.com/')); const newWindowTarget = await browser.chromium.waitForTarget(target => target.url() === 'https://www.example.com/'); ``` -### class: ChromiumCoverage +### class: Coverage Coverage gathers information about parts of JavaScript and CSS that were used by the page. @@ -3154,12 +3229,12 @@ console.log(`Bytes used: ${usedBytes / totalBytes * 100}%`); _To output coverage in a form consumable by [Istanbul](https://github.com/istanbuljs), see [playwright-to-istanbul](https://github.com/istanbuljs/playwright-to-istanbul)._ -#### chromiumCoverage.startCSSCoverage([options]) +#### coverage.startCSSCoverage([options]) - `options` <[Object]> Set of configurable options for coverage - `resetOnNavigation` <[boolean]> Whether to reset coverage on every navigation. Defaults to `true`. - returns: <[Promise]> Promise that resolves when coverage is started -#### chromiumCoverage.startJSCoverage([options]) +#### coverage.startJSCoverage([options]) - `options` <[Object]> Set of configurable options for coverage - `resetOnNavigation` <[boolean]> Whether to reset coverage on every navigation. Defaults to `true`. - `reportAnonymousScripts` <[boolean]> Whether anonymous scripts generated by the page should be reported. Defaults to `false`. @@ -3167,7 +3242,7 @@ _To output coverage in a form consumable by [Istanbul](https://github.com/istanb > **NOTE** Anonymous scripts are ones that don't have an associated url. These are scripts that are dynamically created on the page using `eval` or `new Function`. If `reportAnonymousScripts` is set to `true`, anonymous scripts will have `__playwright_evaluation_script__` as their URL. -#### chromiumCoverage.stopCSSCoverage() +#### coverage.stopCSSCoverage() - returns: <[Promise]<[Array]<[Object]>>> Promise that resolves to the array of coverage reports for all stylesheets - `url` <[string]> StyleSheet URL - `text` <[string]> StyleSheet content @@ -3177,7 +3252,7 @@ _To output coverage in a form consumable by [Istanbul](https://github.com/istanb > **NOTE** CSS Coverage doesn't include dynamically injected style tags without sourceURLs. -#### chromiumCoverage.stopJSCoverage() +#### coverage.stopJSCoverage() - returns: <[Promise]<[Array]<[Object]>>> Promise that resolves to the array of coverage reports for all scripts - `url` <[string]> Script URL - `text` <[string]> Script content @@ -3347,89 +3422,6 @@ const browser = await playwright.launch({ - `pipe` <[boolean]> Connects to the browser over a pipe instead of a WebSocket. Defaults to `false`. - returns: <[Promise]<[BrowserServer]>> Promise which resolves to browser server instance. -### class: ChromiumPage -* extends: [Page] - -The ChromiumPage class represents a Chromium-specific extension of the page. - -#### chromiumPage.accessibility -- returns: <[Accessibility]> - -#### chromiumPage.coverage - -- returns: <[Coverage]> - -#### chromiumPage.interception -- returns: <[Interception]> - -#### chromiumPage.pdf([options]) -- `options` <[Object]> Options object which might have the following properties: - - `path` <[string]> The file path to save the PDF to. If `path` is a relative path, then it is resolved relative to [current working directory](https://nodejs.org/api/process.html#process_process_cwd). If no path is provided, the PDF won't be saved to the disk. - - `scale` <[number]> Scale of the webpage rendering. Defaults to `1`. Scale amount must be between 0.1 and 2. - - `displayHeaderFooter` <[boolean]> Display header and footer. Defaults to `false`. - - `headerTemplate` <[string]> HTML template for the print header. Should be valid HTML markup with following classes used to inject printing values into them: - - `'date'` formatted print date - - `'title'` document title - - `'url'` document location - - `'pageNumber'` current page number - - `'totalPages'` total pages in the document - - `footerTemplate` <[string]> HTML template for the print footer. Should use the same format as the `headerTemplate`. - - `printBackground` <[boolean]> Print background graphics. Defaults to `false`. - - `landscape` <[boolean]> Paper orientation. Defaults to `false`. - - `pageRanges` <[string]> Paper ranges to print, e.g., '1-5, 8, 11-13'. Defaults to the empty string, which means print all pages. - - `format` <[string]> Paper format. If set, takes priority over `width` or `height` options. Defaults to 'Letter'. - - `width` <[string]|[number]> Paper width, accepts values labeled with units. - - `height` <[string]|[number]> Paper height, accepts values labeled with units. - - `margin` <[Object]> Paper margins, defaults to none. - - `top` <[string]|[number]> Top margin, accepts values labeled with units. - - `right` <[string]|[number]> Right margin, accepts values labeled with units. - - `bottom` <[string]|[number]> Bottom margin, accepts values labeled with units. - - `left` <[string]|[number]> Left margin, accepts values labeled with units. - - `preferCSSPageSize` <[boolean]> Give any CSS `@page` size declared in the page priority over what is declared in `width` and `height` or `format` options. Defaults to `false`, which will scale the content to fit the paper size. -- returns: <[Promise]<[Buffer]>> Promise which resolves with PDF buffer. - -> **NOTE** Generating a pdf is currently only supported in Chrome headless. - -`page.pdf()` generates a pdf of the page with `print` css media. To generate a pdf with `screen` media, call [page.emulateMedia({ type: 'screen' })](#pageemulatemedia) before calling `page.pdf()`: - -> **NOTE** By default, `page.pdf()` generates a pdf with modified colors for printing. Use the [`-webkit-print-color-adjust`](https://developer.mozilla.org/en-US/docs/Web/CSS/-webkit-print-color-adjust) property to force rendering of exact colors. - -```js -// Generates a PDF with 'screen' media type. -await page.emulateMedia({type: 'screen'}); -await page.pdf({path: 'page.pdf'}); -``` - -The `width`, `height`, and `margin` options accept values labeled with units. Unlabeled values are treated as pixels. - -A few examples: -- `page.pdf({width: 100})` - prints with width set to 100 pixels -- `page.pdf({width: '100px'})` - prints with width set to 100 pixels -- `page.pdf({width: '10cm'})` - prints with width set to 10 centimeters. - -All possible units are: -- `px` - pixel -- `in` - inch -- `cm` - centimeter -- `mm` - millimeter - -The `format` options are: -- `Letter`: 8.5in x 11in -- `Legal`: 8.5in x 14in -- `Tabloid`: 11in x 17in -- `Ledger`: 17in x 11in -- `A0`: 33.1in x 46.8in -- `A1`: 23.4in x 33.1in -- `A2`: 16.54in x 23.4in -- `A3`: 11.7in x 16.54in -- `A4`: 8.27in x 11.7in -- `A5`: 5.83in x 8.27in -- `A6`: 4.13in x 5.83in - -> **NOTE** `headerTemplate` and `footerTemplate` markup have the following limitations: -> 1. Script tags inside templates are not evaluated. -> 2. Page styles are not visible inside templates. - ### class: ChromiumSession * extends: [EventEmitter](https://nodejs.org/api/events.html#events_class_eventemitter) @@ -3495,7 +3487,7 @@ Identifies what kind of target this is. Can be `"page"`, [`"background_page"`](h #### chromiumTarget.url() - returns: <[string]> -### class: ChromiumWorker +### class: Worker The Worker class represents a [WebWorker](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API). The events `workercreated` and `workerdestroyed` are emitted on the page object to signal the worker lifecycle. @@ -3509,7 +3501,7 @@ for (const worker of page.workers()) console.log(' ' + worker.url()); ``` -#### chromiumWorker.evaluate(pageFunction[, ...args]) +#### worker.evaluate(pageFunction[, ...args]) - `pageFunction` <[function]|[string]> Function to be evaluated in the worker context - `...args` <...[Serializable]|[JSHandle]> Arguments to pass to `pageFunction` - returns: <[Promise]<[Serializable]>> Promise which resolves to the return value of `pageFunction` @@ -3518,7 +3510,7 @@ If the function passed to the `worker.evaluate` returns a [Promise], then `worke If the function passed to the `worker.evaluate` returns a non-[Serializable] value, then `worker.evaluate` resolves to `undefined`. DevTools Protocol also supports transferring some additional values that are not serializable by `JSON`: `-0`, `NaN`, `Infinity`, `-Infinity`, and bigint literals. -#### chromiumWorker.evaluateHandle(pageFunction[, ...args]) +#### worker.evaluateHandle(pageFunction[, ...args]) - `pageFunction` <[function]|[string]> Function to be evaluated in the page context - `...args` <...[Serializable]|[JSHandle]> Arguments to pass to `pageFunction` - returns: <[Promise]<[JSHandle]>> Promise which resolves to the return value of `pageFunction` as in-page object (JSHandle) @@ -3527,7 +3519,7 @@ The only difference between `worker.evaluate` and `worker.evaluateHandle` is tha If the function passed to the `worker.evaluateHandle` returns a [Promise], then `worker.evaluateHandle` would wait for the promise to resolve and return its value. -#### chromiumWorker.url() +#### worker.url() - returns: <[string]> ### class: FirefoxBrowser diff --git a/src/api.ts b/src/api.ts index 814327d090..3b8d06cba5 100644 --- a/src/api.ts +++ b/src/api.ts @@ -14,6 +14,7 @@ * limitations under the License. */ +export { Accessibility } from './accessibility'; export { Browser, BrowserServer } from './browser'; export { BrowserContext } from './browserContext'; export { BrowserFetcher } from './browserFetcher'; @@ -25,8 +26,7 @@ export { Frame } from './frames'; export { Keyboard, Mouse } from './input'; export { JSHandle } from './javascript'; export { Request, Response } from './network'; -export { Page, FileChooser } from './page'; -export { Accessibility } from './accessibility'; +export { Coverage, FileChooser, Page, Worker } from './page'; export * from './chromium/crApi'; export * from './firefox/ffApi'; diff --git a/src/chromium/crApi.ts b/src/chromium/crApi.ts index 9f6c79048b..abf5110ecb 100644 --- a/src/chromium/crApi.ts +++ b/src/chromium/crApi.ts @@ -16,7 +16,5 @@ export { CRBrowser as ChromiumBrowser } from './crBrowser'; export { CRSession as ChromiumSession } from './crConnection'; -export { ChromiumPage } from './crPage'; export { CRPlaywright as ChromiumPlaywright } from './crPlaywright'; export { CRTarget as ChromiumTarget } from './crTarget'; -export { CRCoverage as ChromiumCoverage } from './crCoverage'; diff --git a/src/chromium/crCoverage.ts b/src/chromium/crCoverage.ts index 411d58a98e..2a97a6998f 100644 --- a/src/chromium/crCoverage.ts +++ b/src/chromium/crCoverage.ts @@ -20,6 +20,7 @@ import { assert, debugError, helper, RegisteredListener } from '../helper'; import { Protocol } from './protocol'; import { EVALUATION_SCRIPT_URL } from './crExecutionContext'; +import { Coverage } from '../page'; type CoverageEntry = { url: string, @@ -27,11 +28,12 @@ type CoverageEntry = { ranges : {start: number, end: number}[] }; -export class CRCoverage { +export class CRCoverage extends Coverage { private _jsCoverage: JSCoverage; private _cssCoverage: CSSCoverage; constructor(client: CRSession) { + super(); this._jsCoverage = new JSCoverage(client); this._cssCoverage = new CSSCoverage(client); } diff --git a/src/chromium/crPage.ts b/src/chromium/crPage.ts index 0ad37f3967..89cdb01dc0 100644 --- a/src/chromium/crPage.ts +++ b/src/chromium/crPage.ts @@ -22,7 +22,7 @@ import * as network from '../network'; import { CRSession } from './crConnection'; import { EVALUATION_SCRIPT_URL, CRExecutionContext } from './crExecutionContext'; import { CRNetworkManager } from './crNetworkManager'; -import { Page } from '../page'; +import { Page, Coverage } from '../page'; import { Protocol } from './protocol'; import { Events } from '../events'; import { toConsoleMessageLocation, exceptionToError, releaseObject } from './crProtocolHelper'; @@ -31,7 +31,7 @@ import { PageDelegate } from '../page'; import { RawMouseImpl, RawKeyboardImpl } from './crInput'; import { getAccessibilityTree } from './crAccessibility'; import { CRCoverage } from './crCoverage'; -import { CRPDF, PDFOptions } from './crPdf'; +import { CRPDF } from './crPdf'; import { CRWorkers } from './crWorkers'; import { CRBrowser } from './crBrowser'; import { BrowserContext } from '../browserContext'; @@ -44,7 +44,7 @@ const UTILITY_WORLD_NAME = '__playwright_utility_world__'; export class CRPage implements PageDelegate { _client: CRSession; - private readonly _page: ChromiumPage; + private readonly _page: Page; readonly _networkManager: CRNetworkManager; private _workers: CRWorkers; private _contextIdToContext = new Map(); @@ -53,13 +53,17 @@ export class CRPage implements PageDelegate { rawMouse: RawMouseImpl; rawKeyboard: RawKeyboardImpl; private _browser: CRBrowser; + private _pdf: CRPDF; + private _coverage: CRCoverage; constructor(client: CRSession, browser: CRBrowser, browserContext: BrowserContext) { this._client = client; this._browser = browser; this.rawKeyboard = new RawKeyboardImpl(client); this.rawMouse = new RawMouseImpl(client); - this._page = new ChromiumPage(client, this, browserContext); + this._pdf = new CRPDF(client); + this._coverage = new CRCoverage(client); + this._page = new Page(this, browserContext); this._networkManager = new CRNetworkManager(client, this._page); this._workers = new CRWorkers(client, this._page); @@ -481,20 +485,13 @@ export class CRPage implements PageDelegate { async getAccessibilityTree(): Promise { return getAccessibilityTree(this._client); } -} -export class ChromiumPage extends Page { - readonly coverage: CRCoverage; - private _pdf: CRPDF; - - constructor(client: CRSession, delegate: CRPage, browserContext: BrowserContext) { - super(delegate, browserContext); - this.coverage = new CRCoverage(client); - this._pdf = new CRPDF(client); + async pdf(options?: types.PDFOptions): Promise { + return this._pdf.generate(options); } - async pdf(options?: PDFOptions): Promise { - return this._pdf.generate(options); + coverage(): Coverage | undefined { + return this._coverage; } } diff --git a/src/chromium/crPdf.ts b/src/chromium/crPdf.ts index 11ab2a4e47..daab7f199e 100644 --- a/src/chromium/crPdf.ts +++ b/src/chromium/crPdf.ts @@ -17,25 +17,10 @@ import { assert, helper } from '../helper'; import * as platform from '../platform'; +import * as types from '../types'; import { CRSession } from './crConnection'; import { readProtocolStream } from './crProtocolHelper'; -export type PDFOptions = { - scale?: number, - displayHeaderFooter?: boolean, - headerTemplate?: string, - footerTemplate?: string, - printBackground?: boolean, - landscape?: boolean, - pageRanges?: string, - format?: string, - width?: string|number, - height?: string|number, - preferCSSPageSize?: boolean, - margin?: {top?: string|number, bottom?: string|number, left?: string|number, right?: string|number}, - path?: string, -} - const PagePaperFormats: { [key: string]: { width: number, height: number }} = { letter: {width: 8.5, height: 11}, legal: {width: 8.5, height: 14}, @@ -92,7 +77,7 @@ export class CRPDF { this._client = client; } - async generate(options: PDFOptions = {}): Promise { + async generate(options: types.PDFOptions = {}): Promise { const { scale = 1, displayHeaderFooter = false, diff --git a/src/chromium/crWorkers.ts b/src/chromium/crWorkers.ts index e5c63c79d6..7af956edae 100644 --- a/src/chromium/crWorkers.ts +++ b/src/chromium/crWorkers.ts @@ -17,14 +17,13 @@ import { Events } from '../events'; import { debugError } from '../helper'; -import { Worker } from '../page'; +import { Page, Worker } from '../page'; import { CRConnection, CRSession } from './crConnection'; import { CRExecutionContext } from './crExecutionContext'; -import { ChromiumPage } from './crPage'; import { exceptionToError, toConsoleMessageLocation } from './crProtocolHelper'; export class CRWorkers { - constructor(client: CRSession, page: ChromiumPage) { + constructor(client: CRSession, page: Page) { client.on('Target.attachedToTarget', event => { if (event.targetInfo.type !== 'worker') return; diff --git a/src/firefox/ffPage.ts b/src/firefox/ffPage.ts index f009db4353..86cf6a0c16 100644 --- a/src/firefox/ffPage.ts +++ b/src/firefox/ffPage.ts @@ -20,7 +20,7 @@ import { assert, helper, RegisteredListener, debugError } from '../helper'; import * as dom from '../dom'; import { FFSession } from './ffConnection'; import { FFExecutionContext } from './ffExecutionContext'; -import { Page, PageDelegate } from '../page'; +import { Page, PageDelegate, Coverage } from '../page'; import { FFNetworkManager } from './ffNetworkManager'; import { Events } from '../events'; import * as dialog from '../dialog'; @@ -349,6 +349,10 @@ export class FFPage implements PageDelegate { async getAccessibilityTree() : Promise { return getAccessibilityTree(this._session); } + + coverage(): Coverage | undefined { + return undefined; + } } export function normalizeWaitUntil(waitUntil: frames.LifecycleEvent | frames.LifecycleEvent[]): frames.LifecycleEvent[] { diff --git a/src/page.ts b/src/page.ts index 99dd48be1d..e5eba7d8b0 100644 --- a/src/page.ts +++ b/src/page.ts @@ -69,6 +69,8 @@ export interface PageDelegate { getBoundingBox(handle: dom.ElementHandle): Promise; getAccessibilityTree(): Promise; + pdf?: (options?: types.PDFOptions) => Promise; + coverage(): Coverage | undefined; } type PageState = { @@ -105,6 +107,8 @@ export class Page extends platform.EventEmitter { readonly _frameManager: frames.FrameManager; readonly accessibility: accessibility.Accessibility; private _workers = new Map(); + readonly pdf: ((options?: types.PDFOptions) => Promise) | undefined; + readonly coverage: Coverage | undefined; constructor(delegate: PageDelegate, browserContext: BrowserContext) { super(); @@ -128,6 +132,9 @@ export class Page extends platform.EventEmitter { this._timeoutSettings = new TimeoutSettings(); this._screenshotter = new Screenshotter(this); this._frameManager = new frames.FrameManager(this); + if (delegate.pdf) + this.pdf = delegate.pdf.bind(delegate); + this.coverage = delegate.coverage(); } _didClose() { @@ -546,3 +553,24 @@ export class Worker { return (await this._executionContextPromise).evaluateHandle(pageFunction, ...args as any); } } + +export class Coverage { + startJSCoverage(options: { + resetOnNavigation?: boolean; + reportAnonymousScripts?: boolean; + }): Promise { + throw new Error('not implemented'); + } + + stopJSCoverage(): Promise { + throw new Error('not implemented'); + } + + startCSSCoverage(options: { resetOnNavigation?: boolean; } = {}): Promise { + throw new Error('not implemented'); + } + + stopCSSCoverage(): Promise { + throw new Error('not implemented'); + } +} diff --git a/src/platform.ts b/src/platform.ts index 401652dd86..c3f4b12614 100644 --- a/src/platform.ts +++ b/src/platform.ts @@ -158,7 +158,7 @@ export const Buffer: typeof nodeBuffer.Buffer = isNode ? nodeBuffer.Buffer : ( } } ) as any as typeof nodeBuffer.Buffer; -export type BufferType = NodeBuffer; +export type BufferType = Buffer; function assertFileAccess() { assert(isNode, 'Working with filesystem using "path" is only supported in Node.js'); diff --git a/src/types.ts b/src/types.ts index 1ead5a50fc..9b77ff0108 100644 --- a/src/types.ts +++ b/src/types.ts @@ -99,3 +99,25 @@ export type DeviceDescriptor = { viewport: Viewport, }; export type Devices = { [name: string]: DeviceDescriptor } & DeviceDescriptor[]; + +export type PDFOptions = { + scale?: number, + displayHeaderFooter?: boolean, + headerTemplate?: string, + footerTemplate?: string, + printBackground?: boolean, + landscape?: boolean, + pageRanges?: string, + format?: string, + width?: string|number, + height?: string|number, + preferCSSPageSize?: boolean, + margin?: {top?: string|number, bottom?: string|number, left?: string|number, right?: string|number}, + path?: string, +} + +export type CoverageEntry = { + url: string, + text: string, + ranges : {start: number, end: number}[] +}; diff --git a/src/webkit/wkBrowser.ts b/src/webkit/wkBrowser.ts index 92da4f154f..9afd169199 100644 --- a/src/webkit/wkBrowser.ts +++ b/src/webkit/wkBrowser.ts @@ -17,7 +17,7 @@ import * as browser from '../browser'; import { BrowserContext, BrowserContextOptions } from '../browserContext'; -import { assert, debugError, helper, RegisteredListener } from '../helper'; +import { assert, helper, RegisteredListener } from '../helper'; import * as network from '../network'; import { Page } from '../page'; import { ConnectionTransport } from '../transport'; diff --git a/src/webkit/wkPage.ts b/src/webkit/wkPage.ts index cee6f88306..d7b044af09 100644 --- a/src/webkit/wkPage.ts +++ b/src/webkit/wkPage.ts @@ -24,7 +24,7 @@ import { Events } from '../events'; import { WKExecutionContext, EVALUATION_SCRIPT_URL } from './wkExecutionContext'; import { WKNetworkManager } from './wkNetworkManager'; import { WKWorkers } from './wkWorkers'; -import { Page, PageDelegate } from '../page'; +import { Page, PageDelegate, Coverage } from '../page'; import { Protocol } from './protocol'; import * as dialog from '../dialog'; import { WKBrowser } from './wkBrowser'; @@ -485,6 +485,10 @@ export class WKPage implements PageDelegate { async getAccessibilityTree() : Promise { return getAccessibilityTree(this._session); } + + coverage(): Coverage | undefined { + return undefined; + } } function toRemoteObject(handle: dom.ElementHandle): Protocol.Runtime.RemoteObject {