From c55f2629405fb370c44b303b6b1c71127aefafa3 Mon Sep 17 00:00:00 2001 From: Pavel Feldman Date: Mon, 28 Sep 2020 12:35:58 -0700 Subject: [PATCH] chore: roll Playwright to 1.4.2 (#200) --- api.json | 775 +++++++++++++++++++++++++----- driver/package.json | 2 +- playwright/async_api.py | 387 +++++++++++---- playwright/element_handle.py | 19 +- playwright/frame.py | 5 +- playwright/helper.py | 12 +- playwright/page.py | 6 +- playwright/sync_api.py | 389 +++++++++++---- scripts/documentation_provider.py | 62 +-- scripts/expected_api_mismatch.txt | 102 ++++ 10 files changed, 1377 insertions(+), 382 deletions(-) create mode 100644 scripts/expected_api_mismatch.txt diff --git a/api.json b/api.json index b0bf75cd2..4193c81a2 100644 --- a/api.json +++ b/api.json @@ -109,7 +109,7 @@ "kind": "property", "name": "viewport", "type": { - "name": "?Object", + "name": "null|Object", "properties": { "width": { "kind": "property", @@ -352,7 +352,7 @@ "kind": "property", "name": "colorScheme", "type": { - "name": "\"light\"|\"dark\"|\"no-preference\"", + "name": "\"dark\"|\"light\"|\"no-preference\"", "properties": {} }, "comment": "Emulates `'prefers-colors-scheme'` media feature, supported values are `'light'`, `'dark'`, `'no-preference'`. See page.emulateMedia(options) for more details. Defaults to '`light`'.", @@ -371,6 +371,43 @@ "returnComment": "", "required": false, "templates": [] + }, + "_recordVideos": { + "kind": "property", + "name": "_recordVideos", + "type": { + "name": "Object", + "properties": { + "width": { + "kind": "property", + "name": "width", + "type": { + "name": "number", + "properties": {} + }, + "comment": "Video frame width.", + "returnComment": "", + "required": true, + "templates": [] + }, + "height": { + "kind": "property", + "name": "height", + "type": { + "name": "number", + "properties": {} + }, + "comment": "Video frame height.", + "returnComment": "", + "required": true, + "templates": [] + } + } + }, + "comment": "**experimental** Enables automatic video recording for new pages. The video will have frames with the provided dimensions. Actual picture of the page will be scaled down if necessary to fit specified size.", + "returnComment": "", + "required": false, + "templates": [] } } }, @@ -439,7 +476,7 @@ "kind": "property", "name": "viewport", "type": { - "name": "?Object", + "name": "null|Object", "properties": { "width": { "kind": "property", @@ -682,7 +719,7 @@ "kind": "property", "name": "colorScheme", "type": { - "name": "\"light\"|\"dark\"|\"no-preference\"", + "name": "\"dark\"|\"light\"|\"no-preference\"", "properties": {} }, "comment": "Emulates `'prefers-colors-scheme'` media feature, supported values are `'light'`, `'dark'`, `'no-preference'`. See page.emulateMedia(options) for more details. Defaults to '`light`'.", @@ -701,6 +738,43 @@ "returnComment": "", "required": false, "templates": [] + }, + "_recordVideos": { + "kind": "property", + "name": "_recordVideos", + "type": { + "name": "Object", + "properties": { + "width": { + "kind": "property", + "name": "width", + "type": { + "name": "number", + "properties": {} + }, + "comment": "Video frame width.", + "returnComment": "", + "required": true, + "templates": [] + }, + "height": { + "kind": "property", + "name": "height", + "type": { + "name": "number", + "properties": {} + }, + "comment": "Video frame height.", + "returnComment": "", + "required": true, + "templates": [] + } + } + }, + "comment": "**experimental** Enables automatic video recording for the new page. The video will have frames with the provided dimensions. Actual picture of the page will be scaled down if necessary to fit specified size.", + "returnComment": "", + "required": false, + "templates": [] } } }, @@ -873,7 +947,7 @@ "kind": "property", "name": "sameSite", "type": { - "name": "\"Strict\"|\"Lax\"|\"None\"", + "name": "\"Lax\"|\"None\"|\"Strict\"", "properties": {} }, "comment": "", @@ -1073,7 +1147,7 @@ "kind": "property", "name": "sameSite", "type": { - "name": "\"Strict\"|\"Lax\"|\"None\"", + "name": "\"Lax\"|\"None\"|\"Strict\"", "properties": {} }, "comment": "", @@ -1381,7 +1455,7 @@ "kind": "property", "name": "geolocation", "type": { - "name": "?Object", + "name": "null|Object", "properties": { "latitude": { "kind": "property", @@ -1435,7 +1509,7 @@ "name": "Promise", "properties": {} }, - "comment": "Provide credentials for HTTP authentication.\n\n**NOTE** Browsers may cache credentials that resulted in successful auth. That means passing different credentials after successful authentication or passing `null` to disable authentication is unreliable. Instead, create a separate browser context that will not have previous credentials cached.", + "comment": "Provide credentials for HTTP authentication.\n\n**NOTE** Browsers may cache credentials after successful authentication. Passing different credentials or passing `null` to disable authentication will be unreliable. To remove or replace credentials, create a new browser context instead.", "returnComment": "", "required": true, "templates": [], @@ -1444,7 +1518,7 @@ "kind": "property", "name": "httpCredentials", "type": { - "name": "?Object", + "name": "null|Object", "properties": { "username": { "kind": "property", @@ -1611,6 +1685,19 @@ "Page": { "name": "Page", "members": { + "_videostarted": { + "kind": "event", + "name": "_videostarted", + "type": { + "name": "Object", + "properties": {} + }, + "comment": "**experimental**\nEmitted when video recording has started for this page. The event will fire only if `_recordVideos` option is configured on the parent context.", + "returnComment": "", + "required": true, + "templates": [], + "args": {} + }, "close": { "kind": "method", "name": "close", @@ -1830,7 +1917,7 @@ "name": "Request", "properties": {} }, - "comment": "Emitted when a request finishes successfully.", + "comment": "Emitted when a request finishes successfully after downloading the response body. For a successful response, the sequence of events is `request`, `response` and `requestfinished`.", "returnComment": "", "required": true, "templates": [], @@ -1843,7 +1930,7 @@ "name": "Response", "properties": {} }, - "comment": "Emitted when a response is received.", + "comment": "Emitted when response status and headers are received for a request. For a successful response, the sequence of events is `request`, `response` and `requestfinished`.", "returnComment": "", "required": true, "templates": [], @@ -1866,7 +1953,7 @@ "kind": "method", "name": "$", "type": { - "name": "Promise", + "name": "Promise", "properties": {} }, "comment": "The method finds an element matching the specified selector within the page. If no elements match the selector, the return value resolves to `null`.\nShortcut for page.mainFrame().$(selector).", @@ -2034,7 +2121,7 @@ "name": "Promise", "properties": {} }, - "comment": "Adds a script which would be evaluated in one of the following scenarios:\n\nWhenever the page is navigated.\nWhenever the child frame is attached or navigated. In this case, the scritp is evaluated in the context of the newly attached frame.\n\nThe script is evaluated after the document was created but before any of its scripts were run. This is useful to amend the JavaScript environment, e.g. to seed `Math.random`.\nAn example of overriding `Math.random` before the page loads:\n```js\n// preload.js\nMath.random = () => 42;\n\n// In your playwright script, assuming the preload.js file is in same folder\nconst preloadFile = fs.readFileSync('./preload.js', 'utf8');\nawait page.addInitScript(preloadFile);\n```\n\n**NOTE** The order of evaluation of multiple scripts installed via browserContext.addInitScript(script[, arg]) and page.addInitScript(script[, arg]) is not defined.", + "comment": "Adds a script which would be evaluated in one of the following scenarios:\n\nWhenever the page is navigated.\nWhenever the child frame is attached or navigated. In this case, the script is evaluated in the context of the newly attached frame.\n\nThe script is evaluated after the document was created but before any of its scripts were run. This is useful to amend the JavaScript environment, e.g. to seed `Math.random`.\nAn example of overriding `Math.random` before the page loads:\n```js\n// preload.js\nMath.random = () => 42;\n\n// In your playwright script, assuming the preload.js file is in same folder\nconst preloadFile = fs.readFileSync('./preload.js', 'utf8');\nawait page.addInitScript(preloadFile);\n```\n\n**NOTE** The order of evaluation of multiple scripts installed via browserContext.addInitScript(script[, arg]) and page.addInitScript(script[, arg]) is not defined.", "returnComment": "", "required": true, "templates": [], @@ -2248,8 +2335,8 @@ "name": "Promise", "properties": {} }, - "comment": "This method waits for an element matching `selector`, waits for actionability checks. Then, if the element is not already checked, this method scrolls the element into view and uses elementHandle.click to click in the center of the element.\nIf there's no element matching `selector`, the method waits until a matching element appears in the DOM. If the element is detached during the actionability checks, the action is retried.\nShortcut for page.mainFrame().check(selector[, options]).", - "returnComment": "Promise which resolves when the element matching `selector` is successfully checked. The Promise will be rejected if there is no element matching `selector`.", + "comment": "This method checks an element matching `selector` by performing the following steps:\n\nFind an element match matching `selector`. If there is none, wait until a matching element is attached to the DOM.\nEnsure that matched element is a checkbox or a radio input. If not, this method rejects. If the element is already checked, this method returns immediately.\nWait for actionability checks on the matched element, unless `force` option is set. If the element is detached during the checks, the whole action is retried.\nScroll the element into view if needed.\nUse page.mouse to click in the center of the element.\nWait for initiated navigations to either succeed or fail, unless `noWaitAfter` option is set.\nEnsure that the element is now checked. If not, this method rejects.\n\nWhen all steps combined have not finished during the specified `timeout`, this method rejects with a TimeoutError. Passing zero timeout disables this.\nShortcut for page.mainFrame().check(selector[, options]).", + "returnComment": "Promise that resolves when the element matching `selector` is successfully checked.", "required": true, "templates": [], "args": { @@ -2323,8 +2410,8 @@ "name": "Promise", "properties": {} }, - "comment": "This method waits for an element matching `selector`, waits for actionability checks, then scrolls the element into view if needed and uses page.mouse to click in the center of the element.\nIf there's no element matching `selector`, the method waits until a matching element appears in the DOM. If the element is detached during the actionability checks, the action is retried.\nShortcut for page.mainFrame().click(selector[, options]).", - "returnComment": "Promise which resolves when the element matching `selector` is successfully clicked. The Promise will be rejected if there is no element matching `selector`.", + "comment": "This method clicks an element matching `selector` by performing the following steps:\n\nFind an element match matching `selector`. If there is none, wait until a matching element is attached to the DOM.\nWait for actionability checks on the matched element, unless `force` option is set. If the element is detached during the checks, the whole action is retried.\nScroll the element into view if needed.\nUse page.mouse to click in the center of the element, or the specified `position`.\nWait for initiated navigations to either succeed or fail, unless `noWaitAfter` option is set.\n\nWhen all steps combined have not finished during the specified `timeout`, this method rejects with a TimeoutError. Passing zero timeout disables this.\nShortcut for page.mainFrame().click(selector[, options]).", + "returnComment": "Promise that resolves when the element matching `selector` is successfully clicked.", "required": true, "templates": [], "args": { @@ -2350,7 +2437,7 @@ "kind": "property", "name": "button", "type": { - "name": "\"left\"|\"right\"|\"middle\"", + "name": "\"left\"|\"middle\"|\"right\"", "properties": {} }, "comment": "Defaults to `left`.", @@ -2506,7 +2593,7 @@ "kind": "property", "name": "coverage", "type": { - "name": "?ChromiumCoverage", + "name": "null|ChromiumCoverage", "properties": {} }, "comment": "Browser-specific Coverage implementation, only available for Chromium atm. See ChromiumCoverage for more details.", @@ -2522,8 +2609,8 @@ "name": "Promise", "properties": {} }, - "comment": "This method waits for an element matching `selector`, waits for actionability checks, then scrolls the element into view if needed and uses page.mouse to double click in the center of the element.\nIf there's no element matching `selector`, the method waits until a matching element appears in the DOM. If the element is detached during the actionability checks, the action is retried.\nBear in mind that if the first click of the `dblclick()` triggers a navigation event, there will be an exception.\n\n**NOTE** `page.dblclick()` dispatches two `click` events and a single `dblclick` event.\n\nShortcut for page.mainFrame().dblclick(selector[, options]).", - "returnComment": "Promise which resolves when the element matching `selector` is successfully double clicked. The Promise will be rejected if there is no element matching `selector`.", + "comment": "This method double clicks an element matching `selector` by performing the following steps:\n\nFind an element match matching `selector`. If there is none, wait until a matching element is attached to the DOM.\nWait for actionability checks on the matched element, unless `force` option is set. If the element is detached during the checks, the whole action is retried.\nScroll the element into view if needed.\nUse page.mouse to double click in the center of the element, or the specified `position`.\nWait for initiated navigations to either succeed or fail, unless `noWaitAfter` option is set. Note that if the first click of the `dblclick()` triggers a navigation event, this method will reject.\n\nWhen all steps combined have not finished during the specified `timeout`, this method rejects with a TimeoutError. Passing zero timeout disables this.\n\n**NOTE** `page.dblclick()` dispatches two `click` events and a single `dblclick` event.\n\nShortcut for page.mainFrame().dblclick(selector[, options]).", + "returnComment": "Promise that resolves when the element matching `selector` is successfully double clicked.", "required": true, "templates": [], "args": { @@ -2549,7 +2636,7 @@ "kind": "property", "name": "button", "type": { - "name": "\"left\"|\"right\"|\"middle\"", + "name": "\"left\"|\"middle\"|\"right\"", "properties": {} }, "comment": "Defaults to `left`.", @@ -2703,7 +2790,7 @@ "kind": "property", "name": "eventInit", "type": { - "name": "Object", + "name": "EvaluationArgument", "properties": {} }, "comment": "event-specific initialization properties.", @@ -2760,7 +2847,7 @@ "kind": "property", "name": "media", "type": { - "name": "null|\"screen\"|\"print\"", + "name": "null|\"print\"|\"screen\"", "properties": {} }, "comment": "Changes the CSS media type of the page. The only allowed values are `'screen'`, `'print'` and `null`. Passing `null` disables CSS media emulation. Omitting `media` or passing `undefined` does not change the emulated value.", @@ -2772,7 +2859,7 @@ "kind": "property", "name": "colorScheme", "type": { - "name": "null|\"light\"|\"dark\"|\"no-preference\"", + "name": "null|\"dark\"|\"light\"|\"no-preference\"", "properties": {} }, "comment": "Emulates `'prefers-colors-scheme'` media feature, supported values are `'light'`, `'dark'`, `'no-preference'`. Passing `null` disables color scheme emulation. Omitting `colorScheme` or passing `undefined` does not change the emulated value.", @@ -3071,7 +3158,7 @@ "kind": "method", "name": "frame", "type": { - "name": "?Frame", + "name": "null|Frame", "properties": {} }, "comment": "```js\nconst frame = page.frame('frame-name');\n```\n```js\nconst frame = page.frame({ url: /.*domain.*/ });\n```\nReturns frame matching the specified criteria. Either `name` or `url` must be specified.", @@ -3198,7 +3285,7 @@ "kind": "method", "name": "goBack", "type": { - "name": "Promise", + "name": "Promise", "properties": {} }, "comment": "Navigate to the previous page in history.", @@ -3228,7 +3315,7 @@ "kind": "property", "name": "waitUntil", "type": { - "name": "\"load\"|\"domcontentloaded\"|\"networkidle\"", + "name": "\"domcontentloaded\"|\"load\"|\"networkidle\"", "properties": {} }, "comment": "When to consider navigation succeeded, defaults to `load`. Events can be either:\n - `'domcontentloaded'` - consider navigation to be finished when the `DOMContentLoaded` event is fired.\n - `'load'` - consider navigation to be finished when the `load` event is fired.\n - `'networkidle'` - consider navigation to be finished when there are no network connections for at least `500` ms.", @@ -3249,7 +3336,7 @@ "kind": "method", "name": "goForward", "type": { - "name": "Promise", + "name": "Promise", "properties": {} }, "comment": "Navigate to the next page in history.", @@ -3279,7 +3366,7 @@ "kind": "property", "name": "waitUntil", "type": { - "name": "\"load\"|\"domcontentloaded\"|\"networkidle\"", + "name": "\"domcontentloaded\"|\"load\"|\"networkidle\"", "properties": {} }, "comment": "When to consider navigation succeeded, defaults to `load`. Events can be either:\n - `'domcontentloaded'` - consider navigation to be finished when the `DOMContentLoaded` event is fired.\n - `'load'` - consider navigation to be finished when the `load` event is fired.\n - `'networkidle'` - consider navigation to be finished when there are no network connections for at least `500` ms.", @@ -3300,7 +3387,7 @@ "kind": "method", "name": "goto", "type": { - "name": "Promise", + "name": "Promise", "properties": {} }, "comment": "`page.goto` will throw an error if:\n\nthere's an SSL error (e.g. in case of self-signed certificates).\ntarget URL is invalid.\nthe `timeout` is exceeded during navigation.\nthe remote server does not respond or is unreachable.\nthe main resource failed to load.\n\n`page.goto` will not throw an error when any valid HTTP status code is returned by the remote server, including 404 \"Not Found\" and 500 \"Internal Server Error\". The status code for such responses can be retrieved by calling response.status().\n\n**NOTE** `page.goto` either throws an error or returns a main resource response. The only exceptions are navigation to `about:blank` or navigation to the same URL with a different hash, which would succeed and return `null`.\n\n\n**NOTE** Headless mode doesn't support navigation to a PDF document. See the upstream issue.\n\nShortcut for page.mainFrame().goto(url[, options])", @@ -3342,7 +3429,7 @@ "kind": "property", "name": "waitUntil", "type": { - "name": "\"load\"|\"domcontentloaded\"|\"networkidle\"", + "name": "\"domcontentloaded\"|\"load\"|\"networkidle\"", "properties": {} }, "comment": "When to consider navigation succeeded, defaults to `load`. Events can be either:\n - `'domcontentloaded'` - consider navigation to be finished when the `DOMContentLoaded` event is fired.\n - `'load'` - consider navigation to be finished when the `load` event is fired.\n - `'networkidle'` - consider navigation to be finished when there are no network connections for at least `500` ms.", @@ -3378,8 +3465,8 @@ "name": "Promise", "properties": {} }, - "comment": "This method waits for an element matching `selector`, waits for actionability checks, then scrolls the element into view if needed and uses page.mouse to hover over the center of the element.\nIf there's no element matching `selector`, the method waits until a matching element appears in the DOM. If the element is detached during the actionability checks, the action is retried.\nShortcut for page.mainFrame().hover(selector[, options]).", - "returnComment": "Promise which resolves when the element matching `selector` is successfully hovered. Promise gets rejected if there's no element matching `selector`.", + "comment": "This method hovers over an element matching `selector` by performing the following steps:\n\nFind an element match matching `selector`. If there is none, wait until a matching element is attached to the DOM.\nWait for actionability checks on the matched element, unless `force` option is set. If the element is detached during the checks, the whole action is retried.\nScroll the element into view if needed.\nUse page.mouse to hover over the center of the element, or the specified `position`.\nWait for initiated navigations to either succeed or fail, unless `noWaitAfter` option is set.\n\nWhen all steps combined have not finished during the specified `timeout`, this method rejects with a TimeoutError. Passing zero timeout disables this.\nShortcut for page.mainFrame().hover(selector[, options]).", + "returnComment": "Promise that resolves when the element matching `selector` is successfully hovered.", "required": true, "templates": [], "args": { @@ -3641,7 +3728,7 @@ "kind": "method", "name": "opener", "type": { - "name": "Promise", + "name": "Promise", "properties": {} }, "comment": "", @@ -3973,7 +4060,7 @@ "kind": "method", "name": "reload", "type": { - "name": "Promise", + "name": "Promise", "properties": {} }, "comment": "", @@ -4003,7 +4090,7 @@ "kind": "property", "name": "waitUntil", "type": { - "name": "\"load\"|\"domcontentloaded\"|\"networkidle\"", + "name": "\"domcontentloaded\"|\"load\"|\"networkidle\"", "properties": {} }, "comment": "When to consider navigation succeeded, defaults to `load`. Events can be either:\n - `'domcontentloaded'` - consider navigation to be finished when the `DOMContentLoaded` event is fired.\n - `'load'` - consider navigation to be finished when the `load` event is fired.\n - `'networkidle'` - consider navigation to be finished when there are no network connections for at least `500` ms.", @@ -4092,7 +4179,7 @@ "kind": "property", "name": "type", "type": { - "name": "\"png\"|\"jpeg\"", + "name": "\"jpeg\"|\"png\"", "properties": {} }, "comment": "Specify screenshot type, defaults to `png`.", @@ -4376,7 +4463,7 @@ "kind": "property", "name": "waitUntil", "type": { - "name": "\"load\"|\"domcontentloaded\"|\"networkidle\"", + "name": "\"domcontentloaded\"|\"load\"|\"networkidle\"", "properties": {} }, "comment": "When to consider setting markup succeeded, defaults to `load`. Given an array of event strings, setting content is considered to be successful after all events have been fired. Events can be either:\n - `'load'` - consider setting content to be finished when the `load` event is fired.\n - `'domcontentloaded'` - consider setting content to be finished when the `DOMContentLoaded` event is fired.\n - `'networkidle'` - consider setting content to be finished when there are no network connections for at least `500` ms.", @@ -4786,8 +4873,8 @@ "name": "Promise", "properties": {} }, - "comment": "This method waits for an element matching `selector`, waits for actionability checks. Then, if the element is not already unchecked, this method scrolls the element into view and uses elementHandle.click to click in the center of the element.\nIf there's no element matching `selector`, the method waits until a matching element appears in the DOM. If the element is detached during the actionability checks, the action is retried.\nShortcut for page.mainFrame().uncheck(selector[, options]).", - "returnComment": "Promise which resolves when the element matching `selector` is successfully unchecked. The Promise will be rejected if there is no element matching `selector`.", + "comment": "This method unchecks an element matching `selector` by performing the following steps:\n\nFind an element match matching `selector`. If there is none, wait until a matching element is attached to the DOM.\nEnsure that matched element is a checkbox or a radio input. If not, this method rejects. If the element is already unchecked, this method returns immediately.\nWait for actionability checks on the matched element, unless `force` option is set. If the element is detached during the checks, the whole action is retried.\nScroll the element into view if needed.\nUse page.mouse to click in the center of the element.\nWait for initiated navigations to either succeed or fail, unless `noWaitAfter` option is set.\nEnsure that the element is now unchecked. If not, this method rejects.\n\nWhen all steps combined have not finished during the specified `timeout`, this method rejects with a TimeoutError. Passing zero timeout disables this.\nShortcut for page.mainFrame().uncheck(selector[, options]).", + "returnComment": "Promise that resolves when the element matching `selector` is successfully unchecked.", "required": true, "templates": [], "args": { @@ -4909,7 +4996,7 @@ "kind": "method", "name": "viewportSize", "type": { - "name": "?Object", + "name": "null|Object", "properties": { "width": { "kind": "property", @@ -5097,7 +5184,7 @@ "kind": "property", "name": "state", "type": { - "name": "\"load\"|\"domcontentloaded\"|\"networkidle\"", + "name": "\"domcontentloaded\"|\"load\"|\"networkidle\"", "properties": {} }, "comment": "Load state to wait for, defaults to `load`. If the state has been already reached while loading current document, the method resolves immediately.\n - `'load'` - wait for the `load` event to be fired.\n - `'domcontentloaded'` - wait for the `DOMContentLoaded` event to be fired.\n - `'networkidle'` - wait until there are no network connections for at least `500` ms.", @@ -5136,10 +5223,10 @@ "kind": "method", "name": "waitForNavigation", "type": { - "name": "Promise", + "name": "Promise", "properties": {} }, - "comment": "This resolves when the page navigates to a new URL or reloads. It is useful for when you run code\nwhich will indirectly cause the page to navigate. Consider this example:\n```js\nconst [response] = await Promise.all([\n page.waitForNavigation(), // The promise resolves after navigation has finished\n page.click('a.my-link'), // Clicking the link will indirectly cause a navigation\n]);\n```\n**NOTE** Usage of the History API to change the URL is considered a navigation.\nShortcut for page.mainFrame().waitForNavigation(options).", + "comment": "This resolves when the page navigates to a new URL or reloads. It is useful for when you run code\nwhich will indirectly cause the page to navigate. e.g. The click target has an `onclick` handler that triggers navigation from a `setTimeout`. Consider this example:\n```js\nconst [response] = await Promise.all([\n page.waitForNavigation(), // The promise resolves after navigation has finished\n page.click('a.delayed-navigation'), // Clicking the link will indirectly cause a navigation\n]);\n```\n**NOTE** Usage of the History API to change the URL is considered a navigation.\nShortcut for page.mainFrame().waitForNavigation(options).", "returnComment": "Promise which resolves to the main resource response. In case of multiple redirects, the navigation will resolve with the response of the last redirect. In case of navigation to a different anchor or navigation due to History API usage, the navigation will resolve with `null`.", "required": true, "templates": [], @@ -5178,7 +5265,7 @@ "kind": "property", "name": "waitUntil", "type": { - "name": "\"load\"|\"domcontentloaded\"|\"networkidle\"", + "name": "\"domcontentloaded\"|\"load\"|\"networkidle\"", "properties": {} }, "comment": "When to consider navigation succeeded, defaults to `load`. Events can be either:\n - `'domcontentloaded'` - consider navigation to be finished when the `DOMContentLoaded` event is fired.\n - `'load'` - consider navigation to be finished when the `load` event is fired.\n - `'networkidle'` - consider navigation to be finished when there are no network connections for at least `500` ms.", @@ -5301,7 +5388,7 @@ "kind": "method", "name": "waitForSelector", "type": { - "name": "Promise", + "name": "Promise", "properties": {} }, "comment": "Wait for the `selector` to satisfy `state` option (either appear/disappear from dom, or become visible/hidden). If at the moment of calling the method `selector` already satisfies the condition, the method will return immediately. If the selector doesn't satisfy the condition for the `timeout` milliseconds, the function will throw.\nThis method works across navigations:\n```js\nconst { chromium } = require('playwright'); // Or 'firefox' or 'webkit'.\n\n(async () => {\n const browser = await chromium.launch();\n const page = await browser.newPage();\n let currentURL;\n page\n .waitForSelector('img')\n .then(() => console.log('First URL with image: ' + currentURL));\n for (currentURL of ['https://example.com', 'https://google.com', 'https://bbc.com']) {\n await page.goto(currentURL);\n }\n await browser.close();\n})();\n```\nShortcut for page.mainFrame().waitForSelector(selector[, options]).", @@ -5331,7 +5418,7 @@ "kind": "property", "name": "state", "type": { - "name": "\"attached\"|\"detached\"|\"visible\"|\"hidden\"", + "name": "\"attached\"|\"detached\"|\"hidden\"|\"visible\"", "properties": {} }, "comment": "Defaults to `'visible'`. Can be either:\n - `'attached'` - wait for element to be present in DOM.\n - `'detached'` - wait for element to not be present in DOM.\n - `'visible'` - wait for element to have non-empty bounding box and no `visibility:hidden`. Note that element without any content or with `display:none` has an empty bounding box and is not considered visible.\n - `'hidden'` - wait for element to be either detached from DOM, or have an empty bounding box or `visibility:hidden`. This is opposite to the `'visible'` option.", @@ -5408,7 +5495,7 @@ "kind": "method", "name": "$", "type": { - "name": "Promise", + "name": "Promise", "properties": {} }, "comment": "The method finds an element matching the specified selector within the frame. See Working with selectors for more details. If no elements match the selector, the return value resolves to `null`.", @@ -5701,8 +5788,8 @@ "name": "Promise", "properties": {} }, - "comment": "This method waits for an element matching `selector`, waits for actionability checks. Then, if the element is not already checked, this method scrolls the element into view and uses elementHandle.click to click in the center of the element.\nIf there's no element matching `selector`, the method waits until a matching element appears in the DOM. If the element is detached during the actionability checks, the action is retried.", - "returnComment": "Promise which resolves when the element matching `selector` is successfully checked. The Promise will be rejected if there is no element matching `selector`.", + "comment": "This method checks an element matching `selector` by performing the following steps:\n\nFind an element match matching `selector`. If there is none, wait until a matching element is attached to the DOM.\nEnsure that matched element is a checkbox or a radio input. If not, this method rejects. If the element is already checked, this method returns immediately.\nWait for actionability checks on the matched element, unless `force` option is set. If the element is detached during the checks, the whole action is retried.\nScroll the element into view if needed.\nUse page.mouse to click in the center of the element.\nWait for initiated navigations to either succeed or fail, unless `noWaitAfter` option is set.\nEnsure that the element is now checked. If not, this method rejects.\n\nWhen all steps combined have not finished during the specified `timeout`, this method rejects with a TimeoutError. Passing zero timeout disables this.", + "returnComment": "Promise that resolves when the element matching `selector` is successfully checked.", "required": true, "templates": [], "args": { @@ -5789,8 +5876,8 @@ "name": "Promise", "properties": {} }, - "comment": "This method waits for an element matching `selector`, waits for actionability checks, then scrolls the element into view if needed and uses page.mouse to click in the center of the element.\nIf there's no element matching `selector`, the method waits until a matching element appears in the DOM. If the element is detached during the actionability checks, the action is retried.", - "returnComment": "Promise which resolves when the element matching `selector` is successfully clicked. The Promise will be rejected if there is no element matching `selector`.", + "comment": "This method clicks an element matching `selector` by performing the following steps:\n\nFind an element match matching `selector`. If there is none, wait until a matching element is attached to the DOM.\nWait for actionability checks on the matched element, unless `force` option is set. If the element is detached during the checks, the whole action is retried.\nScroll the element into view if needed.\nUse page.mouse to click in the center of the element, or the specified `position`.\nWait for initiated navigations to either succeed or fail, unless `noWaitAfter` option is set.\n\nWhen all steps combined have not finished during the specified `timeout`, this method rejects with a TimeoutError. Passing zero timeout disables this.", + "returnComment": "Promise that resolves when the element matching `selector` is successfully clicked.", "required": true, "templates": [], "args": { @@ -5816,7 +5903,7 @@ "kind": "property", "name": "button", "type": { - "name": "\"left\"|\"right\"|\"middle\"", + "name": "\"left\"|\"middle\"|\"right\"", "properties": {} }, "comment": "Defaults to `left`.", @@ -5962,8 +6049,8 @@ "name": "Promise", "properties": {} }, - "comment": "This method waits for an element matching `selector`, waits for actionability checks, then scrolls the element into view if needed and uses page.mouse to double click in the center of the element.\nIf there's no element matching `selector`, the method waits until a matching element appears in the DOM. If the element is detached during the actionability checks, the action is retried.\nBear in mind that if the first click of the `dblclick()` triggers a navigation event, there will be an exception.\n\n**NOTE** `frame.dblclick()` dispatches two `click` events and a single `dblclick` event.", - "returnComment": "Promise which resolves when the element matching `selector` is successfully double clicked. The Promise will be rejected if there is no element matching `selector`.", + "comment": "This method double clicks an element matching `selector` by performing the following steps:\n\nFind an element match matching `selector`. If there is none, wait until a matching element is attached to the DOM.\nWait for actionability checks on the matched element, unless `force` option is set. If the element is detached during the checks, the whole action is retried.\nScroll the element into view if needed.\nUse page.mouse to double click in the center of the element, or the specified `position`.\nWait for initiated navigations to either succeed or fail, unless `noWaitAfter` option is set. Note that if the first click of the `dblclick()` triggers a navigation event, this method will reject.\n\nWhen all steps combined have not finished during the specified `timeout`, this method rejects with a TimeoutError. Passing zero timeout disables this.\n\n**NOTE** `frame.dblclick()` dispatches two `click` events and a single `dblclick` event.", + "returnComment": "Promise that resolves when the element matching `selector` is successfully double clicked.", "required": true, "templates": [], "args": { @@ -5989,7 +6076,7 @@ "kind": "property", "name": "button", "type": { - "name": "\"left\"|\"right\"|\"middle\"", + "name": "\"left\"|\"middle\"|\"right\"", "properties": {} }, "comment": "Defaults to `left`.", @@ -6143,7 +6230,7 @@ "kind": "property", "name": "eventInit", "type": { - "name": "Object", + "name": "EvaluationArgument", "properties": {} }, "comment": "event-specific initialization properties.", @@ -6460,7 +6547,7 @@ "kind": "method", "name": "goto", "type": { - "name": "Promise", + "name": "Promise", "properties": {} }, "comment": "`frame.goto` will throw an error if:\n\nthere's an SSL error (e.g. in case of self-signed certificates).\ntarget URL is invalid.\nthe `timeout` is exceeded during navigation.\nthe remote server does not respond or is unreachable.\nthe main resource failed to load.\n\n`frame.goto` will not throw an error when any valid HTTP status code is returned by the remote server, including 404 \"Not Found\" and 500 \"Internal Server Error\". The status code for such responses can be retrieved by calling response.status().\n\n**NOTE** `frame.goto` either throws an error or returns a main resource response. The only exceptions are navigation to `about:blank` or navigation to the same URL with a different hash, which would succeed and return `null`.\n\n\n**NOTE** Headless mode doesn't support navigation to a PDF document. See the upstream issue.", @@ -6502,7 +6589,7 @@ "kind": "property", "name": "waitUntil", "type": { - "name": "\"load\"|\"domcontentloaded\"|\"networkidle\"", + "name": "\"domcontentloaded\"|\"load\"|\"networkidle\"", "properties": {} }, "comment": "When to consider navigation succeeded, defaults to `load`. Events can be either:\n - `'domcontentloaded'` - consider navigation to be finished when the `DOMContentLoaded` event is fired.\n - `'load'` - consider navigation to be finished when the `load` event is fired.\n - `'networkidle'` - consider navigation to be finished when there are no network connections for at least `500` ms.", @@ -6538,8 +6625,8 @@ "name": "Promise", "properties": {} }, - "comment": "This method waits for an element matching `selector`, waits for actionability checks, then scrolls the element into view if needed and uses page.mouse to hover over the center of the element.\nIf there's no element matching `selector`, the method waits until a matching element appears in the DOM. If the element is detached during the actionability checks, the action is retried.", - "returnComment": "Promise which resolves when the element matching `selector` is successfully hovered. Promise gets rejected if there's no element matching `selector`.", + "comment": "This method hovers over an element matching `selector` by performing the following steps:\n\nFind an element match matching `selector`. If there is none, wait until a matching element is attached to the DOM.\nWait for actionability checks on the matched element, unless `force` option is set. If the element is detached during the checks, the whole action is retried.\nScroll the element into view if needed.\nUse page.mouse to hover over the center of the element, or the specified `position`.\nWait for initiated navigations to either succeed or fail, unless `noWaitAfter` option is set.\n\nWhen all steps combined have not finished during the specified `timeout`, this method rejects with a TimeoutError. Passing zero timeout disables this.", + "returnComment": "Promise that resolves when the element matching `selector` is successfully hovered.", "required": true, "templates": [], "args": { @@ -6771,11 +6858,24 @@ "templates": [], "args": {} }, + "page": { + "kind": "method", + "name": "page", + "type": { + "name": "Page", + "properties": {} + }, + "comment": "Returns the page containing this frame.", + "returnComment": "", + "required": true, + "templates": [], + "args": {} + }, "parentFrame": { "kind": "method", "name": "parentFrame", "type": { - "name": "?Frame", + "name": "null|Frame", "properties": {} }, "comment": "", @@ -7029,7 +7129,7 @@ "kind": "property", "name": "waitUntil", "type": { - "name": "\"load\"|\"domcontentloaded\"|\"networkidle\"", + "name": "\"domcontentloaded\"|\"load\"|\"networkidle\"", "properties": {} }, "comment": "When to consider navigation succeeded, defaults to `load`. Events can be either:\n - `'domcontentloaded'` - consider setting content to be finished when the `DOMContentLoaded` event is fired.\n - `'load'` - consider setting content to be finished when the `load` event is fired.\n - `'networkidle'` - consider setting content to be finished when there are no network connections for at least `500` ms.", @@ -7316,8 +7416,8 @@ "name": "Promise", "properties": {} }, - "comment": "This method waits for an element matching `selector`, waits for actionability checks. Then, if the element is not already unchecked, this method scrolls the element into view and uses elementHandle.click to click in the center of the element.\nIf there's no element matching `selector`, the method waits until a matching element appears in the DOM. If the element is detached during the actionability checks, the action is retried.", - "returnComment": "Promise which resolves when the element matching `selector` is successfully unchecked. The Promise will be rejected if there is no element matching `selector`.", + "comment": "This method checks an element matching `selector` by performing the following steps:\n\nFind an element match matching `selector`. If there is none, wait until a matching element is attached to the DOM.\nEnsure that matched element is a checkbox or a radio input. If not, this method rejects. If the element is already unchecked, this method returns immediately.\nWait for actionability checks on the matched element, unless `force` option is set. If the element is detached during the checks, the whole action is retried.\nScroll the element into view if needed.\nUse page.mouse to click in the center of the element.\nWait for initiated navigations to either succeed or fail, unless `noWaitAfter` option is set.\nEnsure that the element is now unchecked. If not, this method rejects.\n\nWhen all steps combined have not finished during the specified `timeout`, this method rejects with a TimeoutError. Passing zero timeout disables this.", + "returnComment": "Promise that resolves when the element matching `selector` is successfully unchecked.", "required": true, "templates": [], "args": { @@ -7488,7 +7588,7 @@ "kind": "property", "name": "state", "type": { - "name": "\"load\"|\"domcontentloaded\"|\"networkidle\"", + "name": "\"domcontentloaded\"|\"load\"|\"networkidle\"", "properties": {} }, "comment": "Load state to wait for, defaults to `load`. If the state has been already reached while loading current document, the method resolves immediately.\n - `'load'` - wait for the `load` event to be fired.\n - `'domcontentloaded'` - wait for the `DOMContentLoaded` event to be fired.\n - `'networkidle'` - wait until there are no network connections for at least `500` ms.", @@ -7527,7 +7627,7 @@ "kind": "method", "name": "waitForNavigation", "type": { - "name": "Promise", + "name": "Promise", "properties": {} }, "comment": "This resolves when the frame navigates to a new URL. It is useful for when you run code\nwhich will indirectly cause the frame to navigate. Consider this example:\n```js\nconst [response] = await Promise.all([\n frame.waitForNavigation(), // The navigation promise resolves after navigation has finished\n frame.click('a.my-link'), // Clicking the link will indirectly cause a navigation\n]);\n```\n**NOTE** Usage of the History API to change the URL is considered a navigation.", @@ -7569,7 +7669,7 @@ "kind": "property", "name": "waitUntil", "type": { - "name": "\"load\"|\"domcontentloaded\"|\"networkidle\"", + "name": "\"domcontentloaded\"|\"load\"|\"networkidle\"", "properties": {} }, "comment": "When to consider navigation succeeded, defaults to `load`. Events can be either:\n - `'domcontentloaded'` - consider navigation to be finished when the `DOMContentLoaded` event is fired.\n - `'load'` - consider navigation to be finished when the `load` event is fired.\n - `'networkidle'` - consider navigation to be finished when there are no network connections for at least `500` ms.", @@ -7590,7 +7690,7 @@ "kind": "method", "name": "waitForSelector", "type": { - "name": "Promise", + "name": "Promise", "properties": {} }, "comment": "Wait for the `selector` to satisfy `state` option (either appear/disappear from dom, or become visible/hidden). If at the moment of calling the method `selector` already satisfies the condition, the method will return immediately. If the selector doesn't satisfy the condition for the `timeout` milliseconds, the function will throw.\nThis method works across navigations:\n```js\nconst { webkit } = require('playwright'); // Or 'chromium' or 'firefox'.\n\n(async () => {\n const browser = await webkit.launch();\n const page = await browser.newPage();\n let currentURL;\n page.mainFrame()\n .waitForSelector('img')\n .then(() => console.log('First URL with image: ' + currentURL));\n for (currentURL of ['https://example.com', 'https://google.com', 'https://bbc.com']) {\n await page.goto(currentURL);\n }\n await browser.close();\n})();\n```", @@ -7620,7 +7720,7 @@ "kind": "property", "name": "state", "type": { - "name": "\"attached\"|\"detached\"|\"visible\"|\"hidden\"", + "name": "\"attached\"|\"detached\"|\"hidden\"|\"visible\"", "properties": {} }, "comment": "Defaults to `'visible'`. Can be either:\n - `'attached'` - wait for element to be present in DOM.\n - `'detached'` - wait for element to not be present in DOM.\n - `'visible'` - wait for element to have non-empty bounding box and no `visibility:hidden`. Note that element without any content or with `display:none` has an empty bounding box and is not considered visible.\n - `'hidden'` - wait for element to be either detached from DOM, or have an empty bounding box or `visibility:hidden`. This is opposite to the `'visible'` option.", @@ -7684,7 +7784,7 @@ "kind": "method", "name": "$", "type": { - "name": "Promise", + "name": "Promise", "properties": {} }, "comment": "The method finds an element matching the specified selector in the `ElementHandle`'s subtree. See Working with selectors for more details. If no elements match the selector, the return value resolves to `null`.", @@ -7836,7 +7936,7 @@ "kind": "method", "name": "boundingBox", "type": { - "name": "Promise", + "name": "Promise", "properties": { "x": { "kind": "property", @@ -7901,8 +8001,8 @@ "name": "Promise", "properties": {} }, - "comment": "This method waits for actionability checks. Then, if the element is not already checked, this method scrolls the element into view and uses elementHandle.click to click in the center of the element.", - "returnComment": "Promise which resolves when the element is successfully checked. Promise gets rejected if the operation fails.", + "comment": "This method checks the element by performing the following steps:\n\nEnsure that element is a checkbox or a radio input. If not, this method rejects. If the element is already checked, this method returns immediately.\nWait for actionability checks on the element, unless `force` option is set.\nScroll the element into view if needed.\nUse page.mouse to click in the center of the element.\nWait for initiated navigations to either succeed or fail, unless `noWaitAfter` option is set.\nEnsure that the element is now checked. If not, this method rejects.\n\nIf the element is detached from the DOM at any moment during the action, this method rejects.\nWhen all steps combined have not finished during the specified `timeout`, this method rejects with a TimeoutError. Passing zero timeout disables this.", + "returnComment": "Promise that resolves when the element is successfully checked.", "required": true, "templates": [], "args": { @@ -7964,8 +8064,8 @@ "name": "Promise", "properties": {} }, - "comment": "This method waits for actionability checks, then scrolls the element into view if needed and uses page.mouse to click in the center of the element.\nIf the element is detached from DOM, the method throws an error.", - "returnComment": "Promise which resolves when the element is successfully clicked. Promise gets rejected if the element is detached from DOM.", + "comment": "This method clicks the element by performing the following steps:\n\nWait for actionability checks on the element, unless `force` option is set.\nScroll the element into view if needed.\nUse page.mouse to click in the center of the element, or the specified `position`.\nWait for initiated navigations to either succeed or fail, unless `noWaitAfter` option is set.\n\nIf the element is detached from the DOM at any moment during the action, this method rejects.\nWhen all steps combined have not finished during the specified `timeout`, this method rejects with a TimeoutError. Passing zero timeout disables this.", + "returnComment": "Promise that resolves when the element is successfully clicked.", "required": true, "templates": [], "args": { @@ -7979,7 +8079,7 @@ "kind": "property", "name": "button", "type": { - "name": "\"left\"|\"right\"|\"middle\"", + "name": "\"left\"|\"middle\"|\"right\"", "properties": {} }, "comment": "Defaults to `left`.", @@ -8109,7 +8209,7 @@ "kind": "method", "name": "contentFrame", "type": { - "name": "Promise", + "name": "Promise", "properties": {} }, "comment": "", @@ -8125,8 +8225,8 @@ "name": "Promise", "properties": {} }, - "comment": "This method waits for actionability checks, then scrolls the element into view if needed and uses page.mouse to double click in the center of the element.\nIf the element is detached from DOM, the method throws an error.\nBear in mind that if the first click of the `dblclick()` triggers a navigation event, there will be an exception.\n\n**NOTE** `elementHandle.dblclick()` dispatches two `click` events and a single `dblclick` event.", - "returnComment": "Promise which resolves when the element is successfully double clicked. Promise gets rejected if the element is detached from DOM.", + "comment": "This method double clicks the element by performing the following steps:\n\nWait for actionability checks on the element, unless `force` option is set.\nScroll the element into view if needed.\nUse page.mouse to double click in the center of the element, or the specified `position`.\nWait for initiated navigations to either succeed or fail, unless `noWaitAfter` option is set. Note that if the first click of the `dblclick()` triggers a navigation event, this method will reject.\n\nIf the element is detached from the DOM at any moment during the action, this method rejects.\nWhen all steps combined have not finished during the specified `timeout`, this method rejects with a TimeoutError. Passing zero timeout disables this.\n\n**NOTE** `elementHandle.dblclick()` dispatches two `click` events and a single `dblclick` event.", + "returnComment": "Promise that resolves when the element is successfully double clicked.", "required": true, "templates": [], "args": { @@ -8140,7 +8240,7 @@ "kind": "property", "name": "button", "type": { - "name": "\"left\"|\"right\"|\"middle\"", + "name": "\"left\"|\"middle\"|\"right\"", "properties": {} }, "comment": "Defaults to `left`.", @@ -8282,7 +8382,7 @@ "kind": "property", "name": "eventInit", "type": { - "name": "Object", + "name": "EvaluationArgument", "properties": {} }, "comment": "event-specific initialization properties.", @@ -8401,8 +8501,8 @@ "name": "Promise", "properties": {} }, - "comment": "This method waits for actionability checks, then scrolls the element into view if needed and uses page.mouse to hover over the center of the element.\nIf the element is detached from DOM, the method throws an error.", - "returnComment": "Promise which resolves when the element is successfully hovered.", + "comment": "This method hovers over the element by performing the following steps:\n\nWait for actionability checks on the element, unless `force` option is set.\nScroll the element into view if needed.\nUse page.mouse to hover over the center of the element, or the specified `position`.\nWait for initiated navigations to either succeed or fail, unless `noWaitAfter` option is set.\n\nIf the element is detached from the DOM at any moment during the action, this method rejects.\nWhen all steps combined have not finished during the specified `timeout`, this method rejects with a TimeoutError. Passing zero timeout disables this.", + "returnComment": "Promise that resolves when the element is successfully hovered.", "required": true, "templates": [], "args": { @@ -8524,7 +8624,7 @@ "kind": "method", "name": "ownerFrame", "type": { - "name": "Promise", + "name": "Promise", "properties": {} }, "comment": "", @@ -8642,7 +8742,7 @@ "kind": "property", "name": "type", "type": { - "name": "\"png\"|\"jpeg\"", + "name": "\"jpeg\"|\"png\"", "properties": {} }, "comment": "Specify screenshot type, defaults to `png`.", @@ -9081,8 +9181,8 @@ "name": "Promise", "properties": {} }, - "comment": "This method waits for actionability checks. Then, if the element is not already unchecked, this method scrolls the element into view and uses elementHandle.click to click in the center of the element.", - "returnComment": "Promise which resolves when the element is successfully unchecked. Promise gets rejected if the operation fails.", + "comment": "This method checks the element by performing the following steps:\n\nEnsure that element is a checkbox or a radio input. If not, this method rejects. If the element is already unchecked, this method returns immediately.\nWait for actionability checks on the element, unless `force` option is set.\nScroll the element into view if needed.\nUse page.mouse to click in the center of the element.\nWait for initiated navigations to either succeed or fail, unless `noWaitAfter` option is set.\nEnsure that the element is now unchecked. If not, this method rejects.\n\nIf the element is detached from the DOM at any moment during the action, this method rejects.\nWhen all steps combined have not finished during the specified `timeout`, this method rejects with a TimeoutError. Passing zero timeout disables this.", + "returnComment": "Promise that resolves when the element is successfully unchecked.", "required": true, "templates": [], "args": { @@ -9137,11 +9237,125 @@ } } }, + "waitForElementState": { + "kind": "method", + "name": "waitForElementState", + "type": { + "name": "Promise", + "properties": {} + }, + "comment": "Depending on the `state` parameter, this method waits for one of the actionability checks to pass. This method throws when the element is detached while waiting, unless waiting for the `\"hidden\"` state.\n\n`\"visible\"` Wait until the element is visible.\n`\"hidden\"` Wait until the element is not visible or not attached. Note that waiting for hidden does not throw when the element detaches.\n`\"stable\"` Wait until the element is both visible and stable.\n`\"enabled\"` Wait until the element is enabled.\n`\"disabled\"` Wait until the element is not enabled.\n\nIf the element does not satisfy the condition for the `timeout` milliseconds, this method will throw.", + "returnComment": "Promise that resolves when the element satisfies the `state`.", + "required": true, + "templates": [], + "args": { + "state": { + "kind": "property", + "name": "state", + "type": { + "name": "\"disabled\"|\"enabled\"|\"hidden\"|\"stable\"|\"visible\"", + "properties": {} + }, + "comment": "A state to wait for, see below for more details.", + "returnComment": "", + "required": true, + "templates": [] + }, + "options": { + "kind": "property", + "name": "options", + "type": { + "name": "Object", + "properties": { + "timeout": { + "kind": "property", + "name": "timeout", + "type": { + "name": "number", + "properties": {} + }, + "comment": "Maximum time in milliseconds, defaults to 30 seconds, pass `0` to disable timeout. The default value can be changed by using the browserContext.setDefaultTimeout(timeout) or page.setDefaultTimeout(timeout) methods.", + "returnComment": "", + "required": false, + "templates": [] + } + } + }, + "comment": "", + "returnComment": "", + "required": false, + "templates": [] + } + } + }, + "waitForSelector": { + "kind": "method", + "name": "waitForSelector", + "type": { + "name": "Promise", + "properties": {} + }, + "comment": "Wait for the `selector` relative to the element handle to satisfy `state` option (either appear/disappear from dom, or become visible/hidden). If at the moment of calling the method `selector` already satisfies the condition, the method will return immediately. If the selector doesn't satisfy the condition for the `timeout` milliseconds, the function will throw.\n```js\nawait page.setContent(`
`);\nconst div = await page.$('div');\n// Waiting for the 'span' selector relative to the div.\nconst span = await div.waitForSelector('span', { state: 'attached' });\n```\n\n**NOTE** This method does not work across navigations, use page.waitForSelector(selector[, options]) instead.", + "returnComment": "Promise that resolves when element specified by selector satisfies `state` option. Resolves to `null` if waiting for `hidden` or `detached`.", + "required": true, + "templates": [], + "args": { + "selector": { + "kind": "property", + "name": "selector", + "type": { + "name": "string", + "properties": {} + }, + "comment": "A selector of an element to wait for, relative to the element handle. See working with selectors for more details.", + "returnComment": "", + "required": true, + "templates": [] + }, + "options": { + "kind": "property", + "name": "options", + "type": { + "name": "Object", + "properties": { + "state": { + "kind": "property", + "name": "state", + "type": { + "name": "\"attached\"|\"detached\"|\"hidden\"|\"visible\"", + "properties": {} + }, + "comment": "Defaults to `'visible'`. Can be either:\n - `'attached'` - wait for element to be present in DOM.\n - `'detached'` - wait for element to not be present in DOM.\n - `'visible'` - wait for element to have non-empty bounding box and no `visibility:hidden`. Note that element without any content or with `display:none` has an empty bounding box and is not considered visible.\n - `'hidden'` - wait for element to be either detached from DOM, or have an empty bounding box or `visibility:hidden`. This is opposite to the `'visible'` option.", + "returnComment": "", + "required": false, + "templates": [] + }, + "timeout": { + "kind": "property", + "name": "timeout", + "type": { + "name": "number", + "properties": {} + }, + "comment": "Maximum time in milliseconds, defaults to 30 seconds, pass `0` to disable timeout. The default value can be changed by using the browserContext.setDefaultTimeout(timeout) or page.setDefaultTimeout(timeout) methods.", + "returnComment": "", + "required": false, + "templates": [] + } + } + }, + "comment": "", + "returnComment": "", + "required": false, + "templates": [] + } + } + }, "asElement": { "kind": "method", "name": "asElement", "type": { - "name": "?ElementHandle", + "name": "null|ElementHandle", "properties": {} }, "comment": "Returns either `null` or the object handle itself, if the object handle is an instance of ElementHandle.", @@ -9179,7 +9393,7 @@ "kind": "property", "name": "pageFunction", "type": { - "name": "function(Object)", + "name": "function", "properties": {} }, "comment": "Function to be evaluated in browser context", @@ -9282,7 +9496,7 @@ "kind": "method", "name": "jsonValue", "type": { - "name": "Promise", + "name": "Promise", "properties": {} }, "comment": "Returns a JSON representation of the object. If the object has a\n`toJSON`\nfunction, it **will not be called**.\n\n**NOTE** The method will return an empty JSON object if the referenced object is not stringifiable. It will throw an error if the object has circular references.", @@ -9300,7 +9514,7 @@ "kind": "method", "name": "asElement", "type": { - "name": "?ElementHandle", + "name": "null|ElementHandle", "properties": {} }, "comment": "Returns either `null` or the object handle itself, if the object handle is an instance of ElementHandle.", @@ -9338,7 +9552,7 @@ "kind": "property", "name": "pageFunction", "type": { - "name": "function(Object)", + "name": "function", "properties": {} }, "comment": "Function to be evaluated in browser context", @@ -9441,7 +9655,7 @@ "kind": "method", "name": "jsonValue", "type": { - "name": "Promise", + "name": "Promise", "properties": {} }, "comment": "Returns a JSON representation of the object. If the object has a\n`toJSON`\nfunction, it **will not be called**.\n\n**NOTE** The method will return an empty JSON object if the referenced object is not stringifiable. It will throw an error if the object has circular references.", @@ -10116,7 +10330,7 @@ "kind": "property", "name": "button", "type": { - "name": "\"left\"|\"right\"|\"middle\"", + "name": "\"left\"|\"middle\"|\"right\"", "properties": {} }, "comment": "Defaults to `left`.", @@ -10203,7 +10417,7 @@ "kind": "property", "name": "button", "type": { - "name": "\"left\"|\"right\"|\"middle\"", + "name": "\"left\"|\"middle\"|\"right\"", "properties": {} }, "comment": "Defaults to `left`.", @@ -10254,7 +10468,7 @@ "kind": "property", "name": "button", "type": { - "name": "\"left\"|\"right\"|\"middle\"", + "name": "\"left\"|\"middle\"|\"right\"", "properties": {} }, "comment": "Defaults to `left`.", @@ -10368,7 +10582,7 @@ "kind": "property", "name": "button", "type": { - "name": "\"left\"|\"right\"|\"middle\"", + "name": "\"left\"|\"middle\"|\"right\"", "properties": {} }, "comment": "Defaults to `left`.", @@ -10406,7 +10620,7 @@ "kind": "method", "name": "failure", "type": { - "name": "?Object", + "name": "null|Object", "properties": { "errorText": { "kind": "property", @@ -10484,7 +10698,7 @@ "kind": "method", "name": "postData", "type": { - "name": "?string", + "name": "null|string", "properties": {} }, "comment": "", @@ -10497,7 +10711,7 @@ "kind": "method", "name": "postDataBuffer", "type": { - "name": "?Buffer", + "name": "null|Buffer", "properties": {} }, "comment": "", @@ -10510,7 +10724,7 @@ "kind": "method", "name": "postDataJSON", "type": { - "name": "?Object", + "name": "null|Object", "properties": {} }, "comment": "When the response is `application/x-www-form-urlencoded` then a key/value object of the values will be returned. Otherwise it will be parsed as JSON.", @@ -10523,7 +10737,7 @@ "kind": "method", "name": "redirectedFrom", "type": { - "name": "?Request", + "name": "null|Request", "properties": {} }, "comment": "When the server responds with a redirect, Playwright creates a new Request object. The two requests are connected by `redirectedFrom()` and `redirectedTo()` methods. When multiple server redirects has happened, it is possible to construct the whole redirect chain by repeatedly calling `redirectedFrom()`.\nFor example, if the website `http://example.com` redirects to `https://example.com`:\n```js\nconst response = await page.goto('http://example.com');\nconsole.log(response.request().redirectedFrom().url()); // 'http://example.com'\n```\nIf the website `https://google.com` has no redirects:\n```js\nconst response = await page.goto('https://google.com');\nconsole.log(response.request().redirectedFrom()); // null\n```", @@ -10536,7 +10750,7 @@ "kind": "method", "name": "redirectedTo", "type": { - "name": "?Request", + "name": "null|Request", "properties": {} }, "comment": "This method is the opposite of request.redirectedFrom():\n```js\nconsole.log(request.redirectedFrom().redirectedTo() === request); // true\n```", @@ -10562,7 +10776,7 @@ "kind": "method", "name": "response", "type": { - "name": "Promise", + "name": "Promise", "properties": {} }, "comment": "", @@ -10606,7 +10820,7 @@ "kind": "method", "name": "finished", "type": { - "name": "Promise", + "name": "Promise", "properties": {} }, "comment": "", @@ -10645,7 +10859,7 @@ "kind": "method", "name": "json", "type": { - "name": "Promise", + "name": "Promise", "properties": {} }, "comment": "This method will throw if the response body is not parsable via `JSON.parse`.", @@ -10863,7 +11077,7 @@ "name": "Promise", "properties": {} }, - "comment": "Continues route's request with optional overrides.\n```js\nawait page.route('**/*', (route, request) => {\n // Override headers\n const headers = Object.assign({}, request.headers(), {\n foo: 'bar', // set \"foo\" header\n origin: undefined, // remove \"origin\" header\n });\n route.continue({headers});\n});\n```", + "comment": "Continues route's request with optional overrides.\n```js\nawait page.route('**/*', (route, request) => {\n // Override headers\n const headers = {\n ...request.headers(),\n foo: 'bar', // set \"foo\" header\n origin: undefined, // remove \"origin\" header\n };\n route.continue({headers});\n});\n```", "returnComment": "", "required": true, "templates": [], @@ -11032,7 +11246,7 @@ "kind": "method", "name": "snapshot", "type": { - "name": "Promise", + "name": "Promise", "properties": { "role": { "kind": "property", @@ -11788,6 +12002,18 @@ "required": false, "templates": [] }, + "_videosPath": { + "kind": "property", + "name": "_videosPath", + "type": { + "name": "string", + "properties": {} + }, + "comment": "**experimental** If specified, recorded videos are saved into this folder. Otherwise, temporary folder is created and is deleted when browser is closed.", + "returnComment": "", + "required": false, + "templates": [] + }, "chromiumSandbox": { "kind": "property", "name": "chromiumSandbox", @@ -11804,7 +12030,7 @@ "kind": "property", "name": "firefoxUserPrefs", "type": { - "name": "Object", + "name": "Object", "properties": {} }, "comment": "Firefox user preferences. Learn more about the Firefox user preferences at `about:config`.", @@ -12216,7 +12442,7 @@ "kind": "property", "name": "viewport", "type": { - "name": "?Object", + "name": "null|Object", "properties": { "width": { "kind": "property", @@ -12459,13 +12685,62 @@ "kind": "property", "name": "colorScheme", "type": { - "name": "\"light\"|\"dark\"|\"no-preference\"", + "name": "\"dark\"|\"light\"|\"no-preference\"", "properties": {} }, "comment": "Emulates `'prefers-colors-scheme'` media feature, supported values are `'light'`, `'dark'`, `'no-preference'`. See page.emulateMedia(options) for more details. Defaults to '`light`'.", "returnComment": "", "required": false, "templates": [] + }, + "_videosPath": { + "kind": "property", + "name": "_videosPath", + "type": { + "name": "string", + "properties": {} + }, + "comment": "**experimental** If specified, recorded videos are saved into this folder. Otherwise, temporary folder is created and is deleted when browser is closed.", + "returnComment": "", + "required": false, + "templates": [] + }, + "_recordVideos": { + "kind": "property", + "name": "_recordVideos", + "type": { + "name": "Object", + "properties": { + "width": { + "kind": "property", + "name": "width", + "type": { + "name": "number", + "properties": {} + }, + "comment": "Video frame width.", + "returnComment": "", + "required": true, + "templates": [] + }, + "height": { + "kind": "property", + "name": "height", + "type": { + "name": "number", + "properties": {} + }, + "comment": "Video frame height.", + "returnComment": "", + "required": true, + "templates": [] + } + } + }, + "comment": "**experimental** Enables automatic video recording for the new page. The video will have frames with the provided dimensions. Actual picture of the page will be scaled down if necessary to fit specified size.", + "returnComment": "", + "required": false, + "templates": [] } } }, @@ -12627,6 +12902,18 @@ "required": false, "templates": [] }, + "_videosPath": { + "kind": "property", + "name": "_videosPath", + "type": { + "name": "string", + "properties": {} + }, + "comment": "**experimental** If specified, recorded videos are saved into this folder. Otherwise, temporary folder is created and is deleted when browser is closed.", + "returnComment": "", + "required": false, + "templates": [] + }, "chromiumSandbox": { "kind": "property", "name": "chromiumSandbox", @@ -12643,7 +12930,7 @@ "kind": "property", "name": "firefoxUserPrefs", "type": { - "name": "Object", + "name": "Object", "properties": {} }, "comment": "Firefox user preferences. Learn more about the Firefox user preferences at `about:config`.", @@ -12790,7 +13077,7 @@ "kind": "property", "name": "severity", "type": { - "name": "\"verbose\"|\"info\"|\"warning\"|\"error\"", + "name": "\"error\"|\"info\"|\"verbose\"|\"warning\"", "properties": {} }, "comment": "", @@ -12825,7 +13112,7 @@ "kind": "property", "name": "severity", "type": { - "name": "\"verbose\"|\"info\"|\"warning\"|\"error\"", + "name": "\"error\"|\"info\"|\"verbose\"|\"warning\"", "properties": {} }, "comment": "", @@ -13097,7 +13384,7 @@ "kind": "property", "name": "viewport", "type": { - "name": "?Object", + "name": "null|Object", "properties": { "width": { "kind": "property", @@ -13340,7 +13627,7 @@ "kind": "property", "name": "colorScheme", "type": { - "name": "\"light\"|\"dark\"|\"no-preference\"", + "name": "\"dark\"|\"light\"|\"no-preference\"", "properties": {} }, "comment": "Emulates `'prefers-colors-scheme'` media feature, supported values are `'light'`, `'dark'`, `'no-preference'`. See page.emulateMedia(options) for more details. Defaults to '`light`'.", @@ -13359,6 +13646,43 @@ "returnComment": "", "required": false, "templates": [] + }, + "_recordVideos": { + "kind": "property", + "name": "_recordVideos", + "type": { + "name": "Object", + "properties": { + "width": { + "kind": "property", + "name": "width", + "type": { + "name": "number", + "properties": {} + }, + "comment": "Video frame width.", + "returnComment": "", + "required": true, + "templates": [] + }, + "height": { + "kind": "property", + "name": "height", + "type": { + "name": "number", + "properties": {} + }, + "comment": "Video frame height.", + "returnComment": "", + "required": true, + "templates": [] + } + } + }, + "comment": "**experimental** Enables automatic video recording for new pages. The video will have frames with the provided dimensions. Actual picture of the page will be scaled down if necessary to fit specified size.", + "returnComment": "", + "required": false, + "templates": [] } } }, @@ -13427,7 +13751,7 @@ "kind": "property", "name": "viewport", "type": { - "name": "?Object", + "name": "null|Object", "properties": { "width": { "kind": "property", @@ -13670,7 +13994,7 @@ "kind": "property", "name": "colorScheme", "type": { - "name": "\"light\"|\"dark\"|\"no-preference\"", + "name": "\"dark\"|\"light\"|\"no-preference\"", "properties": {} }, "comment": "Emulates `'prefers-colors-scheme'` media feature, supported values are `'light'`, `'dark'`, `'no-preference'`. See page.emulateMedia(options) for more details. Defaults to '`light`'.", @@ -13689,6 +14013,43 @@ "returnComment": "", "required": false, "templates": [] + }, + "_recordVideos": { + "kind": "property", + "name": "_recordVideos", + "type": { + "name": "Object", + "properties": { + "width": { + "kind": "property", + "name": "width", + "type": { + "name": "number", + "properties": {} + }, + "comment": "Video frame width.", + "returnComment": "", + "required": true, + "templates": [] + }, + "height": { + "kind": "property", + "name": "height", + "type": { + "name": "number", + "properties": {} + }, + "comment": "Video frame height.", + "returnComment": "", + "required": true, + "templates": [] + } + } + }, + "comment": "**experimental** Enables automatic video recording for the new page. The video will have frames with the provided dimensions. Actual picture of the page will be scaled down if necessary to fit specified size.", + "returnComment": "", + "required": false, + "templates": [] } } }, @@ -13939,7 +14300,7 @@ "kind": "property", "name": "sameSite", "type": { - "name": "\"Strict\"|\"Lax\"|\"None\"", + "name": "\"Lax\"|\"None\"|\"Strict\"", "properties": {} }, "comment": "", @@ -14139,7 +14500,7 @@ "kind": "property", "name": "sameSite", "type": { - "name": "\"Strict\"|\"Lax\"|\"None\"", + "name": "\"Lax\"|\"None\"|\"Strict\"", "properties": {} }, "comment": "", @@ -14447,7 +14808,7 @@ "kind": "property", "name": "geolocation", "type": { - "name": "?Object", + "name": "null|Object", "properties": { "latitude": { "kind": "property", @@ -14501,7 +14862,7 @@ "name": "Promise", "properties": {} }, - "comment": "Provide credentials for HTTP authentication.\n\n**NOTE** Browsers may cache credentials that resulted in successful auth. That means passing different credentials after successful authentication or passing `null` to disable authentication is unreliable. Instead, create a separate browser context that will not have previous credentials cached.", + "comment": "Provide credentials for HTTP authentication.\n\n**NOTE** Browsers may cache credentials after successful authentication. Passing different credentials or passing `null` to disable authentication will be unreliable. To remove or replace credentials, create a new browser context instead.", "returnComment": "", "required": true, "templates": [], @@ -14510,7 +14871,7 @@ "kind": "property", "name": "httpCredentials", "type": { - "name": "?Object", + "name": "null|Object", "properties": { "username": { "kind": "property", @@ -15146,7 +15507,7 @@ "kind": "property", "name": "viewport", "type": { - "name": "?Object", + "name": "null|Object", "properties": { "width": { "kind": "property", @@ -15389,7 +15750,7 @@ "kind": "property", "name": "colorScheme", "type": { - "name": "\"light\"|\"dark\"|\"no-preference\"", + "name": "\"dark\"|\"light\"|\"no-preference\"", "properties": {} }, "comment": "Emulates `'prefers-colors-scheme'` media feature, supported values are `'light'`, `'dark'`, `'no-preference'`. See page.emulateMedia(options) for more details. Defaults to '`light`'.", @@ -15408,6 +15769,43 @@ "returnComment": "", "required": false, "templates": [] + }, + "_recordVideos": { + "kind": "property", + "name": "_recordVideos", + "type": { + "name": "Object", + "properties": { + "width": { + "kind": "property", + "name": "width", + "type": { + "name": "number", + "properties": {} + }, + "comment": "Video frame width.", + "returnComment": "", + "required": true, + "templates": [] + }, + "height": { + "kind": "property", + "name": "height", + "type": { + "name": "number", + "properties": {} + }, + "comment": "Video frame height.", + "returnComment": "", + "required": true, + "templates": [] + } + } + }, + "comment": "**experimental** Enables automatic video recording for new pages. The video will have frames with the provided dimensions. Actual picture of the page will be scaled down if necessary to fit specified size.", + "returnComment": "", + "required": false, + "templates": [] } } }, @@ -15476,7 +15874,7 @@ "kind": "property", "name": "viewport", "type": { - "name": "?Object", + "name": "null|Object", "properties": { "width": { "kind": "property", @@ -15719,7 +16117,7 @@ "kind": "property", "name": "colorScheme", "type": { - "name": "\"light\"|\"dark\"|\"no-preference\"", + "name": "\"dark\"|\"light\"|\"no-preference\"", "properties": {} }, "comment": "Emulates `'prefers-colors-scheme'` media feature, supported values are `'light'`, `'dark'`, `'no-preference'`. See page.emulateMedia(options) for more details. Defaults to '`light`'.", @@ -15738,6 +16136,43 @@ "returnComment": "", "required": false, "templates": [] + }, + "_recordVideos": { + "kind": "property", + "name": "_recordVideos", + "type": { + "name": "Object", + "properties": { + "width": { + "kind": "property", + "name": "width", + "type": { + "name": "number", + "properties": {} + }, + "comment": "Video frame width.", + "returnComment": "", + "required": true, + "templates": [] + }, + "height": { + "kind": "property", + "name": "height", + "type": { + "name": "number", + "properties": {} + }, + "comment": "Video frame height.", + "returnComment": "", + "required": true, + "templates": [] + } + } + }, + "comment": "**experimental** Enables automatic video recording for the new page. The video will have frames with the provided dimensions. Actual picture of the page will be scaled down if necessary to fit specified size.", + "returnComment": "", + "required": false, + "templates": [] } } }, @@ -15873,7 +16308,7 @@ "kind": "property", "name": "viewport", "type": { - "name": "?Object", + "name": "null|Object", "properties": { "width": { "kind": "property", @@ -16116,7 +16551,7 @@ "kind": "property", "name": "colorScheme", "type": { - "name": "\"light\"|\"dark\"|\"no-preference\"", + "name": "\"dark\"|\"light\"|\"no-preference\"", "properties": {} }, "comment": "Emulates `'prefers-colors-scheme'` media feature, supported values are `'light'`, `'dark'`, `'no-preference'`. See page.emulateMedia(options) for more details. Defaults to '`light`'.", @@ -16135,6 +16570,43 @@ "returnComment": "", "required": false, "templates": [] + }, + "_recordVideos": { + "kind": "property", + "name": "_recordVideos", + "type": { + "name": "Object", + "properties": { + "width": { + "kind": "property", + "name": "width", + "type": { + "name": "number", + "properties": {} + }, + "comment": "Video frame width.", + "returnComment": "", + "required": true, + "templates": [] + }, + "height": { + "kind": "property", + "name": "height", + "type": { + "name": "number", + "properties": {} + }, + "comment": "Video frame height.", + "returnComment": "", + "required": true, + "templates": [] + } + } + }, + "comment": "**experimental** Enables automatic video recording for new pages. The video will have frames with the provided dimensions. Actual picture of the page will be scaled down if necessary to fit specified size.", + "returnComment": "", + "required": false, + "templates": [] } } }, @@ -16203,7 +16675,7 @@ "kind": "property", "name": "viewport", "type": { - "name": "?Object", + "name": "null|Object", "properties": { "width": { "kind": "property", @@ -16446,7 +16918,7 @@ "kind": "property", "name": "colorScheme", "type": { - "name": "\"light\"|\"dark\"|\"no-preference\"", + "name": "\"dark\"|\"light\"|\"no-preference\"", "properties": {} }, "comment": "Emulates `'prefers-colors-scheme'` media feature, supported values are `'light'`, `'dark'`, `'no-preference'`. See page.emulateMedia(options) for more details. Defaults to '`light`'.", @@ -16465,6 +16937,43 @@ "returnComment": "", "required": false, "templates": [] + }, + "_recordVideos": { + "kind": "property", + "name": "_recordVideos", + "type": { + "name": "Object", + "properties": { + "width": { + "kind": "property", + "name": "width", + "type": { + "name": "number", + "properties": {} + }, + "comment": "Video frame width.", + "returnComment": "", + "required": true, + "templates": [] + }, + "height": { + "kind": "property", + "name": "height", + "type": { + "name": "number", + "properties": {} + }, + "comment": "Video frame height.", + "returnComment": "", + "required": true, + "templates": [] + } + } + }, + "comment": "**experimental** Enables automatic video recording for the new page. The video will have frames with the provided dimensions. Actual picture of the page will be scaled down if necessary to fit specified size.", + "returnComment": "", + "required": false, + "templates": [] } } }, diff --git a/driver/package.json b/driver/package.json index 0f4683b1f..8e8faab20 100644 --- a/driver/package.json +++ b/driver/package.json @@ -13,7 +13,7 @@ }, "license": "Apache-2.0", "dependencies": { - "playwright": "1.4.0" + "playwright": "1.4.2" }, "devDependencies": { "pkg": "^4.4.9" diff --git a/playwright/async_api.py b/playwright/async_api.py index 54bc893fb..b9f0ddd1d 100644 --- a/playwright/async_api.py +++ b/playwright/async_api.py @@ -585,7 +585,7 @@ async def move(self, x: float, y: float, steps: int = None) -> NoneType: return mapping.from_maybe_impl(await self._impl_obj.move(x=x, y=y, steps=steps)) async def down( - self, button: Literal["left", "right", "middle"] = None, clickCount: int = None + self, button: Literal["left", "middle", "right"] = None, clickCount: int = None ) -> NoneType: """Mouse.down @@ -593,7 +593,7 @@ async def down( Parameters ---------- - button : Optional[Literal['left', 'right', 'middle']] + button : Optional[Literal['left', 'middle', 'right']] Defaults to `left`. clickCount : Optional[int] defaults to 1. See UIEvent.detail. @@ -603,7 +603,7 @@ async def down( ) async def up( - self, button: Literal["left", "right", "middle"] = None, clickCount: int = None + self, button: Literal["left", "middle", "right"] = None, clickCount: int = None ) -> NoneType: """Mouse.up @@ -611,7 +611,7 @@ async def up( Parameters ---------- - button : Optional[Literal['left', 'right', 'middle']] + button : Optional[Literal['left', 'middle', 'right']] Defaults to `left`. clickCount : Optional[int] defaults to 1. See UIEvent.detail. @@ -625,7 +625,7 @@ async def click( x: float, y: float, delay: int = None, - button: Literal["left", "right", "middle"] = None, + button: Literal["left", "middle", "right"] = None, clickCount: int = None, ) -> NoneType: """Mouse.click @@ -638,7 +638,7 @@ async def click( y : float delay : Optional[int] Time to wait between `mousedown` and `mouseup` in milliseconds. Defaults to 0. - button : Optional[Literal['left', 'right', 'middle']] + button : Optional[Literal['left', 'middle', 'right']] Defaults to `left`. clickCount : Optional[int] defaults to 1. See UIEvent.detail. @@ -654,7 +654,7 @@ async def dblclick( x: float, y: float, delay: int = None, - button: Literal["left", "right", "middle"] = None, + button: Literal["left", "middle", "right"] = None, ) -> NoneType: """Mouse.dblclick @@ -666,7 +666,7 @@ async def dblclick( y : float delay : Optional[int] Time to wait between `mousedown` and `mouseup` in milliseconds. Defaults to 0. - button : Optional[Literal['left', 'right', 'middle']] + button : Optional[Literal['left', 'middle', 'right']] Defaults to `left`. """ return mapping.from_maybe_impl( @@ -952,8 +952,15 @@ async def hover( ) -> NoneType: """ElementHandle.hover - This method waits for actionability checks, then scrolls the element into view if needed and uses page.mouse to hover over the center of the element. - If the element is detached from DOM, the method throws an error. + This method hovers over the element by performing the following steps: + + Wait for actionability checks on the element, unless `force` option is set. + Scroll the element into view if needed. + Use page.mouse to hover over the center of the element, or the specified `position`. + Wait for initiated navigations to either succeed or fail, unless `noWaitAfter` option is set. + + If the element is detached from the DOM at any moment during the action, this method rejects. + When all steps combined have not finished during the specified `timeout`, this method rejects with a TimeoutError. Passing zero timeout disables this. Parameters ---------- @@ -979,7 +986,7 @@ async def click( ] = None, position: MousePosition = None, delay: int = None, - button: Literal["left", "right", "middle"] = None, + button: Literal["left", "middle", "right"] = None, clickCount: int = None, timeout: int = None, force: bool = None, @@ -987,8 +994,15 @@ async def click( ) -> NoneType: """ElementHandle.click - This method waits for actionability checks, then scrolls the element into view if needed and uses page.mouse to click in the center of the element. - If the element is detached from DOM, the method throws an error. + This method clicks the element by performing the following steps: + + Wait for actionability checks on the element, unless `force` option is set. + Scroll the element into view if needed. + Use page.mouse to click in the center of the element, or the specified `position`. + Wait for initiated navigations to either succeed or fail, unless `noWaitAfter` option is set. + + If the element is detached from the DOM at any moment during the action, this method rejects. + When all steps combined have not finished during the specified `timeout`, this method rejects with a TimeoutError. Passing zero timeout disables this. Parameters ---------- @@ -998,7 +1012,7 @@ async def click( A point to click relative to the top-left corner of element padding box. If not specified, clicks to some visible point of the element. delay : Optional[int] Time to wait between `mousedown` and `mouseup` in milliseconds. Defaults to 0. - button : Optional[Literal['left', 'right', 'middle']] + button : Optional[Literal['left', 'middle', 'right']] Defaults to `left`. clickCount : Optional[int] defaults to 1. See UIEvent.detail. @@ -1029,16 +1043,22 @@ async def dblclick( ] = None, position: MousePosition = None, delay: int = None, - button: Literal["left", "right", "middle"] = None, + button: Literal["left", "middle", "right"] = None, timeout: int = None, force: bool = None, noWaitAfter: bool = None, ) -> NoneType: """ElementHandle.dblclick - This method waits for actionability checks, then scrolls the element into view if needed and uses page.mouse to double click in the center of the element. - If the element is detached from DOM, the method throws an error. - Bear in mind that if the first click of the `dblclick()` triggers a navigation event, there will be an exception. + This method double clicks the element by performing the following steps: + + Wait for actionability checks on the element, unless `force` option is set. + Scroll the element into view if needed. + Use page.mouse to double click in the center of the element, or the specified `position`. + Wait for initiated navigations to either succeed or fail, unless `noWaitAfter` option is set. Note that if the first click of the `dblclick()` triggers a navigation event, this method will reject. + + If the element is detached from the DOM at any moment during the action, this method rejects. + When all steps combined have not finished during the specified `timeout`, this method rejects with a TimeoutError. Passing zero timeout disables this. **NOTE** `elementHandle.dblclick()` dispatches two `click` events and a single `dblclick` event. @@ -1050,7 +1070,7 @@ async def dblclick( A point to double click relative to the top-left corner of element padding box. If not specified, double clicks to some visible point of the element. delay : Optional[int] Time to wait between `mousedown` and `mouseup` in milliseconds. Defaults to 0. - button : Optional[Literal['left', 'right', 'middle']] + button : Optional[Literal['left', 'middle', 'right']] Defaults to `left`. timeout : Optional[int] Maximum time in milliseconds, defaults to 30 seconds, pass `0` to disable timeout. The default value can be changed by using the browserContext.setDefaultTimeout(timeout) or page.setDefaultTimeout(timeout) methods. @@ -1249,7 +1269,17 @@ async def check( ) -> NoneType: """ElementHandle.check - This method waits for actionability checks. Then, if the element is not already checked, this method scrolls the element into view and uses elementHandle.click to click in the center of the element. + This method checks the element by performing the following steps: + + Ensure that element is a checkbox or a radio input. If not, this method rejects. If the element is already checked, this method returns immediately. + Wait for actionability checks on the element, unless `force` option is set. + Scroll the element into view if needed. + Use page.mouse to click in the center of the element. + Wait for initiated navigations to either succeed or fail, unless `noWaitAfter` option is set. + Ensure that the element is now checked. If not, this method rejects. + + If the element is detached from the DOM at any moment during the action, this method rejects. + When all steps combined have not finished during the specified `timeout`, this method rejects with a TimeoutError. Passing zero timeout disables this. Parameters ---------- @@ -1271,7 +1301,17 @@ async def uncheck( ) -> NoneType: """ElementHandle.uncheck - This method waits for actionability checks. Then, if the element is not already unchecked, this method scrolls the element into view and uses elementHandle.click to click in the center of the element. + This method checks the element by performing the following steps: + + Ensure that element is a checkbox or a radio input. If not, this method rejects. If the element is already unchecked, this method returns immediately. + Wait for actionability checks on the element, unless `force` option is set. + Scroll the element into view if needed. + Use page.mouse to click in the center of the element. + Wait for initiated navigations to either succeed or fail, unless `noWaitAfter` option is set. + Ensure that the element is now unchecked. If not, this method rejects. + + If the element is detached from the DOM at any moment during the action, this method rejects. + When all steps combined have not finished during the specified `timeout`, this method rejects with a TimeoutError. Passing zero timeout disables this. Parameters ---------- @@ -1302,7 +1342,7 @@ async def boundingBox(self) -> typing.Union[FloatRect, NoneType]: async def screenshot( self, timeout: int = None, - type: Literal["png", "jpeg"] = None, + type: Literal["jpeg", "png"] = None, path: typing.Union[str, pathlib.Path] = None, quality: int = None, omitBackground: bool = None, @@ -1315,7 +1355,7 @@ async def screenshot( ---------- timeout : Optional[int] Maximum time in milliseconds, defaults to 30 seconds, pass `0` to disable timeout. The default value can be changed by using the browserContext.setDefaultTimeout(timeout) or page.setDefaultTimeout(timeout) methods. - type : Optional[Literal['png', 'jpeg']] + type : Optional[Literal['jpeg', 'png']] Specify screenshot type, defaults to `png`. path : Union[str, pathlib.Path, NoneType] The file path to save the image to. The screenshot type will be inferred from file extension. If `path` is a relative path, then it is resolved relative to current working directory. If no path is provided, the image won't be saved to the disk. @@ -1459,6 +1499,70 @@ async def evalOnSelectorAll( ) ) + async def waitForElementState( + self, + state: Literal["disabled", "enabled", "hidden", "stable", "visible"], + timeout: int = None, + ) -> NoneType: + """ElementHandle.waitForElementState + + Depending on the `state` parameter, this method waits for one of the actionability checks to pass. This method throws when the element is detached while waiting, unless waiting for the `"hidden"` state. + + `"visible"` Wait until the element is visible. + `"hidden"` Wait until the element is not visible or not attached. Note that waiting for hidden does not throw when the element detaches. + `"stable"` Wait until the element is both visible and stable. + `"enabled"` Wait until the element is enabled. + `"disabled"` Wait until the element is not enabled. + + If the element does not satisfy the condition for the `timeout` milliseconds, this method will throw. + + Parameters + ---------- + state : Literal['disabled', 'enabled', 'hidden', 'stable', 'visible'] + A state to wait for, see below for more details. + timeout : Optional[int] + Maximum time in milliseconds, defaults to 30 seconds, pass `0` to disable timeout. The default value can be changed by using the browserContext.setDefaultTimeout(timeout) or page.setDefaultTimeout(timeout) methods. + """ + return mapping.from_maybe_impl( + await self._impl_obj.waitForElementState(state=state, timeout=timeout) + ) + + async def waitForSelector( + self, + selector: str, + state: Literal["attached", "detached", "hidden", "visible"] = None, + timeout: int = None, + ) -> typing.Union["ElementHandle", NoneType]: + """ElementHandle.waitForSelector + + Wait for the `selector` relative to the element handle to satisfy `state` option (either appear/disappear from dom, or become visible/hidden). If at the moment of calling the method `selector` already satisfies the condition, the method will return immediately. If the selector doesn't satisfy the condition for the `timeout` milliseconds, the function will throw. + + **NOTE** This method does not work across navigations, use page.waitForSelector(selector[, options]) instead. + + Parameters + ---------- + selector : str + A selector of an element to wait for, relative to the element handle. See working with selectors for more details. + state : Optional[Literal['attached', 'detached', 'hidden', 'visible']] + Defaults to `'visible'`. Can be either: + - `'attached'` - wait for element to be present in DOM. + - `'detached'` - wait for element to not be present in DOM. + - `'visible'` - wait for element to have non-empty bounding box and no `visibility:hidden`. Note that element without any content or with `display:none` has an empty bounding box and is not considered visible. + - `'hidden'` - wait for element to be either detached from DOM, or have an empty bounding box or `visibility:hidden`. This is opposite to the `'visible'` option. + timeout : Optional[int] + Maximum time in milliseconds, defaults to 30 seconds, pass `0` to disable timeout. The default value can be changed by using the browserContext.setDefaultTimeout(timeout) or page.setDefaultTimeout(timeout) methods. + + Returns + ------- + Optional[ElementHandle] + Promise that resolves when element specified by selector satisfies `state` option. Resolves to `null` if waiting for `hidden` or `detached`. + """ + return mapping.from_impl_nullable( + await self._impl_obj.waitForSelector( + selector=selector, state=state, timeout=timeout + ) + ) + mapping.register(ElementHandleImpl, ElementHandle) @@ -1625,11 +1729,22 @@ def childFrames(self) -> typing.List["Frame"]: """ return mapping.from_impl_list(self._impl_obj.childFrames) + def page(self) -> "Page": + """Frame.page + + Returns the page containing this frame. + + Returns + ------- + Page + """ + return mapping.from_impl(self._impl_obj.page()) + async def goto( self, url: str, timeout: int = None, - waitUntil: Literal["load", "domcontentloaded", "networkidle"] = None, + waitUntil: Literal["domcontentloaded", "load", "networkidle"] = None, referer: str = None, ) -> typing.Union["Response", NoneType]: """Frame.goto @@ -1654,7 +1769,7 @@ async def goto( URL to navigate frame to. The url should include scheme, e.g. `https://`. timeout : Optional[int] Maximum navigation time in milliseconds, defaults to 30 seconds, pass `0` to disable timeout. The default value can be changed by using the browserContext.setDefaultNavigationTimeout(timeout), browserContext.setDefaultTimeout(timeout), page.setDefaultNavigationTimeout(timeout) or page.setDefaultTimeout(timeout) methods. - waitUntil : Optional[Literal['load', 'domcontentloaded', 'networkidle']] + waitUntil : Optional[Literal['domcontentloaded', 'load', 'networkidle']] When to consider navigation succeeded, defaults to `load`. Events can be either: - `'domcontentloaded'` - consider navigation to be finished when the `DOMContentLoaded` event is fired. - `'load'` - consider navigation to be finished when the `load` event is fired. @@ -1676,7 +1791,7 @@ async def goto( async def waitForNavigation( self, url: typing.Union[str, typing.Pattern, typing.Callable[[str], bool]] = None, - waitUntil: Literal["load", "domcontentloaded", "networkidle"] = None, + waitUntil: Literal["domcontentloaded", "load", "networkidle"] = None, timeout: int = None, ) -> typing.Union["Response", NoneType]: """Frame.waitForNavigation @@ -1689,7 +1804,7 @@ async def waitForNavigation( ---------- url : Union[str, Pattern, typing.Callable[[str], bool], NoneType] URL string, URL regex pattern or predicate receiving URL to match while waiting for the navigation. - waitUntil : Optional[Literal['load', 'domcontentloaded', 'networkidle']] + waitUntil : Optional[Literal['domcontentloaded', 'load', 'networkidle']] When to consider navigation succeeded, defaults to `load`. Events can be either: - `'domcontentloaded'` - consider navigation to be finished when the `DOMContentLoaded` event is fired. - `'load'` - consider navigation to be finished when the `load` event is fired. @@ -1710,7 +1825,7 @@ async def waitForNavigation( async def waitForLoadState( self, - state: Literal["load", "domcontentloaded", "networkidle"] = None, + state: Literal["domcontentloaded", "load", "networkidle"] = None, timeout: int = None, ) -> NoneType: """Frame.waitForLoadState @@ -1719,7 +1834,7 @@ async def waitForLoadState( Parameters ---------- - state : Optional[Literal['load', 'domcontentloaded', 'networkidle']] + state : Optional[Literal['domcontentloaded', 'load', 'networkidle']] Load state to wait for, defaults to `load`. If the state has been already reached while loading current document, the method resolves immediately. - `'load'` - wait for the `load` event to be fired. - `'domcontentloaded'` - wait for the `DOMContentLoaded` event to be fired. @@ -1848,7 +1963,7 @@ async def waitForSelector( self, selector: str, timeout: int = None, - state: Literal["attached", "detached", "visible", "hidden"] = None, + state: Literal["attached", "detached", "hidden", "visible"] = None, ) -> typing.Union["ElementHandle", NoneType]: """Frame.waitForSelector @@ -1861,7 +1976,7 @@ async def waitForSelector( A selector of an element to wait for. See working with selectors for more details. timeout : Optional[int] Maximum time in milliseconds, defaults to 30 seconds, pass `0` to disable timeout. The default value can be changed by using the browserContext.setDefaultTimeout(timeout) or page.setDefaultTimeout(timeout) methods. - state : Optional[Literal['attached', 'detached', 'visible', 'hidden']] + state : Optional[Literal['attached', 'detached', 'hidden', 'visible']] Defaults to `'visible'`. Can be either: - `'attached'` - wait for element to be present in DOM. - `'detached'` - wait for element to not be present in DOM. @@ -2013,7 +2128,7 @@ async def setContent( self, html: str, timeout: int = None, - waitUntil: Literal["load", "domcontentloaded", "networkidle"] = None, + waitUntil: Literal["domcontentloaded", "load", "networkidle"] = None, ) -> NoneType: """Frame.setContent @@ -2023,7 +2138,7 @@ async def setContent( HTML markup to assign to the page. timeout : Optional[int] Maximum time in milliseconds for resources to load, defaults to 30 seconds, pass `0` to disable timeout. The default value can be changed by using the browserContext.setDefaultNavigationTimeout(timeout), browserContext.setDefaultTimeout(timeout), page.setDefaultNavigationTimeout(timeout) or page.setDefaultTimeout(timeout) methods. - waitUntil : Optional[Literal['load', 'domcontentloaded', 'networkidle']] + waitUntil : Optional[Literal['domcontentloaded', 'load', 'networkidle']] When to consider navigation succeeded, defaults to `load`. Events can be either: - `'domcontentloaded'` - consider setting content to be finished when the `DOMContentLoaded` event is fired. - `'load'` - consider setting content to be finished when the `load` event is fired. @@ -2115,7 +2230,7 @@ async def click( ] = None, position: MousePosition = None, delay: int = None, - button: Literal["left", "right", "middle"] = None, + button: Literal["left", "middle", "right"] = None, clickCount: int = None, timeout: int = None, force: bool = None, @@ -2123,8 +2238,15 @@ async def click( ) -> NoneType: """Frame.click - This method waits for an element matching `selector`, waits for actionability checks, then scrolls the element into view if needed and uses page.mouse to click in the center of the element. - If there's no element matching `selector`, the method waits until a matching element appears in the DOM. If the element is detached during the actionability checks, the action is retried. + This method clicks an element matching `selector` by performing the following steps: + + Find an element match matching `selector`. If there is none, wait until a matching element is attached to the DOM. + Wait for actionability checks on the matched element, unless `force` option is set. If the element is detached during the checks, the whole action is retried. + Scroll the element into view if needed. + Use page.mouse to click in the center of the element, or the specified `position`. + Wait for initiated navigations to either succeed or fail, unless `noWaitAfter` option is set. + + When all steps combined have not finished during the specified `timeout`, this method rejects with a TimeoutError. Passing zero timeout disables this. Parameters ---------- @@ -2136,7 +2258,7 @@ async def click( A point to click relative to the top-left corner of element padding box. If not specified, clicks to some visible point of the element. delay : Optional[int] Time to wait between `mousedown` and `mouseup` in milliseconds. Defaults to 0. - button : Optional[Literal['left', 'right', 'middle']] + button : Optional[Literal['left', 'middle', 'right']] Defaults to `left`. clickCount : Optional[int] defaults to 1. See UIEvent.detail. @@ -2169,15 +2291,21 @@ async def dblclick( ] = None, position: MousePosition = None, delay: int = None, - button: Literal["left", "right", "middle"] = None, + button: Literal["left", "middle", "right"] = None, timeout: int = None, force: bool = None, ) -> NoneType: """Frame.dblclick - This method waits for an element matching `selector`, waits for actionability checks, then scrolls the element into view if needed and uses page.mouse to double click in the center of the element. - If there's no element matching `selector`, the method waits until a matching element appears in the DOM. If the element is detached during the actionability checks, the action is retried. - Bear in mind that if the first click of the `dblclick()` triggers a navigation event, there will be an exception. + This method double clicks an element matching `selector` by performing the following steps: + + Find an element match matching `selector`. If there is none, wait until a matching element is attached to the DOM. + Wait for actionability checks on the matched element, unless `force` option is set. If the element is detached during the checks, the whole action is retried. + Scroll the element into view if needed. + Use page.mouse to double click in the center of the element, or the specified `position`. + Wait for initiated navigations to either succeed or fail, unless `noWaitAfter` option is set. Note that if the first click of the `dblclick()` triggers a navigation event, this method will reject. + + When all steps combined have not finished during the specified `timeout`, this method rejects with a TimeoutError. Passing zero timeout disables this. **NOTE** `frame.dblclick()` dispatches two `click` events and a single `dblclick` event. @@ -2191,7 +2319,7 @@ async def dblclick( A point to double click relative to the top-left corner of element padding box. If not specified, double clicks to some visible point of the element. delay : Optional[int] Time to wait between `mousedown` and `mouseup` in milliseconds. Defaults to 0. - button : Optional[Literal['left', 'right', 'middle']] + button : Optional[Literal['left', 'middle', 'right']] Defaults to `left`. timeout : Optional[int] Maximum time in milliseconds, defaults to 30 seconds, pass `0` to disable timeout. The default value can be changed by using the browserContext.setDefaultTimeout(timeout) or page.setDefaultTimeout(timeout) methods. @@ -2354,8 +2482,15 @@ async def hover( ) -> NoneType: """Frame.hover - This method waits for an element matching `selector`, waits for actionability checks, then scrolls the element into view if needed and uses page.mouse to hover over the center of the element. - If there's no element matching `selector`, the method waits until a matching element appears in the DOM. If the element is detached during the actionability checks, the action is retried. + This method hovers over an element matching `selector` by performing the following steps: + + Find an element match matching `selector`. If there is none, wait until a matching element is attached to the DOM. + Wait for actionability checks on the matched element, unless `force` option is set. If the element is detached during the checks, the whole action is retried. + Scroll the element into view if needed. + Use page.mouse to hover over the center of the element, or the specified `position`. + Wait for initiated navigations to either succeed or fail, unless `noWaitAfter` option is set. + + When all steps combined have not finished during the specified `timeout`, this method rejects with a TimeoutError. Passing zero timeout disables this. Parameters ---------- @@ -2544,8 +2679,17 @@ async def check( ) -> NoneType: """Frame.check - This method waits for an element matching `selector`, waits for actionability checks. Then, if the element is not already checked, this method scrolls the element into view and uses elementHandle.click to click in the center of the element. - If there's no element matching `selector`, the method waits until a matching element appears in the DOM. If the element is detached during the actionability checks, the action is retried. + This method checks an element matching `selector` by performing the following steps: + + Find an element match matching `selector`. If there is none, wait until a matching element is attached to the DOM. + Ensure that matched element is a checkbox or a radio input. If not, this method rejects. If the element is already checked, this method returns immediately. + Wait for actionability checks on the matched element, unless `force` option is set. If the element is detached during the checks, the whole action is retried. + Scroll the element into view if needed. + Use page.mouse to click in the center of the element. + Wait for initiated navigations to either succeed or fail, unless `noWaitAfter` option is set. + Ensure that the element is now checked. If not, this method rejects. + + When all steps combined have not finished during the specified `timeout`, this method rejects with a TimeoutError. Passing zero timeout disables this. Parameters ---------- @@ -2573,8 +2717,17 @@ async def uncheck( ) -> NoneType: """Frame.uncheck - This method waits for an element matching `selector`, waits for actionability checks. Then, if the element is not already unchecked, this method scrolls the element into view and uses elementHandle.click to click in the center of the element. - If there's no element matching `selector`, the method waits until a matching element appears in the DOM. If the element is detached during the actionability checks, the action is retried. + This method checks an element matching `selector` by performing the following steps: + + Find an element match matching `selector`. If there is none, wait until a matching element is attached to the DOM. + Ensure that matched element is a checkbox or a radio input. If not, this method rejects. If the element is already unchecked, this method returns immediately. + Wait for actionability checks on the matched element, unless `force` option is set. If the element is detached during the checks, the whole action is retried. + Scroll the element into view if needed. + Use page.mouse to click in the center of the element. + Wait for initiated navigations to either succeed or fail, unless `noWaitAfter` option is set. + Ensure that the element is now unchecked. If not, this method rejects. + + When all steps combined have not finished during the specified `timeout`, this method rejects with a TimeoutError. Passing zero timeout disables this. Parameters ---------- @@ -2662,7 +2815,7 @@ async def title(self) -> str: def expect_load_state( self, - state: Literal["load", "domcontentloaded", "networkidle"] = None, + state: Literal["domcontentloaded", "load", "networkidle"] = None, timeout: int = None, ) -> AsyncEventContextManager[typing.Union["Response", NoneType]]: return AsyncEventContextManager(self._impl_obj.waitForLoadState(state, timeout)) @@ -2670,7 +2823,7 @@ def expect_load_state( def expect_navigation( self, url: typing.Union[str, typing.Pattern, typing.Callable[[str], bool]] = None, - waitUntil: Literal["load", "domcontentloaded", "networkidle"] = None, + waitUntil: Literal["domcontentloaded", "load", "networkidle"] = None, timeout: int = None, ) -> AsyncEventContextManager[typing.Union["Response", NoneType]]: return AsyncEventContextManager( @@ -2831,7 +2984,7 @@ def location(self) -> ConsoleMessageLocation: Returns ------- - {"url": Optional[str], "lineNumber": Optional[int], "columnNumber": Optional[int]} + {"url": str, "lineNumber": int, "columnNumber": int} """ return mapping.from_maybe_impl(self._impl_obj.location) @@ -3201,7 +3354,7 @@ async def waitForSelector( self, selector: str, timeout: int = None, - state: Literal["attached", "detached", "visible", "hidden"] = None, + state: Literal["attached", "detached", "hidden", "visible"] = None, ) -> typing.Union["ElementHandle", NoneType]: """Page.waitForSelector @@ -3216,7 +3369,7 @@ async def waitForSelector( A selector of an element to wait for. See working with selectors for more details. timeout : Optional[int] Maximum time in milliseconds, defaults to 30 seconds, pass `0` to disable timeout. The default value can be changed by using the browserContext.setDefaultTimeout(timeout) or page.setDefaultTimeout(timeout) methods. - state : Optional[Literal['attached', 'detached', 'visible', 'hidden']] + state : Optional[Literal['attached', 'detached', 'hidden', 'visible']] Defaults to `'visible'`. Can be either: - `'attached'` - wait for element to be present in DOM. - `'detached'` - wait for element to not be present in DOM. @@ -3564,7 +3717,7 @@ async def setContent( self, html: str, timeout: int = None, - waitUntil: Literal["load", "domcontentloaded", "networkidle"] = None, + waitUntil: Literal["domcontentloaded", "load", "networkidle"] = None, ) -> NoneType: """Page.setContent @@ -3574,7 +3727,7 @@ async def setContent( HTML markup to assign to the page. timeout : Optional[int] Maximum time in milliseconds for resources to load, defaults to 30 seconds, pass `0` to disable timeout. The default value can be changed by using the browserContext.setDefaultNavigationTimeout(timeout), browserContext.setDefaultTimeout(timeout), page.setDefaultNavigationTimeout(timeout) or page.setDefaultTimeout(timeout) methods. - waitUntil : Optional[Literal['load', 'domcontentloaded', 'networkidle']] + waitUntil : Optional[Literal['domcontentloaded', 'load', 'networkidle']] When to consider setting markup succeeded, defaults to `load`. Given an array of event strings, setting content is considered to be successful after all events have been fired. Events can be either: - `'load'` - consider setting content to be finished when the `load` event is fired. - `'domcontentloaded'` - consider setting content to be finished when the `DOMContentLoaded` event is fired. @@ -3590,7 +3743,7 @@ async def goto( self, url: str, timeout: int = None, - waitUntil: Literal["load", "domcontentloaded", "networkidle"] = None, + waitUntil: Literal["domcontentloaded", "load", "networkidle"] = None, referer: str = None, ) -> typing.Union["Response", NoneType]: """Page.goto @@ -3617,7 +3770,7 @@ async def goto( URL to navigate page to. The url should include scheme, e.g. `https://`. timeout : Optional[int] Maximum navigation time in milliseconds, defaults to 30 seconds, pass `0` to disable timeout. The default value can be changed by using the browserContext.setDefaultNavigationTimeout(timeout), browserContext.setDefaultTimeout(timeout), page.setDefaultNavigationTimeout(timeout) or page.setDefaultTimeout(timeout) methods. - waitUntil : Optional[Literal['load', 'domcontentloaded', 'networkidle']] + waitUntil : Optional[Literal['domcontentloaded', 'load', 'networkidle']] When to consider navigation succeeded, defaults to `load`. Events can be either: - `'domcontentloaded'` - consider navigation to be finished when the `DOMContentLoaded` event is fired. - `'load'` - consider navigation to be finished when the `load` event is fired. @@ -3639,7 +3792,7 @@ async def goto( async def reload( self, timeout: int = None, - waitUntil: Literal["load", "domcontentloaded", "networkidle"] = None, + waitUntil: Literal["domcontentloaded", "load", "networkidle"] = None, ) -> typing.Union["Response", NoneType]: """Page.reload @@ -3647,7 +3800,7 @@ async def reload( ---------- timeout : Optional[int] Maximum navigation time in milliseconds, defaults to 30 seconds, pass `0` to disable timeout. The default value can be changed by using the browserContext.setDefaultNavigationTimeout(timeout), browserContext.setDefaultTimeout(timeout), page.setDefaultNavigationTimeout(timeout) or page.setDefaultTimeout(timeout) methods. - waitUntil : Optional[Literal['load', 'domcontentloaded', 'networkidle']] + waitUntil : Optional[Literal['domcontentloaded', 'load', 'networkidle']] When to consider navigation succeeded, defaults to `load`. Events can be either: - `'domcontentloaded'` - consider navigation to be finished when the `DOMContentLoaded` event is fired. - `'load'` - consider navigation to be finished when the `load` event is fired. @@ -3664,7 +3817,7 @@ async def reload( async def waitForLoadState( self, - state: Literal["load", "domcontentloaded", "networkidle"] = None, + state: Literal["domcontentloaded", "load", "networkidle"] = None, timeout: int = None, ) -> NoneType: """Page.waitForLoadState @@ -3674,7 +3827,7 @@ async def waitForLoadState( Parameters ---------- - state : Optional[Literal['load', 'domcontentloaded', 'networkidle']] + state : Optional[Literal['domcontentloaded', 'load', 'networkidle']] Load state to wait for, defaults to `load`. If the state has been already reached while loading current document, the method resolves immediately. - `'load'` - wait for the `load` event to be fired. - `'domcontentloaded'` - wait for the `DOMContentLoaded` event to be fired. @@ -3689,13 +3842,13 @@ async def waitForLoadState( async def waitForNavigation( self, url: typing.Union[str, typing.Pattern, typing.Callable[[str], bool]] = None, - waitUntil: Literal["load", "domcontentloaded", "networkidle"] = None, + waitUntil: Literal["domcontentloaded", "load", "networkidle"] = None, timeout: int = None, ) -> typing.Union["Response", NoneType]: """Page.waitForNavigation This resolves when the page navigates to a new URL or reloads. It is useful for when you run code - which will indirectly cause the page to navigate. Consider this example: + which will indirectly cause the page to navigate. e.g. The click target has an `onclick` handler that triggers navigation from a `setTimeout`. Consider this example: **NOTE** Usage of the History API to change the URL is considered a navigation. Shortcut for page.mainFrame().waitForNavigation(options). @@ -3703,7 +3856,7 @@ async def waitForNavigation( ---------- url : Union[str, Pattern, typing.Callable[[str], bool], NoneType] A glob pattern, regex pattern or predicate receiving URL to match while waiting for the navigation. - waitUntil : Optional[Literal['load', 'domcontentloaded', 'networkidle']] + waitUntil : Optional[Literal['domcontentloaded', 'load', 'networkidle']] When to consider navigation succeeded, defaults to `load`. Events can be either: - `'domcontentloaded'` - consider navigation to be finished when the `DOMContentLoaded` event is fired. - `'load'` - consider navigation to be finished when the `load` event is fired. @@ -3810,7 +3963,7 @@ async def waitForEvent( async def goBack( self, timeout: int = None, - waitUntil: Literal["load", "domcontentloaded", "networkidle"] = None, + waitUntil: Literal["domcontentloaded", "load", "networkidle"] = None, ) -> typing.Union["Response", NoneType]: """Page.goBack @@ -3820,7 +3973,7 @@ async def goBack( ---------- timeout : Optional[int] Maximum navigation time in milliseconds, defaults to 30 seconds, pass `0` to disable timeout. The default value can be changed by using the browserContext.setDefaultNavigationTimeout(timeout), browserContext.setDefaultTimeout(timeout), page.setDefaultNavigationTimeout(timeout) or page.setDefaultTimeout(timeout) methods. - waitUntil : Optional[Literal['load', 'domcontentloaded', 'networkidle']] + waitUntil : Optional[Literal['domcontentloaded', 'load', 'networkidle']] When to consider navigation succeeded, defaults to `load`. Events can be either: - `'domcontentloaded'` - consider navigation to be finished when the `DOMContentLoaded` event is fired. - `'load'` - consider navigation to be finished when the `load` event is fired. @@ -3839,7 +3992,7 @@ async def goBack( async def goForward( self, timeout: int = None, - waitUntil: Literal["load", "domcontentloaded", "networkidle"] = None, + waitUntil: Literal["domcontentloaded", "load", "networkidle"] = None, ) -> typing.Union["Response", NoneType]: """Page.goForward @@ -3849,7 +4002,7 @@ async def goForward( ---------- timeout : Optional[int] Maximum navigation time in milliseconds, defaults to 30 seconds, pass `0` to disable timeout. The default value can be changed by using the browserContext.setDefaultNavigationTimeout(timeout), browserContext.setDefaultTimeout(timeout), page.setDefaultNavigationTimeout(timeout) or page.setDefaultTimeout(timeout) methods. - waitUntil : Optional[Literal['load', 'domcontentloaded', 'networkidle']] + waitUntil : Optional[Literal['domcontentloaded', 'load', 'networkidle']] When to consider navigation succeeded, defaults to `load`. Events can be either: - `'domcontentloaded'` - consider navigation to be finished when the `DOMContentLoaded` event is fired. - `'load'` - consider navigation to be finished when the `load` event is fired. @@ -3867,17 +4020,17 @@ async def goForward( async def emulateMedia( self, - media: Literal["screen", "print"] = None, - colorScheme: Literal["light", "dark", "no-preference"] = None, + media: Literal["print", "screen"] = None, + colorScheme: Literal["dark", "light", "no-preference"] = None, ) -> NoneType: """Page.emulateMedia Parameters ---------- - media : Optional[Literal['screen', 'print']] + media : Optional[Literal['print', 'screen']] Changes the CSS media type of the page. The only allowed values are `'screen'`, `'print'` and `null`. Passing `null` disables CSS media emulation. Omitting `media` or passing `undefined` does not change the emulated value. - colorScheme : Optional[Literal['light', 'dark', 'no-preference']] + colorScheme : Optional[Literal['dark', 'light', 'no-preference']] Emulates `'prefers-colors-scheme'` media feature, supported values are `'light'`, `'dark'`, `'no-preference'`. Passing `null` disables color scheme emulation. Omitting `colorScheme` or passing `undefined` does not change the emulated value. """ return mapping.from_maybe_impl( @@ -3925,7 +4078,7 @@ async def addInitScript( Adds a script which would be evaluated in one of the following scenarios: Whenever the page is navigated. - Whenever the child frame is attached or navigated. In this case, the scritp is evaluated in the context of the newly attached frame. + Whenever the child frame is attached or navigated. In this case, the script is evaluated in the context of the newly attached frame. The script is evaluated after the document was created but before any of its scripts were run. This is useful to amend the JavaScript environment, e.g. to seed `Math.random`. An example of overriding `Math.random` before the page loads: @@ -3994,7 +4147,7 @@ async def unroute( async def screenshot( self, timeout: int = None, - type: Literal["png", "jpeg"] = None, + type: Literal["jpeg", "png"] = None, path: typing.Union[str, pathlib.Path] = None, quality: int = None, omitBackground: bool = None, @@ -4009,7 +4162,7 @@ async def screenshot( ---------- timeout : Optional[int] Maximum time in milliseconds, defaults to 30 seconds, pass `0` to disable timeout. The default value can be changed by using the browserContext.setDefaultTimeout(timeout) or page.setDefaultTimeout(timeout) methods. - type : Optional[Literal['png', 'jpeg']] + type : Optional[Literal['jpeg', 'png']] Specify screenshot type, defaults to `png`. path : Union[str, pathlib.Path, NoneType] The file path to save the image to. The screenshot type will be inferred from file extension. If `path` is a relative path, then it is resolved relative to current working directory. If no path is provided, the image won't be saved to the disk. @@ -4089,7 +4242,7 @@ async def click( ] = None, position: MousePosition = None, delay: int = None, - button: Literal["left", "right", "middle"] = None, + button: Literal["left", "middle", "right"] = None, clickCount: int = None, timeout: int = None, force: bool = None, @@ -4097,8 +4250,15 @@ async def click( ) -> NoneType: """Page.click - This method waits for an element matching `selector`, waits for actionability checks, then scrolls the element into view if needed and uses page.mouse to click in the center of the element. - If there's no element matching `selector`, the method waits until a matching element appears in the DOM. If the element is detached during the actionability checks, the action is retried. + This method clicks an element matching `selector` by performing the following steps: + + Find an element match matching `selector`. If there is none, wait until a matching element is attached to the DOM. + Wait for actionability checks on the matched element, unless `force` option is set. If the element is detached during the checks, the whole action is retried. + Scroll the element into view if needed. + Use page.mouse to click in the center of the element, or the specified `position`. + Wait for initiated navigations to either succeed or fail, unless `noWaitAfter` option is set. + + When all steps combined have not finished during the specified `timeout`, this method rejects with a TimeoutError. Passing zero timeout disables this. Shortcut for page.mainFrame().click(selector[, options]). Parameters @@ -4111,7 +4271,7 @@ async def click( A point to click relative to the top-left corner of element padding box. If not specified, clicks to some visible point of the element. delay : Optional[int] Time to wait between `mousedown` and `mouseup` in milliseconds. Defaults to 0. - button : Optional[Literal['left', 'right', 'middle']] + button : Optional[Literal['left', 'middle', 'right']] Defaults to `left`. clickCount : Optional[int] defaults to 1. See UIEvent.detail. @@ -4144,15 +4304,21 @@ async def dblclick( ] = None, position: MousePosition = None, delay: int = None, - button: Literal["left", "right", "middle"] = None, + button: Literal["left", "middle", "right"] = None, timeout: int = None, force: bool = None, ) -> NoneType: """Page.dblclick - This method waits for an element matching `selector`, waits for actionability checks, then scrolls the element into view if needed and uses page.mouse to double click in the center of the element. - If there's no element matching `selector`, the method waits until a matching element appears in the DOM. If the element is detached during the actionability checks, the action is retried. - Bear in mind that if the first click of the `dblclick()` triggers a navigation event, there will be an exception. + This method double clicks an element matching `selector` by performing the following steps: + + Find an element match matching `selector`. If there is none, wait until a matching element is attached to the DOM. + Wait for actionability checks on the matched element, unless `force` option is set. If the element is detached during the checks, the whole action is retried. + Scroll the element into view if needed. + Use page.mouse to double click in the center of the element, or the specified `position`. + Wait for initiated navigations to either succeed or fail, unless `noWaitAfter` option is set. Note that if the first click of the `dblclick()` triggers a navigation event, this method will reject. + + When all steps combined have not finished during the specified `timeout`, this method rejects with a TimeoutError. Passing zero timeout disables this. **NOTE** `page.dblclick()` dispatches two `click` events and a single `dblclick` event. @@ -4168,7 +4334,7 @@ async def dblclick( A point to double click relative to the top-left corner of element padding box. If not specified, double clicks to some visible point of the element. delay : Optional[int] Time to wait between `mousedown` and `mouseup` in milliseconds. Defaults to 0. - button : Optional[Literal['left', 'right', 'middle']] + button : Optional[Literal['left', 'middle', 'right']] Defaults to `left`. timeout : Optional[int] Maximum time in milliseconds, defaults to 30 seconds, pass `0` to disable timeout. The default value can be changed by using the browserContext.setDefaultTimeout(timeout) or page.setDefaultTimeout(timeout) methods. @@ -4333,8 +4499,15 @@ async def hover( ) -> NoneType: """Page.hover - This method waits for an element matching `selector`, waits for actionability checks, then scrolls the element into view if needed and uses page.mouse to hover over the center of the element. - If there's no element matching `selector`, the method waits until a matching element appears in the DOM. If the element is detached during the actionability checks, the action is retried. + This method hovers over an element matching `selector` by performing the following steps: + + Find an element match matching `selector`. If there is none, wait until a matching element is attached to the DOM. + Wait for actionability checks on the matched element, unless `force` option is set. If the element is detached during the checks, the whole action is retried. + Scroll the element into view if needed. + Use page.mouse to hover over the center of the element, or the specified `position`. + Wait for initiated navigations to either succeed or fail, unless `noWaitAfter` option is set. + + When all steps combined have not finished during the specified `timeout`, this method rejects with a TimeoutError. Passing zero timeout disables this. Shortcut for page.mainFrame().hover(selector[, options]). Parameters @@ -4523,8 +4696,17 @@ async def check( ) -> NoneType: """Page.check - This method waits for an element matching `selector`, waits for actionability checks. Then, if the element is not already checked, this method scrolls the element into view and uses elementHandle.click to click in the center of the element. - If there's no element matching `selector`, the method waits until a matching element appears in the DOM. If the element is detached during the actionability checks, the action is retried. + This method checks an element matching `selector` by performing the following steps: + + Find an element match matching `selector`. If there is none, wait until a matching element is attached to the DOM. + Ensure that matched element is a checkbox or a radio input. If not, this method rejects. If the element is already checked, this method returns immediately. + Wait for actionability checks on the matched element, unless `force` option is set. If the element is detached during the checks, the whole action is retried. + Scroll the element into view if needed. + Use page.mouse to click in the center of the element. + Wait for initiated navigations to either succeed or fail, unless `noWaitAfter` option is set. + Ensure that the element is now checked. If not, this method rejects. + + When all steps combined have not finished during the specified `timeout`, this method rejects with a TimeoutError. Passing zero timeout disables this. Shortcut for page.mainFrame().check(selector[, options]). Parameters @@ -4553,8 +4735,17 @@ async def uncheck( ) -> NoneType: """Page.uncheck - This method waits for an element matching `selector`, waits for actionability checks. Then, if the element is not already unchecked, this method scrolls the element into view and uses elementHandle.click to click in the center of the element. - If there's no element matching `selector`, the method waits until a matching element appears in the DOM. If the element is detached during the actionability checks, the action is retried. + This method unchecks an element matching `selector` by performing the following steps: + + Find an element match matching `selector`. If there is none, wait until a matching element is attached to the DOM. + Ensure that matched element is a checkbox or a radio input. If not, this method rejects. If the element is already unchecked, this method returns immediately. + Wait for actionability checks on the matched element, unless `force` option is set. If the element is detached during the checks, the whole action is retried. + Scroll the element into view if needed. + Use page.mouse to click in the center of the element. + Wait for initiated navigations to either succeed or fail, unless `noWaitAfter` option is set. + Ensure that the element is now unchecked. If not, this method rejects. + + When all steps combined have not finished during the specified `timeout`, this method rejects with a TimeoutError. Passing zero timeout disables this. Shortcut for page.mainFrame().uncheck(selector[, options]). Parameters @@ -4799,7 +4990,7 @@ def expect_file_chooser( def expect_load_state( self, - state: Literal["load", "domcontentloaded", "networkidle"] = None, + state: Literal["domcontentloaded", "load", "networkidle"] = None, timeout: int = None, ) -> AsyncEventContextManager[typing.Union["Response", NoneType]]: return AsyncEventContextManager(self._impl_obj.waitForLoadState(state, timeout)) @@ -4807,7 +4998,7 @@ def expect_load_state( def expect_navigation( self, url: typing.Union[str, typing.Pattern, typing.Callable[[str], bool]] = None, - waitUntil: Literal["load", "domcontentloaded", "networkidle"] = None, + waitUntil: Literal["domcontentloaded", "load", "networkidle"] = None, timeout: int = None, ) -> AsyncEventContextManager[typing.Union["Response", NoneType]]: return AsyncEventContextManager( @@ -5362,7 +5553,7 @@ async def newContext( deviceScaleFactor: int = None, isMobile: bool = None, hasTouch: bool = None, - colorScheme: Literal["light", "dark", "no-preference"] = None, + colorScheme: Literal["dark", "light", "no-preference"] = None, acceptDownloads: bool = None, defaultBrowserType: str = None, ) -> "BrowserContext": @@ -5401,7 +5592,7 @@ async def newContext( Whether the `meta viewport` tag is taken into account and touch events are enabled. Defaults to `false`. Not supported in Firefox. hasTouch : Optional[bool] Specifies if viewport supports touch events. Defaults to false. - colorScheme : Optional[Literal['light', 'dark', 'no-preference']] + colorScheme : Optional[Literal['dark', 'light', 'no-preference']] Emulates `'prefers-colors-scheme'` media feature, supported values are `'light'`, `'dark'`, `'no-preference'`. See page.emulateMedia(options) for more details. Defaults to '`light`'. acceptDownloads : Optional[bool] Whether to automatically download all the attachments. Defaults to `false` where all the downloads are canceled. @@ -5450,7 +5641,7 @@ async def newPage( deviceScaleFactor: int = None, isMobile: bool = None, hasTouch: bool = None, - colorScheme: Literal["light", "dark", "no-preference"] = None, + colorScheme: Literal["dark", "light", "no-preference"] = None, acceptDownloads: bool = None, ) -> "Page": """Browser.newPage @@ -5489,7 +5680,7 @@ async def newPage( Whether the `meta viewport` tag is taken into account and touch events are enabled. Defaults to `false`. Not supported in Firefox. hasTouch : Optional[bool] Specifies if viewport supports touch events. Defaults to false. - colorScheme : Optional[Literal['light', 'dark', 'no-preference']] + colorScheme : Optional[Literal['dark', 'light', 'no-preference']] Emulates `'prefers-colors-scheme'` media feature, supported values are `'light'`, `'dark'`, `'no-preference'`. See page.emulateMedia(options) for more details. Defaults to '`light`'. acceptDownloads : Optional[bool] Whether to automatically download all the attachments. Defaults to `false` where all the downloads are canceled. @@ -5672,7 +5863,7 @@ async def launchPersistentContext( deviceScaleFactor: int = None, isMobile: bool = None, hasTouch: bool = None, - colorScheme: Literal["light", "dark", "no-preference"] = None, + colorScheme: Literal["dark", "light", "no-preference"] = None, acceptDownloads: bool = None, chromiumSandbox: bool = None, ) -> "BrowserContext": @@ -5739,7 +5930,7 @@ async def launchPersistentContext( Whether the `meta viewport` tag is taken into account and touch events are enabled. Defaults to `false`. Not supported in Firefox. hasTouch : Optional[bool] Specifies if viewport supports touch events. Defaults to false. - colorScheme : Optional[Literal['light', 'dark', 'no-preference']] + colorScheme : Optional[Literal['dark', 'light', 'no-preference']] Emulates `'prefers-colors-scheme'` media feature, supported values are `'light'`, `'dark'`, `'no-preference'`. See page.emulateMedia(options) for more details. Defaults to '`light`'. acceptDownloads : Optional[bool] Whether to automatically download all the attachments. Defaults to `false` where all the downloads are canceled. diff --git a/playwright/element_handle.py b/playwright/element_handle.py index b6eee4b53..681a323f8 100644 --- a/playwright/element_handle.py +++ b/playwright/element_handle.py @@ -180,7 +180,7 @@ async def boundingBox(self) -> Optional[FloatRect]: async def screenshot( self, timeout: int = None, - type: Literal["png", "jpeg"] = None, + type: Literal["jpeg", "png"] = None, path: Union[str, Path] = None, quality: int = None, omitBackground: bool = None, @@ -246,6 +246,23 @@ async def evalOnSelectorAll( ) ) + async def waitForElementState( + self, + state: Literal["disabled", "enabled", "hidden", "stable", "visible"], + timeout: int = None, + ) -> None: + await self._channel.send("waitForElementState", locals_to_params(locals())) + + async def waitForSelector( + self, + selector: str, + state: Literal["attached", "detached", "hidden", "visible"] = None, + timeout: int = None, + ) -> Optional["ElementHandle"]: + return from_nullable_channel( + await self._channel.send("waitForSelector", locals_to_params(locals())) + ) + ValuesToSelect = Union[ str, diff --git a/playwright/frame.py b/playwright/frame.py index b548f4acd..641d6972e 100644 --- a/playwright/frame.py +++ b/playwright/frame.py @@ -98,6 +98,9 @@ def _on_frame_navigated(self, event: FrameNavigatedEvent) -> None: if "error" not in event and hasattr(self, "_page") and self._page: self._page.emit("framenavigated", self) + def page(self) -> "Page": + return self._page + async def goto( self, url: str, @@ -234,7 +237,7 @@ async def waitForSelector( self, selector: str, timeout: int = None, - state: Literal["attached", "detached", "visible", "hidden"] = None, + state: Literal["attached", "detached", "hidden", "visible"] = None, ) -> Optional[ElementHandle]: return from_nullable_channel( await self._channel.send("waitForSelector", locals_to_params(locals())) diff --git a/playwright/helper.py b/playwright/helper.py index 522678a81..a3d46df98 100644 --- a/playwright/helper.py +++ b/playwright/helper.py @@ -45,10 +45,10 @@ URLMatch = Union[str, Pattern, Callable[[str], bool]] RouteHandler = Callable[["Route", "Request"], Any] -ColorScheme = Literal["light", "dark", "no-preference"] -DocumentLoadState = Literal["load", "domcontentloaded", "networkidle"] +ColorScheme = Literal["dark", "light", "no-preference"] +DocumentLoadState = Literal["domcontentloaded", "load", "networkidle"] KeyboardModifier = Literal["Alt", "Control", "Meta", "Shift"] -MouseButton = Literal["left", "right", "middle"] +MouseButton = Literal["left", "middle", "right"] class MousePosition(TypedDict): @@ -69,9 +69,9 @@ class SelectOption(TypedDict): class ConsoleMessageLocation(TypedDict): - url: Optional[str] - lineNumber: Optional[int] - columnNumber: Optional[int] + url: str + lineNumber: int + columnNumber: int class ErrorPayload(TypedDict, total=False): diff --git a/playwright/page.py b/playwright/page.py index 62da22161..2b5c5c29e 100644 --- a/playwright/page.py +++ b/playwright/page.py @@ -313,7 +313,7 @@ async def waitForSelector( self, selector: str, timeout: int = None, - state: Literal["attached", "detached", "visible", "hidden"] = None, + state: Literal["attached", "detached", "hidden", "visible"] = None, ) -> Optional[ElementHandle]: return await self._main_frame.waitForSelector(**locals_to_params(locals())) @@ -503,7 +503,7 @@ async def goForward( ) async def emulateMedia( - self, media: Literal["screen", "print"] = None, colorScheme: ColorScheme = None, + self, media: Literal["print", "screen"] = None, colorScheme: ColorScheme = None, ) -> None: await self._channel.send("emulateMedia", locals_to_params(locals())) @@ -553,7 +553,7 @@ async def unroute( async def screenshot( self, timeout: int = None, - type: Literal["png", "jpeg"] = None, + type: Literal["jpeg", "png"] = None, path: Union[str, Path] = None, quality: int = None, omitBackground: bool = None, diff --git a/playwright/sync_api.py b/playwright/sync_api.py index 9af81004e..a81399f13 100644 --- a/playwright/sync_api.py +++ b/playwright/sync_api.py @@ -595,7 +595,7 @@ def move(self, x: float, y: float, steps: int = None) -> NoneType: ) def down( - self, button: Literal["left", "right", "middle"] = None, clickCount: int = None + self, button: Literal["left", "middle", "right"] = None, clickCount: int = None ) -> NoneType: """Mouse.down @@ -603,7 +603,7 @@ def down( Parameters ---------- - button : Optional[Literal['left', 'right', 'middle']] + button : Optional[Literal['left', 'middle', 'right']] Defaults to `left`. clickCount : Optional[int] defaults to 1. See UIEvent.detail. @@ -613,7 +613,7 @@ def down( ) def up( - self, button: Literal["left", "right", "middle"] = None, clickCount: int = None + self, button: Literal["left", "middle", "right"] = None, clickCount: int = None ) -> NoneType: """Mouse.up @@ -621,7 +621,7 @@ def up( Parameters ---------- - button : Optional[Literal['left', 'right', 'middle']] + button : Optional[Literal['left', 'middle', 'right']] Defaults to `left`. clickCount : Optional[int] defaults to 1. See UIEvent.detail. @@ -635,7 +635,7 @@ def click( x: float, y: float, delay: int = None, - button: Literal["left", "right", "middle"] = None, + button: Literal["left", "middle", "right"] = None, clickCount: int = None, ) -> NoneType: """Mouse.click @@ -648,7 +648,7 @@ def click( y : float delay : Optional[int] Time to wait between `mousedown` and `mouseup` in milliseconds. Defaults to 0. - button : Optional[Literal['left', 'right', 'middle']] + button : Optional[Literal['left', 'middle', 'right']] Defaults to `left`. clickCount : Optional[int] defaults to 1. See UIEvent.detail. @@ -666,7 +666,7 @@ def dblclick( x: float, y: float, delay: int = None, - button: Literal["left", "right", "middle"] = None, + button: Literal["left", "middle", "right"] = None, ) -> NoneType: """Mouse.dblclick @@ -678,7 +678,7 @@ def dblclick( y : float delay : Optional[int] Time to wait between `mousedown` and `mouseup` in milliseconds. Defaults to 0. - button : Optional[Literal['left', 'right', 'middle']] + button : Optional[Literal['left', 'middle', 'right']] Defaults to `left`. """ return mapping.from_maybe_impl( @@ -976,8 +976,15 @@ def hover( ) -> NoneType: """ElementHandle.hover - This method waits for actionability checks, then scrolls the element into view if needed and uses page.mouse to hover over the center of the element. - If the element is detached from DOM, the method throws an error. + This method hovers over the element by performing the following steps: + + Wait for actionability checks on the element, unless `force` option is set. + Scroll the element into view if needed. + Use page.mouse to hover over the center of the element, or the specified `position`. + Wait for initiated navigations to either succeed or fail, unless `noWaitAfter` option is set. + + If the element is detached from the DOM at any moment during the action, this method rejects. + When all steps combined have not finished during the specified `timeout`, this method rejects with a TimeoutError. Passing zero timeout disables this. Parameters ---------- @@ -1005,7 +1012,7 @@ def click( ] = None, position: MousePosition = None, delay: int = None, - button: Literal["left", "right", "middle"] = None, + button: Literal["left", "middle", "right"] = None, clickCount: int = None, timeout: int = None, force: bool = None, @@ -1013,8 +1020,15 @@ def click( ) -> NoneType: """ElementHandle.click - This method waits for actionability checks, then scrolls the element into view if needed and uses page.mouse to click in the center of the element. - If the element is detached from DOM, the method throws an error. + This method clicks the element by performing the following steps: + + Wait for actionability checks on the element, unless `force` option is set. + Scroll the element into view if needed. + Use page.mouse to click in the center of the element, or the specified `position`. + Wait for initiated navigations to either succeed or fail, unless `noWaitAfter` option is set. + + If the element is detached from the DOM at any moment during the action, this method rejects. + When all steps combined have not finished during the specified `timeout`, this method rejects with a TimeoutError. Passing zero timeout disables this. Parameters ---------- @@ -1024,7 +1038,7 @@ def click( A point to click relative to the top-left corner of element padding box. If not specified, clicks to some visible point of the element. delay : Optional[int] Time to wait between `mousedown` and `mouseup` in milliseconds. Defaults to 0. - button : Optional[Literal['left', 'right', 'middle']] + button : Optional[Literal['left', 'middle', 'right']] Defaults to `left`. clickCount : Optional[int] defaults to 1. See UIEvent.detail. @@ -1057,16 +1071,22 @@ def dblclick( ] = None, position: MousePosition = None, delay: int = None, - button: Literal["left", "right", "middle"] = None, + button: Literal["left", "middle", "right"] = None, timeout: int = None, force: bool = None, noWaitAfter: bool = None, ) -> NoneType: """ElementHandle.dblclick - This method waits for actionability checks, then scrolls the element into view if needed and uses page.mouse to double click in the center of the element. - If the element is detached from DOM, the method throws an error. - Bear in mind that if the first click of the `dblclick()` triggers a navigation event, there will be an exception. + This method double clicks the element by performing the following steps: + + Wait for actionability checks on the element, unless `force` option is set. + Scroll the element into view if needed. + Use page.mouse to double click in the center of the element, or the specified `position`. + Wait for initiated navigations to either succeed or fail, unless `noWaitAfter` option is set. Note that if the first click of the `dblclick()` triggers a navigation event, this method will reject. + + If the element is detached from the DOM at any moment during the action, this method rejects. + When all steps combined have not finished during the specified `timeout`, this method rejects with a TimeoutError. Passing zero timeout disables this. **NOTE** `elementHandle.dblclick()` dispatches two `click` events and a single `dblclick` event. @@ -1078,7 +1098,7 @@ def dblclick( A point to double click relative to the top-left corner of element padding box. If not specified, double clicks to some visible point of the element. delay : Optional[int] Time to wait between `mousedown` and `mouseup` in milliseconds. Defaults to 0. - button : Optional[Literal['left', 'right', 'middle']] + button : Optional[Literal['left', 'middle', 'right']] Defaults to `left`. timeout : Optional[int] Maximum time in milliseconds, defaults to 30 seconds, pass `0` to disable timeout. The default value can be changed by using the browserContext.setDefaultTimeout(timeout) or page.setDefaultTimeout(timeout) methods. @@ -1293,7 +1313,17 @@ def check( ) -> NoneType: """ElementHandle.check - This method waits for actionability checks. Then, if the element is not already checked, this method scrolls the element into view and uses elementHandle.click to click in the center of the element. + This method checks the element by performing the following steps: + + Ensure that element is a checkbox or a radio input. If not, this method rejects. If the element is already checked, this method returns immediately. + Wait for actionability checks on the element, unless `force` option is set. + Scroll the element into view if needed. + Use page.mouse to click in the center of the element. + Wait for initiated navigations to either succeed or fail, unless `noWaitAfter` option is set. + Ensure that the element is now checked. If not, this method rejects. + + If the element is detached from the DOM at any moment during the action, this method rejects. + When all steps combined have not finished during the specified `timeout`, this method rejects with a TimeoutError. Passing zero timeout disables this. Parameters ---------- @@ -1317,7 +1347,17 @@ def uncheck( ) -> NoneType: """ElementHandle.uncheck - This method waits for actionability checks. Then, if the element is not already unchecked, this method scrolls the element into view and uses elementHandle.click to click in the center of the element. + This method checks the element by performing the following steps: + + Ensure that element is a checkbox or a radio input. If not, this method rejects. If the element is already unchecked, this method returns immediately. + Wait for actionability checks on the element, unless `force` option is set. + Scroll the element into view if needed. + Use page.mouse to click in the center of the element. + Wait for initiated navigations to either succeed or fail, unless `noWaitAfter` option is set. + Ensure that the element is now unchecked. If not, this method rejects. + + If the element is detached from the DOM at any moment during the action, this method rejects. + When all steps combined have not finished during the specified `timeout`, this method rejects with a TimeoutError. Passing zero timeout disables this. Parameters ---------- @@ -1350,7 +1390,7 @@ def boundingBox(self) -> typing.Union[FloatRect, NoneType]: def screenshot( self, timeout: int = None, - type: Literal["png", "jpeg"] = None, + type: Literal["jpeg", "png"] = None, path: typing.Union[str, pathlib.Path] = None, quality: int = None, omitBackground: bool = None, @@ -1363,7 +1403,7 @@ def screenshot( ---------- timeout : Optional[int] Maximum time in milliseconds, defaults to 30 seconds, pass `0` to disable timeout. The default value can be changed by using the browserContext.setDefaultTimeout(timeout) or page.setDefaultTimeout(timeout) methods. - type : Optional[Literal['png', 'jpeg']] + type : Optional[Literal['jpeg', 'png']] Specify screenshot type, defaults to `png`. path : Union[str, pathlib.Path, NoneType] The file path to save the image to. The screenshot type will be inferred from file extension. If `path` is a relative path, then it is resolved relative to current working directory. If no path is provided, the image won't be saved to the disk. @@ -1511,6 +1551,72 @@ def evalOnSelectorAll( ) ) + def waitForElementState( + self, + state: Literal["disabled", "enabled", "hidden", "stable", "visible"], + timeout: int = None, + ) -> NoneType: + """ElementHandle.waitForElementState + + Depending on the `state` parameter, this method waits for one of the actionability checks to pass. This method throws when the element is detached while waiting, unless waiting for the `"hidden"` state. + + `"visible"` Wait until the element is visible. + `"hidden"` Wait until the element is not visible or not attached. Note that waiting for hidden does not throw when the element detaches. + `"stable"` Wait until the element is both visible and stable. + `"enabled"` Wait until the element is enabled. + `"disabled"` Wait until the element is not enabled. + + If the element does not satisfy the condition for the `timeout` milliseconds, this method will throw. + + Parameters + ---------- + state : Literal['disabled', 'enabled', 'hidden', 'stable', 'visible'] + A state to wait for, see below for more details. + timeout : Optional[int] + Maximum time in milliseconds, defaults to 30 seconds, pass `0` to disable timeout. The default value can be changed by using the browserContext.setDefaultTimeout(timeout) or page.setDefaultTimeout(timeout) methods. + """ + return mapping.from_maybe_impl( + self._sync(self._impl_obj.waitForElementState(state=state, timeout=timeout)) + ) + + def waitForSelector( + self, + selector: str, + state: Literal["attached", "detached", "hidden", "visible"] = None, + timeout: int = None, + ) -> typing.Union["ElementHandle", NoneType]: + """ElementHandle.waitForSelector + + Wait for the `selector` relative to the element handle to satisfy `state` option (either appear/disappear from dom, or become visible/hidden). If at the moment of calling the method `selector` already satisfies the condition, the method will return immediately. If the selector doesn't satisfy the condition for the `timeout` milliseconds, the function will throw. + + **NOTE** This method does not work across navigations, use page.waitForSelector(selector[, options]) instead. + + Parameters + ---------- + selector : str + A selector of an element to wait for, relative to the element handle. See working with selectors for more details. + state : Optional[Literal['attached', 'detached', 'hidden', 'visible']] + Defaults to `'visible'`. Can be either: + - `'attached'` - wait for element to be present in DOM. + - `'detached'` - wait for element to not be present in DOM. + - `'visible'` - wait for element to have non-empty bounding box and no `visibility:hidden`. Note that element without any content or with `display:none` has an empty bounding box and is not considered visible. + - `'hidden'` - wait for element to be either detached from DOM, or have an empty bounding box or `visibility:hidden`. This is opposite to the `'visible'` option. + timeout : Optional[int] + Maximum time in milliseconds, defaults to 30 seconds, pass `0` to disable timeout. The default value can be changed by using the browserContext.setDefaultTimeout(timeout) or page.setDefaultTimeout(timeout) methods. + + Returns + ------- + Optional[ElementHandle] + Promise that resolves when element specified by selector satisfies `state` option. Resolves to `null` if waiting for `hidden` or `detached`. + """ + return mapping.from_impl_nullable( + self._sync( + self._impl_obj.waitForSelector( + selector=selector, state=state, timeout=timeout + ) + ) + ) + mapping.register(ElementHandleImpl, ElementHandle) @@ -1681,11 +1787,22 @@ def childFrames(self) -> typing.List["Frame"]: """ return mapping.from_impl_list(self._impl_obj.childFrames) + def page(self) -> "Page": + """Frame.page + + Returns the page containing this frame. + + Returns + ------- + Page + """ + return mapping.from_impl(self._impl_obj.page()) + def goto( self, url: str, timeout: int = None, - waitUntil: Literal["load", "domcontentloaded", "networkidle"] = None, + waitUntil: Literal["domcontentloaded", "load", "networkidle"] = None, referer: str = None, ) -> typing.Union["Response", NoneType]: """Frame.goto @@ -1710,7 +1827,7 @@ def goto( URL to navigate frame to. The url should include scheme, e.g. `https://`. timeout : Optional[int] Maximum navigation time in milliseconds, defaults to 30 seconds, pass `0` to disable timeout. The default value can be changed by using the browserContext.setDefaultNavigationTimeout(timeout), browserContext.setDefaultTimeout(timeout), page.setDefaultNavigationTimeout(timeout) or page.setDefaultTimeout(timeout) methods. - waitUntil : Optional[Literal['load', 'domcontentloaded', 'networkidle']] + waitUntil : Optional[Literal['domcontentloaded', 'load', 'networkidle']] When to consider navigation succeeded, defaults to `load`. Events can be either: - `'domcontentloaded'` - consider navigation to be finished when the `DOMContentLoaded` event is fired. - `'load'` - consider navigation to be finished when the `load` event is fired. @@ -1734,7 +1851,7 @@ def goto( def waitForNavigation( self, url: typing.Union[str, typing.Pattern, typing.Callable[[str], bool]] = None, - waitUntil: Literal["load", "domcontentloaded", "networkidle"] = None, + waitUntil: Literal["domcontentloaded", "load", "networkidle"] = None, timeout: int = None, ) -> typing.Union["Response", NoneType]: """Frame.waitForNavigation @@ -1747,7 +1864,7 @@ def waitForNavigation( ---------- url : Union[str, Pattern, typing.Callable[[str], bool], NoneType] URL string, URL regex pattern or predicate receiving URL to match while waiting for the navigation. - waitUntil : Optional[Literal['load', 'domcontentloaded', 'networkidle']] + waitUntil : Optional[Literal['domcontentloaded', 'load', 'networkidle']] When to consider navigation succeeded, defaults to `load`. Events can be either: - `'domcontentloaded'` - consider navigation to be finished when the `DOMContentLoaded` event is fired. - `'load'` - consider navigation to be finished when the `load` event is fired. @@ -1770,7 +1887,7 @@ def waitForNavigation( def waitForLoadState( self, - state: Literal["load", "domcontentloaded", "networkidle"] = None, + state: Literal["domcontentloaded", "load", "networkidle"] = None, timeout: int = None, ) -> NoneType: """Frame.waitForLoadState @@ -1779,7 +1896,7 @@ def waitForLoadState( Parameters ---------- - state : Optional[Literal['load', 'domcontentloaded', 'networkidle']] + state : Optional[Literal['domcontentloaded', 'load', 'networkidle']] Load state to wait for, defaults to `load`. If the state has been already reached while loading current document, the method resolves immediately. - `'load'` - wait for the `load` event to be fired. - `'domcontentloaded'` - wait for the `DOMContentLoaded` event to be fired. @@ -1914,7 +2031,7 @@ def waitForSelector( self, selector: str, timeout: int = None, - state: Literal["attached", "detached", "visible", "hidden"] = None, + state: Literal["attached", "detached", "hidden", "visible"] = None, ) -> typing.Union["ElementHandle", NoneType]: """Frame.waitForSelector @@ -1927,7 +2044,7 @@ def waitForSelector( A selector of an element to wait for. See working with selectors for more details. timeout : Optional[int] Maximum time in milliseconds, defaults to 30 seconds, pass `0` to disable timeout. The default value can be changed by using the browserContext.setDefaultTimeout(timeout) or page.setDefaultTimeout(timeout) methods. - state : Optional[Literal['attached', 'detached', 'visible', 'hidden']] + state : Optional[Literal['attached', 'detached', 'hidden', 'visible']] Defaults to `'visible'`. Can be either: - `'attached'` - wait for element to be present in DOM. - `'detached'` - wait for element to not be present in DOM. @@ -2087,7 +2204,7 @@ def setContent( self, html: str, timeout: int = None, - waitUntil: Literal["load", "domcontentloaded", "networkidle"] = None, + waitUntil: Literal["domcontentloaded", "load", "networkidle"] = None, ) -> NoneType: """Frame.setContent @@ -2097,7 +2214,7 @@ def setContent( HTML markup to assign to the page. timeout : Optional[int] Maximum time in milliseconds for resources to load, defaults to 30 seconds, pass `0` to disable timeout. The default value can be changed by using the browserContext.setDefaultNavigationTimeout(timeout), browserContext.setDefaultTimeout(timeout), page.setDefaultNavigationTimeout(timeout) or page.setDefaultTimeout(timeout) methods. - waitUntil : Optional[Literal['load', 'domcontentloaded', 'networkidle']] + waitUntil : Optional[Literal['domcontentloaded', 'load', 'networkidle']] When to consider navigation succeeded, defaults to `load`. Events can be either: - `'domcontentloaded'` - consider setting content to be finished when the `DOMContentLoaded` event is fired. - `'load'` - consider setting content to be finished when the `load` event is fired. @@ -2193,7 +2310,7 @@ def click( ] = None, position: MousePosition = None, delay: int = None, - button: Literal["left", "right", "middle"] = None, + button: Literal["left", "middle", "right"] = None, clickCount: int = None, timeout: int = None, force: bool = None, @@ -2201,8 +2318,15 @@ def click( ) -> NoneType: """Frame.click - This method waits for an element matching `selector`, waits for actionability checks, then scrolls the element into view if needed and uses page.mouse to click in the center of the element. - If there's no element matching `selector`, the method waits until a matching element appears in the DOM. If the element is detached during the actionability checks, the action is retried. + This method clicks an element matching `selector` by performing the following steps: + + Find an element match matching `selector`. If there is none, wait until a matching element is attached to the DOM. + Wait for actionability checks on the matched element, unless `force` option is set. If the element is detached during the checks, the whole action is retried. + Scroll the element into view if needed. + Use page.mouse to click in the center of the element, or the specified `position`. + Wait for initiated navigations to either succeed or fail, unless `noWaitAfter` option is set. + + When all steps combined have not finished during the specified `timeout`, this method rejects with a TimeoutError. Passing zero timeout disables this. Parameters ---------- @@ -2214,7 +2338,7 @@ def click( A point to click relative to the top-left corner of element padding box. If not specified, clicks to some visible point of the element. delay : Optional[int] Time to wait between `mousedown` and `mouseup` in milliseconds. Defaults to 0. - button : Optional[Literal['left', 'right', 'middle']] + button : Optional[Literal['left', 'middle', 'right']] Defaults to `left`. clickCount : Optional[int] defaults to 1. See UIEvent.detail. @@ -2249,15 +2373,21 @@ def dblclick( ] = None, position: MousePosition = None, delay: int = None, - button: Literal["left", "right", "middle"] = None, + button: Literal["left", "middle", "right"] = None, timeout: int = None, force: bool = None, ) -> NoneType: """Frame.dblclick - This method waits for an element matching `selector`, waits for actionability checks, then scrolls the element into view if needed and uses page.mouse to double click in the center of the element. - If there's no element matching `selector`, the method waits until a matching element appears in the DOM. If the element is detached during the actionability checks, the action is retried. - Bear in mind that if the first click of the `dblclick()` triggers a navigation event, there will be an exception. + This method double clicks an element matching `selector` by performing the following steps: + + Find an element match matching `selector`. If there is none, wait until a matching element is attached to the DOM. + Wait for actionability checks on the matched element, unless `force` option is set. If the element is detached during the checks, the whole action is retried. + Scroll the element into view if needed. + Use page.mouse to double click in the center of the element, or the specified `position`. + Wait for initiated navigations to either succeed or fail, unless `noWaitAfter` option is set. Note that if the first click of the `dblclick()` triggers a navigation event, this method will reject. + + When all steps combined have not finished during the specified `timeout`, this method rejects with a TimeoutError. Passing zero timeout disables this. **NOTE** `frame.dblclick()` dispatches two `click` events and a single `dblclick` event. @@ -2271,7 +2401,7 @@ def dblclick( A point to double click relative to the top-left corner of element padding box. If not specified, double clicks to some visible point of the element. delay : Optional[int] Time to wait between `mousedown` and `mouseup` in milliseconds. Defaults to 0. - button : Optional[Literal['left', 'right', 'middle']] + button : Optional[Literal['left', 'middle', 'right']] Defaults to `left`. timeout : Optional[int] Maximum time in milliseconds, defaults to 30 seconds, pass `0` to disable timeout. The default value can be changed by using the browserContext.setDefaultTimeout(timeout) or page.setDefaultTimeout(timeout) methods. @@ -2443,8 +2573,15 @@ def hover( ) -> NoneType: """Frame.hover - This method waits for an element matching `selector`, waits for actionability checks, then scrolls the element into view if needed and uses page.mouse to hover over the center of the element. - If there's no element matching `selector`, the method waits until a matching element appears in the DOM. If the element is detached during the actionability checks, the action is retried. + This method hovers over an element matching `selector` by performing the following steps: + + Find an element match matching `selector`. If there is none, wait until a matching element is attached to the DOM. + Wait for actionability checks on the matched element, unless `force` option is set. If the element is detached during the checks, the whole action is retried. + Scroll the element into view if needed. + Use page.mouse to hover over the center of the element, or the specified `position`. + Wait for initiated navigations to either succeed or fail, unless `noWaitAfter` option is set. + + When all steps combined have not finished during the specified `timeout`, this method rejects with a TimeoutError. Passing zero timeout disables this. Parameters ---------- @@ -2646,8 +2783,17 @@ def check( ) -> NoneType: """Frame.check - This method waits for an element matching `selector`, waits for actionability checks. Then, if the element is not already checked, this method scrolls the element into view and uses elementHandle.click to click in the center of the element. - If there's no element matching `selector`, the method waits until a matching element appears in the DOM. If the element is detached during the actionability checks, the action is retried. + This method checks an element matching `selector` by performing the following steps: + + Find an element match matching `selector`. If there is none, wait until a matching element is attached to the DOM. + Ensure that matched element is a checkbox or a radio input. If not, this method rejects. If the element is already checked, this method returns immediately. + Wait for actionability checks on the matched element, unless `force` option is set. If the element is detached during the checks, the whole action is retried. + Scroll the element into view if needed. + Use page.mouse to click in the center of the element. + Wait for initiated navigations to either succeed or fail, unless `noWaitAfter` option is set. + Ensure that the element is now checked. If not, this method rejects. + + When all steps combined have not finished during the specified `timeout`, this method rejects with a TimeoutError. Passing zero timeout disables this. Parameters ---------- @@ -2680,8 +2826,17 @@ def uncheck( ) -> NoneType: """Frame.uncheck - This method waits for an element matching `selector`, waits for actionability checks. Then, if the element is not already unchecked, this method scrolls the element into view and uses elementHandle.click to click in the center of the element. - If there's no element matching `selector`, the method waits until a matching element appears in the DOM. If the element is detached during the actionability checks, the action is retried. + This method checks an element matching `selector` by performing the following steps: + + Find an element match matching `selector`. If there is none, wait until a matching element is attached to the DOM. + Ensure that matched element is a checkbox or a radio input. If not, this method rejects. If the element is already unchecked, this method returns immediately. + Wait for actionability checks on the matched element, unless `force` option is set. If the element is detached during the checks, the whole action is retried. + Scroll the element into view if needed. + Use page.mouse to click in the center of the element. + Wait for initiated navigations to either succeed or fail, unless `noWaitAfter` option is set. + Ensure that the element is now unchecked. If not, this method rejects. + + When all steps combined have not finished during the specified `timeout`, this method rejects with a TimeoutError. Passing zero timeout disables this. Parameters ---------- @@ -2776,7 +2931,7 @@ def title(self) -> str: def expect_load_state( self, - state: Literal["load", "domcontentloaded", "networkidle"] = None, + state: Literal["domcontentloaded", "load", "networkidle"] = None, timeout: int = None, ) -> EventContextManager[typing.Union["Response", NoneType]]: return EventContextManager( @@ -2786,7 +2941,7 @@ def expect_load_state( def expect_navigation( self, url: typing.Union[str, typing.Pattern, typing.Callable[[str], bool]] = None, - waitUntil: Literal["load", "domcontentloaded", "networkidle"] = None, + waitUntil: Literal["domcontentloaded", "load", "networkidle"] = None, timeout: int = None, ) -> EventContextManager[typing.Union["Response", NoneType]]: return EventContextManager( @@ -2957,7 +3112,7 @@ def location(self) -> ConsoleMessageLocation: Returns ------- - {"url": Optional[str], "lineNumber": Optional[int], "columnNumber": Optional[int]} + {"url": str, "lineNumber": int, "columnNumber": int} """ return mapping.from_maybe_impl(self._impl_obj.location) @@ -3325,7 +3480,7 @@ def waitForSelector( self, selector: str, timeout: int = None, - state: Literal["attached", "detached", "visible", "hidden"] = None, + state: Literal["attached", "detached", "hidden", "visible"] = None, ) -> typing.Union["ElementHandle", NoneType]: """Page.waitForSelector @@ -3340,7 +3495,7 @@ def waitForSelector( A selector of an element to wait for. See working with selectors for more details. timeout : Optional[int] Maximum time in milliseconds, defaults to 30 seconds, pass `0` to disable timeout. The default value can be changed by using the browserContext.setDefaultTimeout(timeout) or page.setDefaultTimeout(timeout) methods. - state : Optional[Literal['attached', 'detached', 'visible', 'hidden']] + state : Optional[Literal['attached', 'detached', 'hidden', 'visible']] Defaults to `'visible'`. Can be either: - `'attached'` - wait for element to be present in DOM. - `'detached'` - wait for element to not be present in DOM. @@ -3712,7 +3867,7 @@ def setContent( self, html: str, timeout: int = None, - waitUntil: Literal["load", "domcontentloaded", "networkidle"] = None, + waitUntil: Literal["domcontentloaded", "load", "networkidle"] = None, ) -> NoneType: """Page.setContent @@ -3722,7 +3877,7 @@ def setContent( HTML markup to assign to the page. timeout : Optional[int] Maximum time in milliseconds for resources to load, defaults to 30 seconds, pass `0` to disable timeout. The default value can be changed by using the browserContext.setDefaultNavigationTimeout(timeout), browserContext.setDefaultTimeout(timeout), page.setDefaultNavigationTimeout(timeout) or page.setDefaultTimeout(timeout) methods. - waitUntil : Optional[Literal['load', 'domcontentloaded', 'networkidle']] + waitUntil : Optional[Literal['domcontentloaded', 'load', 'networkidle']] When to consider setting markup succeeded, defaults to `load`. Given an array of event strings, setting content is considered to be successful after all events have been fired. Events can be either: - `'load'` - consider setting content to be finished when the `load` event is fired. - `'domcontentloaded'` - consider setting content to be finished when the `DOMContentLoaded` event is fired. @@ -3740,7 +3895,7 @@ def goto( self, url: str, timeout: int = None, - waitUntil: Literal["load", "domcontentloaded", "networkidle"] = None, + waitUntil: Literal["domcontentloaded", "load", "networkidle"] = None, referer: str = None, ) -> typing.Union["Response", NoneType]: """Page.goto @@ -3767,7 +3922,7 @@ def goto( URL to navigate page to. The url should include scheme, e.g. `https://`. timeout : Optional[int] Maximum navigation time in milliseconds, defaults to 30 seconds, pass `0` to disable timeout. The default value can be changed by using the browserContext.setDefaultNavigationTimeout(timeout), browserContext.setDefaultTimeout(timeout), page.setDefaultNavigationTimeout(timeout) or page.setDefaultTimeout(timeout) methods. - waitUntil : Optional[Literal['load', 'domcontentloaded', 'networkidle']] + waitUntil : Optional[Literal['domcontentloaded', 'load', 'networkidle']] When to consider navigation succeeded, defaults to `load`. Events can be either: - `'domcontentloaded'` - consider navigation to be finished when the `DOMContentLoaded` event is fired. - `'load'` - consider navigation to be finished when the `load` event is fired. @@ -3791,7 +3946,7 @@ def goto( def reload( self, timeout: int = None, - waitUntil: Literal["load", "domcontentloaded", "networkidle"] = None, + waitUntil: Literal["domcontentloaded", "load", "networkidle"] = None, ) -> typing.Union["Response", NoneType]: """Page.reload @@ -3799,7 +3954,7 @@ def reload( ---------- timeout : Optional[int] Maximum navigation time in milliseconds, defaults to 30 seconds, pass `0` to disable timeout. The default value can be changed by using the browserContext.setDefaultNavigationTimeout(timeout), browserContext.setDefaultTimeout(timeout), page.setDefaultNavigationTimeout(timeout) or page.setDefaultTimeout(timeout) methods. - waitUntil : Optional[Literal['load', 'domcontentloaded', 'networkidle']] + waitUntil : Optional[Literal['domcontentloaded', 'load', 'networkidle']] When to consider navigation succeeded, defaults to `load`. Events can be either: - `'domcontentloaded'` - consider navigation to be finished when the `DOMContentLoaded` event is fired. - `'load'` - consider navigation to be finished when the `load` event is fired. @@ -3816,7 +3971,7 @@ def reload( def waitForLoadState( self, - state: Literal["load", "domcontentloaded", "networkidle"] = None, + state: Literal["domcontentloaded", "load", "networkidle"] = None, timeout: int = None, ) -> NoneType: """Page.waitForLoadState @@ -3826,7 +3981,7 @@ def waitForLoadState( Parameters ---------- - state : Optional[Literal['load', 'domcontentloaded', 'networkidle']] + state : Optional[Literal['domcontentloaded', 'load', 'networkidle']] Load state to wait for, defaults to `load`. If the state has been already reached while loading current document, the method resolves immediately. - `'load'` - wait for the `load` event to be fired. - `'domcontentloaded'` - wait for the `DOMContentLoaded` event to be fired. @@ -3841,13 +3996,13 @@ def waitForLoadState( def waitForNavigation( self, url: typing.Union[str, typing.Pattern, typing.Callable[[str], bool]] = None, - waitUntil: Literal["load", "domcontentloaded", "networkidle"] = None, + waitUntil: Literal["domcontentloaded", "load", "networkidle"] = None, timeout: int = None, ) -> typing.Union["Response", NoneType]: """Page.waitForNavigation This resolves when the page navigates to a new URL or reloads. It is useful for when you run code - which will indirectly cause the page to navigate. Consider this example: + which will indirectly cause the page to navigate. e.g. The click target has an `onclick` handler that triggers navigation from a `setTimeout`. Consider this example: **NOTE** Usage of the History API to change the URL is considered a navigation. Shortcut for page.mainFrame().waitForNavigation(options). @@ -3855,7 +4010,7 @@ def waitForNavigation( ---------- url : Union[str, Pattern, typing.Callable[[str], bool], NoneType] A glob pattern, regex pattern or predicate receiving URL to match while waiting for the navigation. - waitUntil : Optional[Literal['load', 'domcontentloaded', 'networkidle']] + waitUntil : Optional[Literal['domcontentloaded', 'load', 'networkidle']] When to consider navigation succeeded, defaults to `load`. Events can be either: - `'domcontentloaded'` - consider navigation to be finished when the `DOMContentLoaded` event is fired. - `'load'` - consider navigation to be finished when the `load` event is fired. @@ -3972,7 +4127,7 @@ def waitForEvent( def goBack( self, timeout: int = None, - waitUntil: Literal["load", "domcontentloaded", "networkidle"] = None, + waitUntil: Literal["domcontentloaded", "load", "networkidle"] = None, ) -> typing.Union["Response", NoneType]: """Page.goBack @@ -3982,7 +4137,7 @@ def goBack( ---------- timeout : Optional[int] Maximum navigation time in milliseconds, defaults to 30 seconds, pass `0` to disable timeout. The default value can be changed by using the browserContext.setDefaultNavigationTimeout(timeout), browserContext.setDefaultTimeout(timeout), page.setDefaultNavigationTimeout(timeout) or page.setDefaultTimeout(timeout) methods. - waitUntil : Optional[Literal['load', 'domcontentloaded', 'networkidle']] + waitUntil : Optional[Literal['domcontentloaded', 'load', 'networkidle']] When to consider navigation succeeded, defaults to `load`. Events can be either: - `'domcontentloaded'` - consider navigation to be finished when the `DOMContentLoaded` event is fired. - `'load'` - consider navigation to be finished when the `load` event is fired. @@ -4001,7 +4156,7 @@ def goBack( def goForward( self, timeout: int = None, - waitUntil: Literal["load", "domcontentloaded", "networkidle"] = None, + waitUntil: Literal["domcontentloaded", "load", "networkidle"] = None, ) -> typing.Union["Response", NoneType]: """Page.goForward @@ -4011,7 +4166,7 @@ def goForward( ---------- timeout : Optional[int] Maximum navigation time in milliseconds, defaults to 30 seconds, pass `0` to disable timeout. The default value can be changed by using the browserContext.setDefaultNavigationTimeout(timeout), browserContext.setDefaultTimeout(timeout), page.setDefaultNavigationTimeout(timeout) or page.setDefaultTimeout(timeout) methods. - waitUntil : Optional[Literal['load', 'domcontentloaded', 'networkidle']] + waitUntil : Optional[Literal['domcontentloaded', 'load', 'networkidle']] When to consider navigation succeeded, defaults to `load`. Events can be either: - `'domcontentloaded'` - consider navigation to be finished when the `DOMContentLoaded` event is fired. - `'load'` - consider navigation to be finished when the `load` event is fired. @@ -4029,17 +4184,17 @@ def goForward( def emulateMedia( self, - media: Literal["screen", "print"] = None, - colorScheme: Literal["light", "dark", "no-preference"] = None, + media: Literal["print", "screen"] = None, + colorScheme: Literal["dark", "light", "no-preference"] = None, ) -> NoneType: """Page.emulateMedia Parameters ---------- - media : Optional[Literal['screen', 'print']] + media : Optional[Literal['print', 'screen']] Changes the CSS media type of the page. The only allowed values are `'screen'`, `'print'` and `null`. Passing `null` disables CSS media emulation. Omitting `media` or passing `undefined` does not change the emulated value. - colorScheme : Optional[Literal['light', 'dark', 'no-preference']] + colorScheme : Optional[Literal['dark', 'light', 'no-preference']] Emulates `'prefers-colors-scheme'` media feature, supported values are `'light'`, `'dark'`, `'no-preference'`. Passing `null` disables color scheme emulation. Omitting `colorScheme` or passing `undefined` does not change the emulated value. """ return mapping.from_maybe_impl( @@ -4089,7 +4244,7 @@ def addInitScript( Adds a script which would be evaluated in one of the following scenarios: Whenever the page is navigated. - Whenever the child frame is attached or navigated. In this case, the scritp is evaluated in the context of the newly attached frame. + Whenever the child frame is attached or navigated. In this case, the script is evaluated in the context of the newly attached frame. The script is evaluated after the document was created but before any of its scripts were run. This is useful to amend the JavaScript environment, e.g. to seed `Math.random`. An example of overriding `Math.random` before the page loads: @@ -4162,7 +4317,7 @@ def unroute( def screenshot( self, timeout: int = None, - type: Literal["png", "jpeg"] = None, + type: Literal["jpeg", "png"] = None, path: typing.Union[str, pathlib.Path] = None, quality: int = None, omitBackground: bool = None, @@ -4177,7 +4332,7 @@ def screenshot( ---------- timeout : Optional[int] Maximum time in milliseconds, defaults to 30 seconds, pass `0` to disable timeout. The default value can be changed by using the browserContext.setDefaultTimeout(timeout) or page.setDefaultTimeout(timeout) methods. - type : Optional[Literal['png', 'jpeg']] + type : Optional[Literal['jpeg', 'png']] Specify screenshot type, defaults to `png`. path : Union[str, pathlib.Path, NoneType] The file path to save the image to. The screenshot type will be inferred from file extension. If `path` is a relative path, then it is resolved relative to current working directory. If no path is provided, the image won't be saved to the disk. @@ -4259,7 +4414,7 @@ def click( ] = None, position: MousePosition = None, delay: int = None, - button: Literal["left", "right", "middle"] = None, + button: Literal["left", "middle", "right"] = None, clickCount: int = None, timeout: int = None, force: bool = None, @@ -4267,8 +4422,15 @@ def click( ) -> NoneType: """Page.click - This method waits for an element matching `selector`, waits for actionability checks, then scrolls the element into view if needed and uses page.mouse to click in the center of the element. - If there's no element matching `selector`, the method waits until a matching element appears in the DOM. If the element is detached during the actionability checks, the action is retried. + This method clicks an element matching `selector` by performing the following steps: + + Find an element match matching `selector`. If there is none, wait until a matching element is attached to the DOM. + Wait for actionability checks on the matched element, unless `force` option is set. If the element is detached during the checks, the whole action is retried. + Scroll the element into view if needed. + Use page.mouse to click in the center of the element, or the specified `position`. + Wait for initiated navigations to either succeed or fail, unless `noWaitAfter` option is set. + + When all steps combined have not finished during the specified `timeout`, this method rejects with a TimeoutError. Passing zero timeout disables this. Shortcut for page.mainFrame().click(selector[, options]). Parameters @@ -4281,7 +4443,7 @@ def click( A point to click relative to the top-left corner of element padding box. If not specified, clicks to some visible point of the element. delay : Optional[int] Time to wait between `mousedown` and `mouseup` in milliseconds. Defaults to 0. - button : Optional[Literal['left', 'right', 'middle']] + button : Optional[Literal['left', 'middle', 'right']] Defaults to `left`. clickCount : Optional[int] defaults to 1. See UIEvent.detail. @@ -4316,15 +4478,21 @@ def dblclick( ] = None, position: MousePosition = None, delay: int = None, - button: Literal["left", "right", "middle"] = None, + button: Literal["left", "middle", "right"] = None, timeout: int = None, force: bool = None, ) -> NoneType: """Page.dblclick - This method waits for an element matching `selector`, waits for actionability checks, then scrolls the element into view if needed and uses page.mouse to double click in the center of the element. - If there's no element matching `selector`, the method waits until a matching element appears in the DOM. If the element is detached during the actionability checks, the action is retried. - Bear in mind that if the first click of the `dblclick()` triggers a navigation event, there will be an exception. + This method double clicks an element matching `selector` by performing the following steps: + + Find an element match matching `selector`. If there is none, wait until a matching element is attached to the DOM. + Wait for actionability checks on the matched element, unless `force` option is set. If the element is detached during the checks, the whole action is retried. + Scroll the element into view if needed. + Use page.mouse to double click in the center of the element, or the specified `position`. + Wait for initiated navigations to either succeed or fail, unless `noWaitAfter` option is set. Note that if the first click of the `dblclick()` triggers a navigation event, this method will reject. + + When all steps combined have not finished during the specified `timeout`, this method rejects with a TimeoutError. Passing zero timeout disables this. **NOTE** `page.dblclick()` dispatches two `click` events and a single `dblclick` event. @@ -4340,7 +4508,7 @@ def dblclick( A point to double click relative to the top-left corner of element padding box. If not specified, double clicks to some visible point of the element. delay : Optional[int] Time to wait between `mousedown` and `mouseup` in milliseconds. Defaults to 0. - button : Optional[Literal['left', 'right', 'middle']] + button : Optional[Literal['left', 'middle', 'right']] Defaults to `left`. timeout : Optional[int] Maximum time in milliseconds, defaults to 30 seconds, pass `0` to disable timeout. The default value can be changed by using the browserContext.setDefaultTimeout(timeout) or page.setDefaultTimeout(timeout) methods. @@ -4514,8 +4682,15 @@ def hover( ) -> NoneType: """Page.hover - This method waits for an element matching `selector`, waits for actionability checks, then scrolls the element into view if needed and uses page.mouse to hover over the center of the element. - If there's no element matching `selector`, the method waits until a matching element appears in the DOM. If the element is detached during the actionability checks, the action is retried. + This method hovers over an element matching `selector` by performing the following steps: + + Find an element match matching `selector`. If there is none, wait until a matching element is attached to the DOM. + Wait for actionability checks on the matched element, unless `force` option is set. If the element is detached during the checks, the whole action is retried. + Scroll the element into view if needed. + Use page.mouse to hover over the center of the element, or the specified `position`. + Wait for initiated navigations to either succeed or fail, unless `noWaitAfter` option is set. + + When all steps combined have not finished during the specified `timeout`, this method rejects with a TimeoutError. Passing zero timeout disables this. Shortcut for page.mainFrame().hover(selector[, options]). Parameters @@ -4717,8 +4892,17 @@ def check( ) -> NoneType: """Page.check - This method waits for an element matching `selector`, waits for actionability checks. Then, if the element is not already checked, this method scrolls the element into view and uses elementHandle.click to click in the center of the element. - If there's no element matching `selector`, the method waits until a matching element appears in the DOM. If the element is detached during the actionability checks, the action is retried. + This method checks an element matching `selector` by performing the following steps: + + Find an element match matching `selector`. If there is none, wait until a matching element is attached to the DOM. + Ensure that matched element is a checkbox or a radio input. If not, this method rejects. If the element is already checked, this method returns immediately. + Wait for actionability checks on the matched element, unless `force` option is set. If the element is detached during the checks, the whole action is retried. + Scroll the element into view if needed. + Use page.mouse to click in the center of the element. + Wait for initiated navigations to either succeed or fail, unless `noWaitAfter` option is set. + Ensure that the element is now checked. If not, this method rejects. + + When all steps combined have not finished during the specified `timeout`, this method rejects with a TimeoutError. Passing zero timeout disables this. Shortcut for page.mainFrame().check(selector[, options]). Parameters @@ -4752,8 +4936,17 @@ def uncheck( ) -> NoneType: """Page.uncheck - This method waits for an element matching `selector`, waits for actionability checks. Then, if the element is not already unchecked, this method scrolls the element into view and uses elementHandle.click to click in the center of the element. - If there's no element matching `selector`, the method waits until a matching element appears in the DOM. If the element is detached during the actionability checks, the action is retried. + This method unchecks an element matching `selector` by performing the following steps: + + Find an element match matching `selector`. If there is none, wait until a matching element is attached to the DOM. + Ensure that matched element is a checkbox or a radio input. If not, this method rejects. If the element is already unchecked, this method returns immediately. + Wait for actionability checks on the matched element, unless `force` option is set. If the element is detached during the checks, the whole action is retried. + Scroll the element into view if needed. + Use page.mouse to click in the center of the element. + Wait for initiated navigations to either succeed or fail, unless `noWaitAfter` option is set. + Ensure that the element is now unchecked. If not, this method rejects. + + When all steps combined have not finished during the specified `timeout`, this method rejects with a TimeoutError. Passing zero timeout disables this. Shortcut for page.mainFrame().uncheck(selector[, options]). Parameters @@ -5007,7 +5200,7 @@ def expect_file_chooser( def expect_load_state( self, - state: Literal["load", "domcontentloaded", "networkidle"] = None, + state: Literal["domcontentloaded", "load", "networkidle"] = None, timeout: int = None, ) -> EventContextManager[typing.Union["Response", NoneType]]: return EventContextManager( @@ -5017,7 +5210,7 @@ def expect_load_state( def expect_navigation( self, url: typing.Union[str, typing.Pattern, typing.Callable[[str], bool]] = None, - waitUntil: Literal["load", "domcontentloaded", "networkidle"] = None, + waitUntil: Literal["domcontentloaded", "load", "networkidle"] = None, timeout: int = None, ) -> EventContextManager[typing.Union["Response", NoneType]]: return EventContextManager( @@ -5590,7 +5783,7 @@ def newContext( deviceScaleFactor: int = None, isMobile: bool = None, hasTouch: bool = None, - colorScheme: Literal["light", "dark", "no-preference"] = None, + colorScheme: Literal["dark", "light", "no-preference"] = None, acceptDownloads: bool = None, defaultBrowserType: str = None, ) -> "BrowserContext": @@ -5629,7 +5822,7 @@ def newContext( Whether the `meta viewport` tag is taken into account and touch events are enabled. Defaults to `false`. Not supported in Firefox. hasTouch : Optional[bool] Specifies if viewport supports touch events. Defaults to false. - colorScheme : Optional[Literal['light', 'dark', 'no-preference']] + colorScheme : Optional[Literal['dark', 'light', 'no-preference']] Emulates `'prefers-colors-scheme'` media feature, supported values are `'light'`, `'dark'`, `'no-preference'`. See page.emulateMedia(options) for more details. Defaults to '`light`'. acceptDownloads : Optional[bool] Whether to automatically download all the attachments. Defaults to `false` where all the downloads are canceled. @@ -5680,7 +5873,7 @@ def newPage( deviceScaleFactor: int = None, isMobile: bool = None, hasTouch: bool = None, - colorScheme: Literal["light", "dark", "no-preference"] = None, + colorScheme: Literal["dark", "light", "no-preference"] = None, acceptDownloads: bool = None, ) -> "Page": """Browser.newPage @@ -5719,7 +5912,7 @@ def newPage( Whether the `meta viewport` tag is taken into account and touch events are enabled. Defaults to `false`. Not supported in Firefox. hasTouch : Optional[bool] Specifies if viewport supports touch events. Defaults to false. - colorScheme : Optional[Literal['light', 'dark', 'no-preference']] + colorScheme : Optional[Literal['dark', 'light', 'no-preference']] Emulates `'prefers-colors-scheme'` media feature, supported values are `'light'`, `'dark'`, `'no-preference'`. See page.emulateMedia(options) for more details. Defaults to '`light`'. acceptDownloads : Optional[bool] Whether to automatically download all the attachments. Defaults to `false` where all the downloads are canceled. @@ -5906,7 +6099,7 @@ def launchPersistentContext( deviceScaleFactor: int = None, isMobile: bool = None, hasTouch: bool = None, - colorScheme: Literal["light", "dark", "no-preference"] = None, + colorScheme: Literal["dark", "light", "no-preference"] = None, acceptDownloads: bool = None, chromiumSandbox: bool = None, ) -> "BrowserContext": @@ -5973,7 +6166,7 @@ def launchPersistentContext( Whether the `meta viewport` tag is taken into account and touch events are enabled. Defaults to `false`. Not supported in Firefox. hasTouch : Optional[bool] Specifies if viewport supports touch events. Defaults to false. - colorScheme : Optional[Literal['light', 'dark', 'no-preference']] + colorScheme : Optional[Literal['dark', 'light', 'no-preference']] Emulates `'prefers-colors-scheme'` media feature, supported values are `'light'`, `'dark'`, `'no-preference'`. See page.emulateMedia(options) for more details. Defaults to '`light`'. acceptDownloads : Optional[bool] Whether to automatically download all the attachments. Defaults to `false` where all the downloads are canceled. diff --git a/scripts/documentation_provider.py b/scripts/documentation_provider.py index 9ba78de7e..b064e0546 100644 --- a/scripts/documentation_provider.py +++ b/scripts/documentation_provider.py @@ -19,6 +19,7 @@ Any, Dict, List, + Set, Union, get_args, get_origin, @@ -43,29 +44,6 @@ }, } -expected_mismatches = [ - "Download.createReadStream", - "Browser.startTracing", - "Browser.stopTracing", - "Logger.log", - "BrowserContext.setHTTPCredentials", # deprecated - "BrowserContext.serviceWorkers", # CR only (and the following) - "BrowserContext.backgroundPages", - "Browser.newBrowserCDPSession", - "Page.coverage", - "Coverage.startCSSCoverage", - "Coverage.stopCSSCoverage", - "Coverage.startJSCoverage", - "Coverage.stopJSCoverage", - "BrowserContext.newCDPSession", - "Logger.isEnabled", - "BrowserServer.kill", # not relevant for RPC clients (and the following) - "BrowserType.launchServer", - "BrowserServer.close", - "BrowserServer.process", - "BrowserServer.wsEndpoint", -] - class DocumentationProvider: def __init__(self) -> None: @@ -73,6 +51,7 @@ def __init__(self) -> None: self.printed_entries: List[str] = [] with open("api.json") as json_file: self.api = json.load(json_file) + self.errors: Set[str] = set() method_name_rewrites: Dict[str, str] = { "continue_": "continue", @@ -134,9 +113,8 @@ def print_entry( args = args["viewportSize"]["type"]["properties"] doc_value = args.get(name) if not doc_value: - print( - f"Missing parameter documentation: {fqname}({name}=)", - file=stderr, + self.errors.add( + f"Missing parameter documentation: {fqname}({name}=)" ) else: code_type = self.serialize_python_type(value) @@ -172,9 +150,8 @@ def print_entry( if signature_no_return: for name in signature_no_return: - print( - f"Parameter not implemented: {class_name}.{method_name}({name}=)", - file=stderr, + self.errors.add( + f"Parameter not implemented: {class_name}.{method_name}({name}=)" ) def indent_paragraph(self, p: str, indent: str) -> str: @@ -228,9 +205,8 @@ def compare_types(self, value: Any, doc_value: Any, fqname: str) -> None: return if doc_type != code_type: - print( - f"Parameter type mismatch in {fqname}: documented as {doc_type}, code has {code_type}", - file=stderr, + self.errors.add( + f"Parameter type mismatch in {fqname}: documented as {doc_type}, code has {code_type}" ) def serialize_python_type(self, value: Any) -> str: @@ -394,7 +370,6 @@ def rewrite_param_name(self, fqname: str, method_name: str, name: str) -> str: return name def print_remainder(self) -> None: - remainders = set() for [class_name, value] in self.api.items(): class_name = re.sub(r"Chromium(.*)", r"\1", class_name) class_name = re.sub(r"WebKit(.*)", r"\1", class_name) @@ -403,14 +378,19 @@ def print_remainder(self) -> None: if method["kind"] == "event": continue entry = f"{class_name}.{method_name}" - if ( - entry not in self.printed_entries - and entry not in expected_mismatches - ): - remainders.add(f"Method not implemented: {entry}") - for remainder in remainders: - print(remainder, file=stderr) - if len(remainders) > 0: + if entry not in self.printed_entries: + self.errors.add(f"Method not implemented: {entry}") + + with open("scripts/expected_api_mismatch.txt") as f: + for line in f.readlines(): + sline = line.strip() + if not len(sline) or sline.startswith("#"): + continue + self.errors.remove(sline) + + if len(self.errors) > 0: + for error in self.errors: + print(error, file=stderr) exit(1) diff --git a/scripts/expected_api_mismatch.txt b/scripts/expected_api_mismatch.txt new file mode 100644 index 000000000..d77871846 --- /dev/null +++ b/scripts/expected_api_mismatch.txt @@ -0,0 +1,102 @@ +# Missing methods +Method not implemented: Browser.newBrowserCDPSession +Method not implemented: Browser.startTracing +Method not implemented: Browser.stopTracing +Method not implemented: BrowserContext.backgroundPages +Method not implemented: BrowserContext.newCDPSession +Method not implemented: BrowserContext.serviceWorkers +Method not implemented: BrowserContext.setHTTPCredentials +Method not implemented: BrowserServer.close +Method not implemented: BrowserServer.kill +Method not implemented: BrowserServer.process +Method not implemented: BrowserServer.wsEndpoint +Method not implemented: BrowserType.launchServer +Method not implemented: Coverage.startCSSCoverage +Method not implemented: Coverage.startJSCoverage +Method not implemented: Coverage.stopCSSCoverage +Method not implemented: Coverage.stopJSCoverage +Method not implemented: Download.createReadStream +Method not implemented: Logger.isEnabled +Method not implemented: Logger.log +Method not implemented: Page.coverage + +# Parameter overloads +Missing parameter documentation: BrowserContext.waitForEvent(predicate=) +Missing parameter documentation: BrowserContext.waitForEvent(timeout=) +Missing parameter documentation: Page.waitForEvent(predicate=) +Missing parameter documentation: Page.waitForEvent(timeout=) +Missing parameter documentation: Page.waitForRequest(predicate=) +Missing parameter documentation: Page.waitForResponse(predicate=) +Missing parameter documentation: Selectors.register(path=) + +# Documented as Dict / Any +Parameter type mismatch in BrowserContext.setGeolocation(geolocation=): documented as Optional[Dict], code has Optional[{"latitude": float, "longitude": float, "accuracy": Optional[float]}] +Parameter type mismatch in BrowserContext.waitForEvent(return=): documented as Dict, code has Any +Parameter type mismatch in Browser.newContext(viewport=): documented as Optional[Dict], code has Union[{"width": int, "height": int}, '0', NoneType] +Parameter type mismatch in Browser.newPage(viewport=): documented as Optional[Dict], code has Union[{"width": int, "height": int}, '0', NoneType] +Parameter type mismatch in BrowserType.launchPersistentContext(viewport=): documented as Optional[Dict], code has Optional[{"width": int, "height": int}] +Parameter type mismatch in ElementHandle.boundingBox(return=): documented as Optional[Dict], code has Optional[{"x": float, "y": float, "width": float, "height": float}] +Parameter type mismatch in Page.viewportSize(return=): documented as Optional[Dict], code has Optional[{"width": int, "height": int}] +Parameter type mismatch in Page.waitForEvent(return=): documented as Dict, code has Any +Parameter type mismatch in Request.failure(return=): documented as Optional[Dict], code has Optional[{"errorText": str}] +Parameter type mismatch in Response.json(return=): documented as Any, code has Union[Dict, List] + +# Pathlib +Parameter type mismatch in BrowserType.launch(executablePath=): documented as Optional[str], code has Union[str, pathlib.Path, NoneType] +Parameter type mismatch in BrowserType.launch(downloadsPath=): documented as Optional[str], code has Union[str, pathlib.Path, NoneType] +Parameter type mismatch in BrowserType.launchPersistentContext(downloadsPath=): documented as Optional[str], code has Union[str, pathlib.Path, NoneType] +Parameter type mismatch in BrowserType.launchPersistentContext(executablePath=): documented as Optional[str], code has Union[str, pathlib.Path, NoneType] +Parameter type mismatch in BrowserType.launchPersistentContext(userDataDir=): documented as str, code has Union[str, pathlib.Path] +Parameter type mismatch in Download.saveAs(path=): documented as str, code has Union[str, pathlib.Path] +Parameter type mismatch in ElementHandle.screenshot(path=): documented as Optional[str], code has Union[str, pathlib.Path, NoneType] +Parameter type mismatch in Frame.addScriptTag(path=): documented as Optional[str], code has Union[str, pathlib.Path, NoneType] +Parameter type mismatch in Frame.addStyleTag(path=): documented as Optional[str], code has Union[str, pathlib.Path, NoneType] +Parameter type mismatch in Page.addScriptTag(path=): documented as Optional[str], code has Union[str, pathlib.Path, NoneType] +Parameter type mismatch in Page.addStyleTag(path=): documented as Optional[str], code has Union[str, pathlib.Path, NoneType] +Parameter type mismatch in Page.screenshot(path=): documented as Optional[str], code has Union[str, pathlib.Path, NoneType] +Parameter type mismatch in Page.pdf(path=): documented as Optional[str], code has Union[str, pathlib.Path, NoneType] + +# Pattern +Parameter type mismatch in BrowserContext.route(url=): documented as Union[str, RegExp, function(URL):boolean], code has Union[str, Pattern, typing.Callable[[str], bool]] +Parameter type mismatch in BrowserContext.unroute(url=): documented as Union[str, RegExp, function(URL):boolean], code has Union[str, Pattern, typing.Callable[[str], bool]] +Parameter type mismatch in Frame.waitForNavigation(url=): documented as Union[str, RegExp, Function, NoneType], code has Union[str, Pattern, typing.Callable[[str], bool], NoneType] +Parameter type mismatch in Page.frame(url=): documented as Union[str, RegExp, Function, NoneType], code has Union[str, Pattern, typing.Callable[[str], bool], NoneType] +Parameter type mismatch in Page.route(url=): documented as Union[str, RegExp, function(URL):boolean], code has Union[str, Pattern, typing.Callable[[str], bool]] +Parameter type mismatch in Page.unroute(url=): documented as Union[str, RegExp, function(URL):boolean], code has Union[str, Pattern, typing.Callable[[str], bool]] +Parameter type mismatch in Page.waitForNavigation(url=): documented as Union[str, RegExp, Function, NoneType], code has Union[str, Pattern, typing.Callable[[str], bool], NoneType] +Parameter type mismatch in Page.waitForRequest(urlOrPredicate=): documented as Union[str, RegExp, Function], code has Union[str, Pattern, typing.Callable[[str], bool], NoneType] +Parameter type mismatch in Page.waitForResponse(urlOrPredicate=): documented as Union[str, RegExp, Function], code has Union[str, Pattern, typing.Callable[[str], bool], NoneType] + +# Add init script +Parameter type mismatch in Page.addInitScript(script=): documented as Union[Callable, str, Dict], code has Optional[str] +Parameter type mismatch in BrowserContext.addInitScript(script=): documented as Union[Callable, str, Dict], code has Optional[str] +Missing parameter documentation: BrowserContext.addInitScript(path=) +Missing parameter documentation: Page.addInitScript(path=) + +# File payload +Parameter type mismatch in FileChooser.setFiles(files=): documented as Union[str, List[str], Dict, List[Dict]], code has Union[str, {"name": str, "mimeType": str, "buffer": Union[bytes, str]}, List[str], List[{"name": str, "mimeType": str, "buffer": Union[bytes, str]}]] +Parameter type mismatch in Page.setInputFiles(files=): documented as Union[str, List[str], Dict, List[Dict]], code has Union[str, {"name": str, "mimeType": str, "buffer": Union[bytes, str]}, List[str], List[{"name": str, "mimeType": str, "buffer": Union[bytes, str]}]] +Parameter type mismatch in ElementHandle.setInputFiles(files=): documented as Union[str, List[str], Dict, List[Dict]], code has Union[str, pathlib.Path, {"name": str, "mimeType": str, "buffer": Union[bytes, str]}, List[str], List[pathlib.Path], List[{"name": str, "mimeType": str, "buffer": Union[bytes, str]}]] +Parameter type mismatch in Frame.setInputFiles(files=): documented as Union[str, List[str], Dict, List[Dict]], code has Union[str, pathlib.Path, {"name": str, "mimeType": str, "buffer": Union[bytes, str]}, List[str], List[pathlib.Path], List[{"name": str, "mimeType": str, "buffer": Union[bytes, str]}]] + +# Select option +Parameter type mismatch in ElementHandle.selectOption(values=): documented as Union[str, ElementHandle, List[str], Dict, List[ElementHandle], List[Dict], NoneType], code has Union[str, ElementHandle, {"value": Optional[str], "label": Optional[str], "index": Optional[str]}, List[str], List[ElementHandle], List[{"value": Optional[str], "label": Optional[str], "index": Optional[str]}], NoneType] +Parameter type mismatch in Frame.selectOption(values=): documented as Union[str, ElementHandle, List[str], Dict, List[ElementHandle], List[Dict], NoneType], code has Union[str, ElementHandle, {"value": Optional[str], "label": Optional[str], "index": Optional[str]}, List[str], List[ElementHandle], List[{"value": Optional[str], "label": Optional[str], "index": Optional[str]}], NoneType] +Parameter type mismatch in Page.selectOption(values=): documented as Union[str, ElementHandle, List[str], Dict, List[ElementHandle], List[Dict], NoneType], code has Union[str, ElementHandle, {"value": Optional[str], "label": Optional[str], "index": Optional[str]}, List[str], List[ElementHandle], List[{"value": Optional[str], "label": Optional[str], "index": Optional[str]}], NoneType] + +# Evaluation argument +Parameter type mismatch in ElementHandle.dispatchEvent(eventInit=): documented as Optional[EvaluationArgument], code has Optional[Dict] +Parameter type mismatch in Frame.dispatchEvent(eventInit=): documented as Optional[EvaluationArgument], code has Optional[Dict] +Parameter type mismatch in Page.dispatchEvent(eventInit=): documented as Optional[EvaluationArgument], code has Optional[Dict] + +# Route +Parameter type mismatch in BrowserContext.route(handler=): documented as function(Route, Request), code has typing.Callable[[playwright.network.Route, playwright.network.Request], typing.Any] +Parameter type mismatch in BrowserContext.unroute(handler=): documented as Optional[function(Route, Request)], code has Optional[typing.Callable[[playwright.network.Route, playwright.network.Request], typing.Any]] +Parameter type mismatch in Page.route(handler=): documented as function(Route, Request), code has typing.Callable[[playwright.network.Route, playwright.network.Request], typing.Any] +Parameter type mismatch in Page.unroute(handler=): documented as Optional[function(Route, Request)], code has Optional[typing.Callable[[playwright.network.Route, playwright.network.Request], typing.Any]] + +# Selectors +Parameter type mismatch in Selectors.register(script=): documented as Union[Callable, str, Dict], code has Optional[str] + +# Device support +Missing parameter documentation: Browser.newContext(defaultBrowserType=)