microsoft/playwright
1
1
Fork 0
mirror of https://github.com/microsoft/playwright.git synced 2024-12-13 17:14:02 +03:00
Code Issues Projects Releases Wiki Activity

docs: document Python's expect_event methods (#4963)

Browse Source
This commit is contained in:
Pavel Feldman 2021-01-10 21:00:52 -08:00 committed by GitHub
parent e67d89747a
commit 4dbbb47583
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
6 changed files with 347 additions and 27 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

10
docs/src/api/class-frame.md
View File

@ -856,15 +856,7 @@ await frame.click('button'); // Click triggers navigation.
await frame.waitForLoadState(); // Waits for 'load' state by default.
```
### param: Frame.waitForLoadState.state
- `state` <"load"|"domcontentloaded"|"networkidle">
Optional load state to wait for, defaults to `load`. If the state has been already reached while loading current document, the
method returns immediately. Can be one of:
* `'load'` - wait for the `load` event to be fired.
* `'domcontentloaded'` - wait for the `DOMContentLoaded` event to be fired.
* `'networkidle'` - wait until there are no network connections for at least `500` ms.
### param: Frame.waitForLoadState.state = %%-wait-for-load-state-state-%%
### option: Frame.waitForLoadState.timeout = %%-navigation-timeout-%%
## async method: Frame.waitForNavigation

20
docs/src/api/class-page.md
View File

@ -1608,10 +1608,7 @@ Returns the event data value.
Waits for event to fire and passes its value into the predicate function. Returns when the predicate returns truthy
value. Will throw an error if the page is closed before the event is fired.
### param: Page.waitForEvent.event
- `event` <[string]>
Event name, same one would pass into `page.on(event)`.
### param: Page.waitForEvent.event = %%-wait-for-event-event-%%
### param: Page.waitForEvent.optionsOrPredicate
* langs: js
@ -1693,15 +1690,7 @@ console.log(await popup.title()); // Popup is ready to use.
Shortcut for main frame's [`method: Frame.waitForLoadState`].
### param: Page.waitForLoadState.state
- `state` <"load"|"domcontentloaded"|"networkidle">
Optional load state to wait for, defaults to `load`. If the state has been already reached while loading current document, the
method resolves immediately. Can be one of:
* `'load'` - wait for the `load` event to be fired.
* `'domcontentloaded'` - wait for the `DOMContentLoaded` event to be fired.
* `'networkidle'` - wait until there are no network connections for at least `500` ms.
### param: Page.waitForLoadState.state = %%-wait-for-load-state-state-%%
### option: Page.waitForLoadState.timeout = %%-navigation-timeout-%%
## async method: Page.waitForNavigation
@ -1729,10 +1718,7 @@ Shortcut for main frame's [`method: Frame.waitForNavigation`].
### option: Page.waitForNavigation.timeout = %%-navigation-timeout-%%
### option: Page.waitForNavigation.url
- `url` <[string]|[RegExp]|[function]\([URL]\):[boolean]>
A glob pattern, regex pattern or predicate receiving [URL] to match while waiting for the navigation.
### option: Page.waitForNavigation.url = %%-wait-for-navigation-url-%%
### option: Page.waitForNavigation.waitUntil = %%-navigation-wait-until-%%

19
docs/src/api/params.md
View File

@ -322,6 +322,25 @@ Options to select. If the `<select>` has the `multiple` attribute, all matching
first option matching one of the passed options is selected. String values are equivalent to `{value:'string'}`. Option
is considered matching if all specified properties match.
## wait-for-navigation-url
- `url` <[string]|[RegExp]|[function]\([URL]\):[boolean]>
A glob pattern, regex pattern or predicate receiving [URL] to match while waiting for the navigation.
## wait-for-event-event
- `event` <[string]>
Event name, same one typically passed into `page.on(event)`.
## wait-for-load-state-state
- `state` <"load"|"domcontentloaded"|"networkidle">
Optional load state to wait for, defaults to `load`. If the state has been already reached while loading current document, the
method resolves immediately. Can be one of:
* `'load'` - wait for the `load` event to be fired.
* `'domcontentloaded'` - wait for the `DOMContentLoaded` event to be fired.
* `'networkidle'` - wait until there are no network connections for at least `500` ms.
## python-select-options-element
* langs: python
- `element` <[ElementHandle]|[Array]<[ElementHandle]>>

317
docs/src/api/python.md
View File

@ -116,6 +116,323 @@ page.on('requestfailed', lambda request: print(request.url + ' ' + request.failu
Waits for this response to finish, returns failure error if request failed.
## async method: Page.expectEvent
* langs: python
- returns: <[EventContextManager]>
Performs action and waits for given `event` to fire. If predicate is provided, it passes
event's value into the `predicate` function and waits for `predicate(event)` to return a truthy value.
Will throw an error if the page is closed before the `event` is fired.
```python-async
async with page.expect_event(event_name) as event_info:
await page.click("button")
value = await event_info.value
```
```python-sync
with page.expect_event(event_name) as event_info:
page.click("button")
value = event_info.value
```
### param: Page.expectEvent.event = %%-wait-for-event-event-%%
### option: Page.expectEvent.predicate = %%-python-wait-for-event-predicate-%%
### option: Page.expectEvent.timeout = %%-python-wait-for-event-timeout-%%
## async method: BrowserContext.expectEvent
* langs: python
- returns: <[EventContextManager]>
Performs action and waits for given `event` to fire. If predicate is provided, it passes
event's value into the `predicate` function and waits for `predicate(event)` to return a truthy value.
Will throw an error if browser context is closed before the `event` is fired.
```python-async
async with context.expect_event(event_name) as event_info:
await context.click("button")
value = await event_info.value
```
```python-sync
with context.expect_event(event_name) as event_info:
context.click("button")
value = event_info.value
```
### param: BrowserContext.expectEvent.event = %%-wait-for-event-event-%%
### option: BrowserContext.expectEvent.predicate = %%-python-wait-for-event-predicate-%%
### option: BrowserContext.expectEvent.timeout = %%-python-wait-for-event-timeout-%%
## async method: WebSocket.expectEvent
* langs: python
- returns: <[EventContextManager]>
Performs action and waits for given `event` to fire. If predicate is provided, it passes
event's value into the `predicate` function and waits for `predicate(event)` to return a truthy value.
Will throw an error if the socket is closed before the `event` is fired.
```python-async
async with ws.expect_event(event_name) as event_info:
await ws.click("button")
value = await event_info.value
```
```python-sync
with ws.expect_event(event_name) as event_info:
ws.click("button")
value = event_info.value
```
### param: WebSocket.expectEvent.event = %%-wait-for-event-event-%%
### option: WebSocket.expectEvent.predicate = %%-python-wait-for-event-predicate-%%
### option: WebSocket.expectEvent.timeout = %%-python-wait-for-event-timeout-%%
## async method: Page.expectLoadState
* langs: python
- returns: <[EventContextManager]>
Performs action and waits for the required load state. It resolves when the page reaches a required load state, `load` by default. The navigation must have been committed when this method is called. If current document has
already reached the required state, resolves immediately.
```python-async
async with page.expect_load_state():
await page.click('button') # Click triggers navigation.
# Context manager waits for 'load' event.
```
```python-sync
with page.expect_load_state():
page.click('button') # Click triggers navigation.
# Context manager waits for 'load' event.
```
Shortcut for main frame's [`method: Frame.expectLoadState`].
### param: Page.expectLoadState.state = %%-wait-for-load-state-state-%%
### option: Page.expectLoadState.timeout = %%-navigation-timeout-%%
## async method: Frame.expectLoadState
* langs: python
- returns: <[EventContextManager]>
Performs action and waits for the required load state. It resolves when the page reaches a required load state, `load` by default. The navigation must have been committed when this method is called. If current document has
already reached the required state, resolves immediately.
```python-async
async with frame.expect_load_state():
await frame.click('button') # Click triggers navigation.
# Context manager waits for 'load' event.
```
```python-sync
with frame.expect_load_state():
frame.click('button') # Click triggers navigation.
# Context manager waits for 'load' event.
```
### param: Frame.expectLoadState.state = %%-wait-for-load-state-state-%%
### option: Frame.expectLoadState.timeout = %%-navigation-timeout-%%
## async method: Page.expectNavigation
* langs: python
- returns: <[EventContextManager]>
Performs action and wait for the next navigation. 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`.
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. e.g. The click target has an `onclick` handler that triggers navigation
from a `setTimeout`. Consider this example:
```python-async
async with page.expect_navigation():
await page.click("a.delayed-navigation") # Clicking the link will indirectly cause a navigation
# Context manager waited for the navigation to happen.
```
```python-sync
with page.expect_navigation():
page.click("a.delayed-navigation") # Clicking the link will indirectly cause a navigation
# Context manager waited for the navigation to happen.
```
**NOTE** Usage of the [History API](https://developer.mozilla.org/en-US/docs/Web/API/History_API) to change the
URL is considered a navigation.
Shortcut for main frame's [`method: Frame.expectNavigation`].
### option: Page.expectNavigation.timeout = %%-navigation-timeout-%%
### option: Page.expectNavigation.url = %%-wait-for-navigation-url-%%
### option: Page.expectNavigation.waitUntil = %%-navigation-wait-until-%%
## async method: Frame.expectNavigation
* langs: python
- returns: <[EventContextManager]>
Performs action and wait for the next navigation. 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`.
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. e.g. The click target has an `onclick` handler that triggers navigation
from a `setTimeout`. Consider this example:
```python-async
async with frame.expect_navigation():
await frame.click("a.delayed-navigation") # Clicking the link will indirectly cause a navigation
# Context manager waited for the navigation to happen.
```
```python-sync
with frame.expect_navigation():
frame.click("a.delayed-navigation") # Clicking the link will indirectly cause a navigation
# Context manager waited for the navigation to happen.
```
**NOTE** Usage of the [History API](https://developer.mozilla.org/en-US/docs/Web/API/History_API) to change the
URL is considered a navigation.
### option: Frame.expectNavigation.timeout = %%-navigation-timeout-%%
### option: Frame.expectNavigation.url = %%-wait-for-navigation-url-%%
### option: Frame.expectNavigation.waitUntil = %%-navigation-wait-until-%%
## async method: Page.expectDownload
* langs: python
- returns: <[EventContextManager]<[Download]>>
Performs action and waits for `download` event to fire. If predicate is provided, it passes
[Download] value into the `predicate` function and waits for `predicate(event)` to return a truthy value.
Will throw an error if the page is closed before the download event is fired.
### option: Page.expectDownload.predicate =
* langs: python
- `predicate` <[function]\([Download]\):[bool]>
Receives the [Download] object and resolves to truthy value when the waiting should resolve.
### option: Page.expectDownload.timeout = %%-python-wait-for-event-timeout-%%
## async method: Page.expectPopup
* langs: python
- returns: <[EventContextManager]<[Page]>>
Performs action and waits for `popup` event to fire. If predicate is provided, it passes
[Popup] value into the `predicate` function and waits for `predicate(event)` to return a truthy value.
Will throw an error if the page is closed before the popup event is fired.
### option: Page.expectPopup.predicate =
* langs: python
- `predicate` <[function]\([Page]\):[bool]>
Receives the [Popup] object and resolves to truthy value when the waiting should resolve.
### option: Page.expectPopup.timeout = %%-python-wait-for-event-timeout-%%
## async method: Page.expectWorker
* langs: python
- returns: <[EventContextManager]<[Worker]>>
Performs action and waits for `worker` event to fire. If predicate is provided, it passes
[Worker] value into the `predicate` function and waits for `predicate(event)` to return a truthy value.
Will throw an error if the page is closed before the worker event is fired.
### option: Page.expectWorker.predicate =
* langs: python
- `predicate` <[function]\([Worker]\):[bool]>
Receives the [Worker] object and resolves to truthy value when the waiting should resolve.
### option: Page.expectWorker.timeout = %%-python-wait-for-event-timeout-%%
## async method: Page.expectConsoleMessage
* langs: python
- returns: <[EventContextManager]<[ConsoleMessage]>>
Performs action and waits for `console` event to fire. If predicate is provided, it passes
[ConsoleMessage] value into the `predicate` function and waits for `predicate(event)` to return a truthy value.
Will throw an error if the page is closed before the worker event is fired.
### option: Page.expectConsoleMessage.predicate =
* langs: python
- `predicate` <[function]\([ConsoleMessage]\):[bool]>
Receives the [ConsoleMessage] object and resolves to truthy value when the waiting should resolve.
### option: Page.expectConsoleMessage.timeout = %%-python-wait-for-event-timeout-%%
## async method: Page.expectFileChooser
* langs: python
- returns: <[EventContextManager]<[FileChooser]>>
Performs action and waits for `filechooser` event to fire. If predicate is provided, it passes
[FileChooser] value into the `predicate` function and waits for `predicate(event)` to return a truthy value.
Will throw an error if the page is closed before the worker event is fired.
### option: Page.expectFileChooser.predicate =
* langs: python
- `predicate` <[function]\([FileChooser]\):[bool]>
Receives the [FileChooser] object and resolves to truthy value when the waiting should resolve.
### option: Page.expectFileChooser.timeout = %%-python-wait-for-event-timeout-%%
## async method: BrowserContext.expectPage
* langs: python
- returns: <[EventContextManager]<[Page]>>
Performs action and waits for `page` event to fire. If predicate is provided, it passes
[Page] value into the `predicate` function and waits for `predicate(event)` to return a truthy value.
Will throw an error if the page is closed before the worker event is fired.
### option: BrowserContext.expectPage.predicate =
* langs: python
- `predicate` <[function]\([Page]\):[bool]>
Receives the [Page] object and resolves to truthy value when the waiting should resolve.
### option: BrowserContext.expectPage.timeout = %%-python-wait-for-event-timeout-%%
## async method: Page.expectRequest
* langs: python
- returns: <[EventContextManager]<[Request]>>
Performs action and waits for `response` event to fire. If predicate is provided, it passes
[Request] value into the `predicate` function and waits for `predicate(event)` to return a truthy value.
Will throw an error if the page is closed before the download event is fired.
### param: Page.expectRequest.url_or_predicate =
* langs: python
- `url_or_predicate` <[str]|[RegExp]|[function]\([Request]\):[bool]>
Receives the [Request] object and resolves to truthy value when the waiting should resolve.
### option: Page.expectRequest.timeout = %%-python-wait-for-event-timeout-%%
## async method: Page.expectResponse
* langs: python
- returns: <[EventContextManager]<[Response]>>
Performs action and waits for `response` event to fire. If predicate is provided, it passes
[Response] value into the `predicate` function and waits for `predicate(event)` to return a truthy value.
Will throw an error if the page is closed before the download event is fired.
### param: Page.expectResponse.url_or_predicate =
* langs: python
- `url_or_predicate` <[str]|[RegExp]|[function]\([Response]\):[bool]>
Receives the [Response] object and resolves to truthy value when the waiting should resolve.
### option: Page.expectResponse.timeout = %%-python-wait-for-event-timeout-%%
### option: BrowserContext.waitForEvent.predicate = %%-python-wait-for-event-predicate-%%
### option: BrowserContext.waitForEvent.timeout = %%-python-wait-for-event-timeout-%%

2
types/types.d.ts vendored
View File

@ -4499,7 +4499,7 @@ export interface Frame {
* await frame.waitForLoadState(); // Waits for 'load' state by default.
* ```
*
* @param state Optional load state to wait for, defaults to `load`. If the state has been already reached while loading current document, the method returns immediately. Can be one of:
* @param state Optional load state to wait for, defaults to `load`. If the state has been already reached while loading current document, the method resolves immediately. Can be one of:
* - `'load'` - wait for the `load` event to be fired.
* - `'domcontentloaded'` - wait for the `DOMContentLoaded` event to be fired.
* - `'networkidle'` - wait until there are no network connections for at least `500` ms.

6
utils/doclint/api_parser.js
View File

@ -77,6 +77,8 @@ class ApiParser {
*/
parseMember(spec) {
const match = spec.text.match(/(event|method|property|async method): ([^.]+)\.(.*)/);
if (!match)
throw new Error('Invalid member: ' + spec.text);
const name = match[3];
let returnType = null;
for (const item of spec.children || []) {
@ -106,7 +108,11 @@ class ApiParser {
parseArgument(spec) {
const match = spec.text.match(/(param|option): ([^.]+)\.([^.]+)\.(.*)/);
const clazz = this.classes.get(match[2]);
if (!clazz)
throw new Error('Invalid class ' + match[2]);
const method = clazz.membersArray.find(m => m.kind === 'method' && m.name === match[3]);
if (!method)
throw new Error('Invalid method ' + match[2] + '.' + match[3]);
if (match[1] === 'param') {
method.argsArray.push(this.parseProperty(spec));
} else {