diff --git a/docs/src/api/class-browser.md b/docs/src/api/class-browser.md index 43782ab0d3..a26f1ee0ac 100644 --- a/docs/src/api/class-browser.md +++ b/docs/src/api/class-browser.md @@ -1,10 +1,7 @@ # class: Browser * extends: [EventEmitter](https://nodejs.org/api/events.html#events_class_eventemitter) -A Browser is created when Playwright connects to a browser instance, either through [`method: BrowserType.launch`] or -[`method: BrowserType.connect`]. - -An example of using a [Browser] to create a [Page]: +A Browser is created via [`method: BrowserType.launch`]. An example of using a [Browser] to create a [Page]: ```js const { firefox } = require('playwright'); // Or 'chromium' or 'webkit'. @@ -17,9 +14,8 @@ const { firefox } = require('playwright'); // Or 'chromium' or 'webkit'. })(); ``` -See [ChromiumBrowser], [FirefoxBrowser] and [WebKitBrowser] for browser-specific features. Note that [`method: -BrowserType.connect`] and [`method: BrowserType.launch`] always return a specific browser instance, based on the -browser being connected to or launched. +See [ChromiumBrowser], [FirefoxBrowser] and [WebKitBrowser] for browser-specific features. Note that +[`method: BrowserType.launch`] always returns a specific browser instance, based on the browser being launched. ## event: Browser.disconnected @@ -32,7 +28,7 @@ Emitted when Browser gets disconnected from the browser application. This might In case this browser is obtained using [`method: BrowserType.launch`], closes the browser and all of its pages (if any were opened). -In case this browser is obtained using [`method: BrowserType.connect`], clears all created contexts belonging to this +In case this browser is connected to, clears all created contexts belonging to this browser and disconnects from the browser server. The [Browser] object itself is considered to be disposed and cannot be used anymore. diff --git a/docs/src/api/class-browsercontext.md b/docs/src/api/class-browsercontext.md index faf7eb2eef..29da8d1dd1 100644 --- a/docs/src/api/class-browsercontext.md +++ b/docs/src/api/class-browsercontext.md @@ -95,6 +95,7 @@ await browserContext.addInitScript({ [`method: Page.addInitScript`] is not defined. ### param: BrowserContext.addInitScript.script +* langs: js - `script` <[function]|[string]|[Object]> - `path` <[path]> Path to the JavaScript file. If `path` is a relative path, then it is resolved relative to the current working directory. Optional. - `content` <[string]> Raw script content. Optional. @@ -102,6 +103,7 @@ await browserContext.addInitScript({ Script to be evaluated in all pages in the browser context. ### param: BrowserContext.addInitScript.arg +* langs: js - `arg` <[Serializable]> Optional argument to pass to [`param: script`] (only supported when passing a function). diff --git a/docs/src/api/class-browserserver.md b/docs/src/api/class-browserserver.md index e15f4cd6b8..646f08f636 100644 --- a/docs/src/api/class-browserserver.md +++ b/docs/src/api/class-browserserver.md @@ -1,4 +1,5 @@ # class: BrowserServer +* langs: js ## event: BrowserServer.close diff --git a/docs/src/api/class-browsertype.md b/docs/src/api/class-browsertype.md index 474db30508..ec3f6aea6d 100644 --- a/docs/src/api/class-browsertype.md +++ b/docs/src/api/class-browsertype.md @@ -16,6 +16,7 @@ const { chromium } = require('playwright'); // Or 'firefox' or 'webkit'. ``` ## async method: BrowserType.connect +* langs: js - returns: <[Browser]> This methods attaches Playwright to an existing browser instance. @@ -129,6 +130,7 @@ Close the browser process on SIGTERM. Defaults to `true`. Close the browser process on SIGHUP. Defaults to `true`. ### option: BrowserType.launch.logger +* langs: js - `logger` <[Logger]> Logger sink for Playwright logging. @@ -258,6 +260,7 @@ Defaults to 0. ### option: BrowserType.launchPersistentContext.-inline- = %%-shared-context-params-list-%% ## async method: BrowserType.launchServer +* langs: js - returns: <[BrowserServer]> Returns the browser app instance. @@ -352,6 +355,7 @@ Close the browser process on SIGTERM. Defaults to `true`. Close the browser process on SIGHUP. Defaults to `true`. ### option: BrowserType.launchServer.logger +* langs: js - `logger` <[Logger]> Logger sink for Playwright logging. diff --git a/docs/src/api/class-chromiumbrowser.md b/docs/src/api/class-chromiumbrowser.md index 4ead8640fe..c877552a9f 100644 --- a/docs/src/api/class-chromiumbrowser.md +++ b/docs/src/api/class-chromiumbrowser.md @@ -1,5 +1,6 @@ # class: ChromiumBrowser * extends: [Browser] +* langs: js Chromium-specific features including Tracing, service worker support, etc. You can use [`method: ChromiumBrowser.startTracing`] and [`method: ChromiumBrowser.stopTracing`] to create a trace file which can be diff --git a/docs/src/api/class-chromiumcoverage.md b/docs/src/api/class-chromiumcoverage.md index d6511d05de..10430bfbf0 100644 --- a/docs/src/api/class-chromiumcoverage.md +++ b/docs/src/api/class-chromiumcoverage.md @@ -1,4 +1,5 @@ # class: ChromiumCoverage +* langs: js Coverage gathers information about parts of JavaScript and CSS that were used by the page. diff --git a/docs/src/api/class-download.md b/docs/src/api/class-download.md index 8173901031..e59e7651b2 100644 --- a/docs/src/api/class-download.md +++ b/docs/src/api/class-download.md @@ -22,6 +22,7 @@ downloaded content. If `acceptDownloads` is not set or set to `false`, download download is not performed and user has no access to the downloaded files. ## async method: Download.createReadStream +* langs: js - returns: <[null]|[Readable]> Returns readable stream for current download or `null` if download failed. diff --git a/docs/src/api/class-elementhandle.md b/docs/src/api/class-elementhandle.md index 6339be9180..412e56c303 100644 --- a/docs/src/api/class-elementhandle.md +++ b/docs/src/api/class-elementhandle.md @@ -424,18 +424,8 @@ handle.selectOption('red', 'green', 'blue'); handle.selectOption({ value: 'blue' }, { index: 2 }, 'red'); ``` -### param: ElementHandle.selectOption.values -- `values` <[null]|[string]|[ElementHandle]|[Array]<[string]>|[Object]|[Array]<[ElementHandle]>|[Array]<[Object]>> - - `value` <[string]> Matches by `option.value`. Optional. - - `label` <[string]> Matches by `option.label`. Optional. - - `index` <[int]> Matches by the index. Optional. - -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. - +### param: Frame.selectOption.values = %%-select-options-values-%% ### option: Frame.selectOption.noWaitAfter = %%-input-no-wait-after-%% - ### option: Frame.selectOption.timeout = %%-input-timeout-%% ## async method: Frame.setContent diff --git a/docs/src/api/class-logger.md b/docs/src/api/class-logger.md index d3ed209e14..b6b3a03f8b 100644 --- a/docs/src/api/class-logger.md +++ b/docs/src/api/class-logger.md @@ -1,4 +1,5 @@ # class: Logger +* langs: js Playwright generates a lot of logs and they are accessible via the pluggable logger sink. diff --git a/docs/src/api/class-page.md b/docs/src/api/class-page.md index 601804c026..5c012e2b00 100644 --- a/docs/src/api/class-page.md +++ b/docs/src/api/class-page.md @@ -315,6 +315,7 @@ await page.addInitScript(preloadFile); [`method: Page.addInitScript`] is not defined. ### param: Page.addInitScript.script +* langs: js - `script` <[function]|[string]|[Object]> - `path` <[path]> Path to the JavaScript file. If `path` is a relative path, then it is resolved relative to the current working directory. Optional. - `content` <[string]> Raw script content. Optional. @@ -322,6 +323,7 @@ await page.addInitScript(preloadFile); Script to be evaluated in the page. ### param: Page.addInitScript.arg +* langs: js - `arg` <[Serializable]> Optional argument to pass to [`param: script`] (only supported when passing a function). @@ -443,6 +445,7 @@ Gets the full HTML contents of the page, including the doctype. Get the browser context that the page belongs to. ## property: Page.coverage +* langs: js - type: <[null]|[ChromiumCoverage]> Browser-specific Coverage implementation, only available for Chromium atm. See @@ -1285,19 +1288,8 @@ page.selectOption('select#colors', ['red', 'green', 'blue']); Shortcut for main frame's [`method: Frame.selectOption`] ### param: Page.selectOption.selector = %%-input-selector-%% - -### param: Page.selectOption.values -- `values` <[null]|[string]|[ElementHandle]|[Array]<[string]>|[Object]|[Array]<[ElementHandle]>|[Array]<[Object]>> - - `value` <[string]> Matches by `option.value`. Optional. - - `label` <[string]> Matches by `option.label`. Optional. - - `index` <[int]> Matches by the index. Optional. - -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. + +## python-select-options-element +* langs: python +- `element` <[ElementHandle]|[Array]<[ElementHandle]>> + +Option elements to select. Optional. + +## python-select-options-index +* langs: python +- `index` <[int]|[Array]<[int]>> + +Options to select by index. Optional. + +## python-select-options-value +* langs: python +- `value` <[string]|[Array]<[string]>> + +Options to select by value. If the `` has the `multiple` attribute, all given options are selected, otherwise +only the first option matching one of the passed options is selected. Optional. + + ## shared-context-params-list - %%-context-option-acceptdownloads-%% - %%-context-option-ignorehttpserrors-%% diff --git a/docs/src/api/python.md b/docs/src/api/python.md new file mode 100644 index 0000000000..01cff4439f --- /dev/null +++ b/docs/src/api/python.md @@ -0,0 +1,58 @@ +## async method: Playwright.stop +* langs: python + +Terminates this instance of Playwright in case it was created bypassing the Python context manager. This is useful in REPL applications. + +```py +>>> from playwright import sync_playwright + +>>> playwright = sync_playwright().start() + +>>> browser = playwright.chromium.launch() +>>> page = browser.newPage() +>>> page.goto("http://whatsmyuseragent.org/") +>>> page.screenshot(path="example.png") +>>> browser.close() + +>>> playwright.stop() +``` + +### param: BrowserContext.addInitScript.path +* langs: python +- `path` <[path]> + +Path to the JavaScript file. If `path` is a relative path, then it is resolved relative to the current working directory. Optional. + + +### param: BrowserContext.addInitScript.script +* langs: python +- `script` <[string]> + +Script to be evaluated in all pages in the browser context. Optional. + +### param: Page.addInitScript.path +* langs: python +- `path` <[path]> + +Path to the JavaScript file. If `path` is a relative path, then it is resolved relative to the current working directory. Optional. + +### param: Page.addInitScript.script +* langs: python +- `script` <[string]> + +Script to be evaluated in all pages in the browser context. Optional. + +### param: ElementHandle.selectOption.element = %%-python-select-options-element-%% +### param: ElementHandle.selectOption.index = %%-python-select-options-index-%% +### param: ElementHandle.selectOption.value = %%-python-select-options-value-%% +### param: ElementHandle.selectOption.label = %%-python-select-options-label-%% + +### param: Frame.selectOption.element = %%-python-select-options-element-%% +### param: Frame.selectOption.index = %%-python-select-options-index-%% +### param: Frame.selectOption.value = %%-python-select-options-value-%% +### param: Frame.selectOption.label = %%-python-select-options-label-%% + +### param: Page.selectOption.element = %%-python-select-options-element-%% +### param: Page.selectOption.index = %%-python-select-options-index-%% +### param: Page.selectOption.value = %%-python-select-options-value-%% +### param: Page.selectOption.label = %%-python-select-options-label-%% diff --git a/types/types.d.ts b/types/types.d.ts index 804850d996..2e170b5129 100644 --- a/types/types.d.ts +++ b/types/types.d.ts @@ -6884,11 +6884,9 @@ export {}; /** * - extends: [EventEmitter](https://nodejs.org/api/events.html#events_class_eventemitter) * - * A Browser is created when Playwright connects to a browser instance, either through - * [browserType.launch(…)](https://github.com/microsoft/playwright/blob/master/docs/api.md#browsertypelaunch) or - * [browserType.connect(…)](https://github.com/microsoft/playwright/blob/master/docs/api.md#browsertypeconnect). - * - * An example of using a [Browser] to create a [Page]: + * A Browser is created via + * [browserType.launch(…)](https://github.com/microsoft/playwright/blob/master/docs/api.md#browsertypelaunch). An example + * of using a [Browser] to create a [Page]: * * ```js * const { firefox } = require('playwright'); // Or 'chromium' or 'webkit'. @@ -6902,9 +6900,8 @@ export {}; * ``` * * See [ChromiumBrowser], [FirefoxBrowser] and [WebKitBrowser] for browser-specific features. Note that - * [browserType.connect(…)](https://github.com/microsoft/playwright/blob/master/docs/api.md#browsertypeconnect) and - * [browserType.launch(…)](https://github.com/microsoft/playwright/blob/master/docs/api.md#browsertypelaunch) always return - * a specific browser instance, based on the browser being connected to or launched. + * [browserType.launch(…)](https://github.com/microsoft/playwright/blob/master/docs/api.md#browsertypelaunch) always + * returns a specific browser instance, based on the browser being launched. */ export interface Browser extends EventEmitter { /** @@ -6952,9 +6949,8 @@ export interface Browser extends EventEmitter { * [browserType.launch(…)](https://github.com/microsoft/playwright/blob/master/docs/api.md#browsertypelaunch), closes the * browser and all of its pages (if any were opened). * - * In case this browser is obtained using - * [browserType.connect(…)](https://github.com/microsoft/playwright/blob/master/docs/api.md#browsertypeconnect), clears all - * created contexts belonging to this browser and disconnects from the browser server. + * In case this browser is connected to, clears all created contexts belonging to this browser and disconnects from the + * browser server. * * The [Browser] object itself is considered to be disposed and cannot be used anymore. */ diff --git a/utils/doclint/api_parser.js b/utils/doclint/api_parser.js index e1478a35ba..184479d371 100644 --- a/utils/doclint/api_parser.js +++ b/utils/doclint/api_parser.js @@ -31,10 +31,10 @@ class ApiParser { let bodyParts = []; let paramsPath; for (const name of fs.readdirSync(apiDir)) { - if (name.startsWith('class-')) - bodyParts.push(fs.readFileSync(path.join(apiDir, name)).toString()); if (name === 'params.md') paramsPath = path.join(apiDir, name); + else + bodyParts.push(fs.readFileSync(path.join(apiDir, name)).toString()); } const body = md.parse(bodyParts.join('\n')); const params = paramsPath ? md.parse(fs.readFileSync(paramsPath).toString()) : null; @@ -58,21 +58,16 @@ class ApiParser { */ parseClass(node) { let extendsName = null; - let langs = null; const name = node.text.substring('class: '.length); for (const member of node.children) { if (member.type.startsWith('h')) continue; - if (member.type === 'li' && member.text.startsWith('extends: [')) { + if (member.type === 'li' && member.liType === 'bullet' && member.text.startsWith('extends: [')) { extendsName = member.text.substring('extends: ['.length, member.text.indexOf(']')); continue; } - if (member.type === 'li' && member.text.startsWith('langs: ')) { - langs = new Set(member.text.substring('langs: '.length).split(',').map(l => l.trim())); - continue; - } } - const clazz = new Documentation.Class(langs, name, [], extendsName, extractComments(node)); + const clazz = new Documentation.Class(extractLangs(node), name, [], extendsName, extractComments(node)); this.classes.set(clazz.name, clazz); } @@ -84,13 +79,9 @@ class ApiParser { const match = spec.text.match(/(event|method|property|async method): ([^.]+)\.(.*)/); const name = match[3]; let returnType = null; - let langs = null; - for (const item of spec.children || []) { if (item.type === 'li' && item.liType === 'default') returnType = this.parseType(item); - if (item.type === 'li' && item.liType === 'bullet' && item.text.startsWith('langs: ')) - langs = new Set(item.text.substring('langs: '.length).split(',').map(l => l.trim())); } if (!returnType) returnType = new Documentation.Type('void'); @@ -103,11 +94,11 @@ class ApiParser { let member; if (match[1] === 'event') - member = Documentation.Member.createEvent(langs, name, returnType, extractComments(spec)); + member = Documentation.Member.createEvent(extractLangs(spec), name, returnType, extractComments(spec)); if (match[1] === 'property') - member = Documentation.Member.createProperty(langs, name, returnType, extractComments(spec)); + member = Documentation.Member.createProperty(extractLangs(spec), name, returnType, extractComments(spec)); if (match[1] === 'method' || match[1] === 'async method') - member = Documentation.Member.createMethod(langs, name, [], returnType, extractComments(spec)); + member = Documentation.Member.createMethod(extractLangs(spec), name, [], returnType, extractComments(spec)); const clazz = this.classes.get(match[2]); clazz.membersArray.push(member); } @@ -138,11 +129,11 @@ class ApiParser { * @param {MarkdownNode} spec */ parseProperty(spec) { - const param = spec.children[0]; + const param = childrenWithoutProperties(spec)[0]; const text = param.text; const name = text.substring(0, text.indexOf('<')).replace(/\`/g, '').trim(); const comments = extractComments(spec); - return Documentation.Member.createProperty(null, name, this.parseType(param), comments, guessRequired(md.render(comments))); + return Documentation.Member.createProperty(extractLangs(spec), name, this.parseType(param), comments, guessRequired(md.render(comments))); } /** @@ -150,10 +141,10 @@ class ApiParser { * @return {Documentation.Type} */ parseType(spec) { - const arg = parseArgument(spec.text); + const arg = parseVariable(spec.text); const properties = []; for (const child of spec.children || []) { - const { name, text } = parseArgument(child.text); + const { name, text } = parseVariable(child.text); const comments = /** @type {MarkdownNode[]} */ ([{ type: 'text', text }]); properties.push(Documentation.Member.createProperty(null, name, this.parseType(child), comments, guessRequired(text))); } @@ -165,7 +156,7 @@ class ApiParser { * @param {string} line * @returns {{ name: string, type: string, text: string }} */ -function parseArgument(line) { +function parseVariable(line) { let match = line.match(/^`([^`]+)` (.*)/); if (!match) match = line.match(/^(returns): (.*)/); @@ -209,7 +200,8 @@ function applyTemplates(body, params) { const template = paramsMap.get(prop.text); if (!template) throw new Error('Bad template: ' + prop.text); - const { name: argName } = parseArgument(template.children[0].text); + const children = childrenWithoutProperties(template); + const { name: argName } = parseVariable(children[0].text); parent.children.push({ type: node.type, text: name + argName, @@ -281,4 +273,23 @@ function parseApi(apiDir) { return new ApiParser(apiDir).documentation; } +/** + * @param {MarkdownNode} spec + * @returns {?Set} + */ +function extractLangs(spec) { + for (const child of spec.children) + if (child.type === 'li' && child.liType === 'bullet' && child.text.startsWith('langs: ')) + return new Set(child.text.substring('langs: '.length).split(',').map(l => l.trim())); + return null; +} + +/** + * @param {MarkdownNode} spec + * @returns {MarkdownNode[]} + */ +function childrenWithoutProperties(spec) { + return spec.children.filter(c => c.liType !== 'bullet' || !c.text.startsWith('langs')); +} + module.exports = { parseApi }; diff --git a/utils/doclint/generateApiJson.js b/utils/doclint/generateApiJson.js index b3e39ad5da..fe587efc2a 100644 --- a/utils/doclint/generateApiJson.js +++ b/utils/doclint/generateApiJson.js @@ -88,6 +88,7 @@ function sanitize(result) { delete result.args; delete result.argsArray; delete result.clazz; + delete result.langs; delete result.spec; }