diff --git a/README.md b/README.md
index bcf88ee0a..3bacdb735 100644
--- a/README.md
+++ b/README.md
@@ -4,9 +4,9 @@ Playwright is a Python library to automate [Chromium](https://www.chromium.org/H
| | Linux | macOS | Windows |
| :--- | :---: | :---: | :---: |
-| Chromium 109.0.5414.46 | ✅ | ✅ | ✅ |
+| Chromium 109.0.5414.74 | ✅ | ✅ | ✅ |
| WebKit 16.4 | ✅ | ✅ | ✅ |
-| Firefox 107.0 | ✅ | ✅ | ✅ |
+| Firefox 108.0.2 | ✅ | ✅ | ✅ |
## Documentation
diff --git a/playwright/_impl/_page.py b/playwright/_impl/_page.py
index da524d4b8..4f7a5d03b 100644
--- a/playwright/_impl/_page.py
+++ b/playwright/_impl/_page.py
@@ -954,7 +954,10 @@ def request(self) -> "APIRequestContext":
return self.context.request
async def pause(self) -> None:
- await self._browser_context._pause()
+ await asyncio.wait(
+ [self._browser_context._pause(), self._closed_or_crashed_future],
+ return_when=asyncio.FIRST_COMPLETED,
+ )
async def pdf(
self,
diff --git a/playwright/async_api/_generated.py b/playwright/async_api/_generated.py
index 24efc0ceb..497d481d5 100644
--- a/playwright/async_api/_generated.py
+++ b/playwright/async_api/_generated.py
@@ -754,7 +754,7 @@ async def fetch(
```py
async def handle(route):
- response = await route.fulfill()
+ response = await route.fetch()
json = await response.json()
json[\"message\"][\"big_red_dog\"] = []
await route.fulfill(response=response, json=json)
@@ -764,7 +764,7 @@ async def handle(route):
```py
def handle(route):
- response = route.fulfill()
+ response = route.fetch()
json = response.json()
json[\"message\"][\"big_red_dog\"] = []
route.fulfill(response=response, json=json)
@@ -4688,10 +4688,22 @@ def get_by_alt_text(
) -> "Locator":
"""Frame.get_by_alt_text
- Allows locating elements by their alt text. For example, this method will find the image by alt text \"Castle\":
+ Allows locating elements by their alt text.
+
+ **Usage**
+
+ For example, this method will find the image by alt text \"Playwright logo\":
```html
-
+
+ ```
+
+ ```py
+ await page.get_by_alt_text(\"Playwright logo\").click()
+ ```
+
+ ```py
+ page.get_by_alt_text(\"Playwright logo\").click()
```
Parameters
@@ -4717,14 +4729,25 @@ def get_by_label(
) -> "Locator":
"""Frame.get_by_label
- Allows locating input elements by the text of the associated label. For example, this method will find the input by
- label text \"Password\" in the following DOM:
+ Allows locating input elements by the text of the associated label.
+
+ **Usage**
+
+ For example, this method will find the input by label text \"Password\" in the following DOM:
```html
```
+ ```py
+ await page.get_by_label(\"Password\").fill(\"secret\")
+ ```
+
+ ```py
+ page.get_by_label(\"Password\").fill(\"secret\")
+ ```
+
Parameters
----------
text : Union[Pattern[str], str]
@@ -4748,11 +4771,24 @@ def get_by_placeholder(
) -> "Locator":
"""Frame.get_by_placeholder
- Allows locating input elements by the placeholder text. For example, this method will find the input by placeholder
- \"Country\":
+ Allows locating input elements by the placeholder text.
+
+ **Usage**
+
+ For example, consider the following DOM structure.
```html
-
+
+ ```
+
+ You can fill the input after locating it by the placeholder text:
+
+ ```py
+ await page.get_by_placeholder(\"name@example.com\").fill(\"playwright@microsoft.com\")
+ ```
+
+ ```py
+ page.get_by_placeholder(\"name@example.com\").fill(\"playwright@microsoft.com\")
```
Parameters
@@ -4873,14 +4909,48 @@ def get_by_role(
Allows locating elements by their [ARIA role](https://www.w3.org/TR/wai-aria-1.2/#roles),
[ARIA attributes](https://www.w3.org/TR/wai-aria-1.2/#aria-attributes) and
- [accessible name](https://w3c.github.io/accname/#dfn-accessible-name). Note that role selector **does not replace**
- accessibility audits and conformance tests, but rather gives early feedback about the ARIA guidelines.
+ [accessible name](https://w3c.github.io/accname/#dfn-accessible-name).
+
+ **Usage**
+
+ Consider the following DOM structure.
+
+ ```html
+
Sign up
+
+
+
+ ```
+
+ You can locate each element by it's implicit role:
+
+ ```py
+ await expect(page.get_by_role(\"heading\", name=\"Sign up\")).to_be_visible()
+
+ await page.get_by_role(\"checkbox\", name=\"Subscribe\").check()
+
+ await page.get_by_role(\"button\", name=re.compile(\"submit\", re.IGNORECASE)).click()
+ ```
+
+ ```py
+ expect(page.get_by_role(\"heading\", name=\"Sign up\")).to_be_visible()
+
+ page.get_by_role(\"checkbox\", name=\"Subscribe\").check()
+
+ page.get_by_role(\"button\", name=re.compile(\"submit\", re.IGNORECASE)).click()
+ ```
+
+ **Details**
+
+ Role selector **does not replace** accessibility audits and conformance tests, but rather gives early feedback
+ about the ARIA guidelines.
- Note that many html elements have an implicitly
- [defined role](https://w3c.github.io/html-aam/#html-element-role-mappings) that is recognized by the role selector.
- You can find all the [supported roles here](https://www.w3.org/TR/wai-aria-1.2/#role_definitions). ARIA guidelines
- **do not recommend** duplicating implicit roles and attributes by setting `role` and/or `aria-*` attributes to
- default values.
+ Many html elements have an implicitly [defined role](https://w3c.github.io/html-aam/#html-element-role-mappings)
+ that is recognized by the role selector. You can find all the
+ [supported roles here](https://www.w3.org/TR/wai-aria-1.2/#role_definitions). ARIA guidelines **do not recommend**
+ duplicating implicit roles and attributes by setting `role` and/or `aria-*` attributes to default values.
Parameters
----------
@@ -4951,8 +5021,30 @@ def get_by_test_id(
) -> "Locator":
"""Frame.get_by_test_id
- Locate element by the test id. By default, the `data-testid` attribute is used as a test id. Use
- `selectors.set_test_id_attribute()` to configure a different test id attribute if necessary.
+ Locate element by the test id.
+
+ **Usage**
+
+ Consider the following DOM structure.
+
+ ```html
+
+ ```
+
+ You can locate the element by it's test id:
+
+ ```py
+ await page.get_by_test_id(\"directions\").click()
+ ```
+
+ ```py
+ page.get_by_test_id(\"directions\").click()
+ ```
+
+ **Details**
+
+ By default, the `data-testid` attribute is used as a test id. Use `selectors.set_test_id_attribute()` to
+ configure a different test id attribute if necessary.
Parameters
----------
@@ -4974,7 +5066,14 @@ def get_by_text(
) -> "Locator":
"""Frame.get_by_text
- Allows locating elements that contain given text. Consider the following DOM structure:
+ Allows locating elements that contain given text.
+
+ See also `locator.filter()` that allows to match by another criteria, like an accessible role, and then
+ filter by the text content.
+
+ **Usage**
+
+ Consider the following DOM structure:
```html
Hello world
@@ -5017,14 +5116,13 @@ def get_by_text(
page.get_by_text(re.compile(\"^hello$\", re.IGNORECASE))
```
- See also `locator.filter()` that allows to match by another criteria, like an accessible role, and then
- filter by the text content.
+ **Details**
- **NOTE** Matching by text always normalizes whitespace, even with exact match. For example, it turns multiple
- spaces into one, turns line breaks into spaces and ignores leading and trailing whitespace.
+ Matching by text always normalizes whitespace, even with exact match. For example, it turns multiple spaces into
+ one, turns line breaks into spaces and ignores leading and trailing whitespace.
- **NOTE** Input elements of the type `button` and `submit` are matched by their `value` instead of the text content.
- For example, locating by text `\"Log in\"` matches ``.
+ Input elements of the type `button` and `submit` are matched by their `value` instead of the text content. For
+ example, locating by text `\"Log in\"` matches ``.
Parameters
----------
@@ -5049,11 +5147,24 @@ def get_by_title(
) -> "Locator":
"""Frame.get_by_title
- Allows locating elements by their title. For example, this method will find the button by its title \"Place the
- order\":
+ Allows locating elements by their title attribute.
+
+ **Usage**
+
+ Consider the following DOM structure.
```html
-
+ 25 issues
+ ```
+
+ You can check the issues count after locating it by the title text:
+
+ ```py
+ await expect(page.get_by_title(\"Issues count\")).to_have_text(\"25 issues\")
+ ```
+
+ ```py
+ expect(page.get_by_title(\"Issues count\")).to_have_text(\"25 issues\")
```
Parameters
@@ -6104,10 +6215,22 @@ def get_by_alt_text(
) -> "Locator":
"""FrameLocator.get_by_alt_text
- Allows locating elements by their alt text. For example, this method will find the image by alt text \"Castle\":
+ Allows locating elements by their alt text.
+
+ **Usage**
+
+ For example, this method will find the image by alt text \"Playwright logo\":
```html
-
+
+ ```
+
+ ```py
+ await page.get_by_alt_text(\"Playwright logo\").click()
+ ```
+
+ ```py
+ page.get_by_alt_text(\"Playwright logo\").click()
```
Parameters
@@ -6133,14 +6256,25 @@ def get_by_label(
) -> "Locator":
"""FrameLocator.get_by_label
- Allows locating input elements by the text of the associated label. For example, this method will find the input by
- label text \"Password\" in the following DOM:
+ Allows locating input elements by the text of the associated label.
+
+ **Usage**
+
+ For example, this method will find the input by label text \"Password\" in the following DOM:
```html
```
+ ```py
+ await page.get_by_label(\"Password\").fill(\"secret\")
+ ```
+
+ ```py
+ page.get_by_label(\"Password\").fill(\"secret\")
+ ```
+
Parameters
----------
text : Union[Pattern[str], str]
@@ -6164,11 +6298,24 @@ def get_by_placeholder(
) -> "Locator":
"""FrameLocator.get_by_placeholder
- Allows locating input elements by the placeholder text. For example, this method will find the input by placeholder
- \"Country\":
+ Allows locating input elements by the placeholder text.
+
+ **Usage**
+
+ For example, consider the following DOM structure.
```html
-
+
+ ```
+
+ You can fill the input after locating it by the placeholder text:
+
+ ```py
+ await page.get_by_placeholder(\"name@example.com\").fill(\"playwright@microsoft.com\")
+ ```
+
+ ```py
+ page.get_by_placeholder(\"name@example.com\").fill(\"playwright@microsoft.com\")
```
Parameters
@@ -6289,14 +6436,48 @@ def get_by_role(
Allows locating elements by their [ARIA role](https://www.w3.org/TR/wai-aria-1.2/#roles),
[ARIA attributes](https://www.w3.org/TR/wai-aria-1.2/#aria-attributes) and
- [accessible name](https://w3c.github.io/accname/#dfn-accessible-name). Note that role selector **does not replace**
- accessibility audits and conformance tests, but rather gives early feedback about the ARIA guidelines.
+ [accessible name](https://w3c.github.io/accname/#dfn-accessible-name).
+
+ **Usage**
+
+ Consider the following DOM structure.
+
+ ```html
+
Sign up
+
+
+
+ ```
+
+ You can locate each element by it's implicit role:
+
+ ```py
+ await expect(page.get_by_role(\"heading\", name=\"Sign up\")).to_be_visible()
+
+ await page.get_by_role(\"checkbox\", name=\"Subscribe\").check()
+
+ await page.get_by_role(\"button\", name=re.compile(\"submit\", re.IGNORECASE)).click()
+ ```
+
+ ```py
+ expect(page.get_by_role(\"heading\", name=\"Sign up\")).to_be_visible()
+
+ page.get_by_role(\"checkbox\", name=\"Subscribe\").check()
+
+ page.get_by_role(\"button\", name=re.compile(\"submit\", re.IGNORECASE)).click()
+ ```
- Note that many html elements have an implicitly
- [defined role](https://w3c.github.io/html-aam/#html-element-role-mappings) that is recognized by the role selector.
- You can find all the [supported roles here](https://www.w3.org/TR/wai-aria-1.2/#role_definitions). ARIA guidelines
- **do not recommend** duplicating implicit roles and attributes by setting `role` and/or `aria-*` attributes to
- default values.
+ **Details**
+
+ Role selector **does not replace** accessibility audits and conformance tests, but rather gives early feedback
+ about the ARIA guidelines.
+
+ Many html elements have an implicitly [defined role](https://w3c.github.io/html-aam/#html-element-role-mappings)
+ that is recognized by the role selector. You can find all the
+ [supported roles here](https://www.w3.org/TR/wai-aria-1.2/#role_definitions). ARIA guidelines **do not recommend**
+ duplicating implicit roles and attributes by setting `role` and/or `aria-*` attributes to default values.
Parameters
----------
@@ -6367,8 +6548,30 @@ def get_by_test_id(
) -> "Locator":
"""FrameLocator.get_by_test_id
- Locate element by the test id. By default, the `data-testid` attribute is used as a test id. Use
- `selectors.set_test_id_attribute()` to configure a different test id attribute if necessary.
+ Locate element by the test id.
+
+ **Usage**
+
+ Consider the following DOM structure.
+
+ ```html
+
+ ```
+
+ You can locate the element by it's test id:
+
+ ```py
+ await page.get_by_test_id(\"directions\").click()
+ ```
+
+ ```py
+ page.get_by_test_id(\"directions\").click()
+ ```
+
+ **Details**
+
+ By default, the `data-testid` attribute is used as a test id. Use `selectors.set_test_id_attribute()` to
+ configure a different test id attribute if necessary.
Parameters
----------
@@ -6390,7 +6593,14 @@ def get_by_text(
) -> "Locator":
"""FrameLocator.get_by_text
- Allows locating elements that contain given text. Consider the following DOM structure:
+ Allows locating elements that contain given text.
+
+ See also `locator.filter()` that allows to match by another criteria, like an accessible role, and then
+ filter by the text content.
+
+ **Usage**
+
+ Consider the following DOM structure:
```html
Hello world
@@ -6433,14 +6643,13 @@ def get_by_text(
page.get_by_text(re.compile(\"^hello$\", re.IGNORECASE))
```
- See also `locator.filter()` that allows to match by another criteria, like an accessible role, and then
- filter by the text content.
+ **Details**
- **NOTE** Matching by text always normalizes whitespace, even with exact match. For example, it turns multiple
- spaces into one, turns line breaks into spaces and ignores leading and trailing whitespace.
+ Matching by text always normalizes whitespace, even with exact match. For example, it turns multiple spaces into
+ one, turns line breaks into spaces and ignores leading and trailing whitespace.
- **NOTE** Input elements of the type `button` and `submit` are matched by their `value` instead of the text content.
- For example, locating by text `\"Log in\"` matches ``.
+ Input elements of the type `button` and `submit` are matched by their `value` instead of the text content. For
+ example, locating by text `\"Log in\"` matches ``.
Parameters
----------
@@ -6465,11 +6674,24 @@ def get_by_title(
) -> "Locator":
"""FrameLocator.get_by_title
- Allows locating elements by their title. For example, this method will find the button by its title \"Place the
- order\":
+ Allows locating elements by their title attribute.
+
+ **Usage**
+
+ Consider the following DOM structure.
```html
-
+ 25 issues
+ ```
+
+ You can check the issues count after locating it by the title text:
+
+ ```py
+ await expect(page.get_by_title(\"Issues count\")).to_have_text(\"25 issues\")
+ ```
+
+ ```py
+ expect(page.get_by_title(\"Issues count\")).to_have_text(\"25 issues\")
```
Parameters
@@ -10008,10 +10230,22 @@ def get_by_alt_text(
) -> "Locator":
"""Page.get_by_alt_text
- Allows locating elements by their alt text. For example, this method will find the image by alt text \"Castle\":
+ Allows locating elements by their alt text.
+
+ **Usage**
+
+ For example, this method will find the image by alt text \"Playwright logo\":
```html
-
+
+ ```
+
+ ```py
+ await page.get_by_alt_text(\"Playwright logo\").click()
+ ```
+
+ ```py
+ page.get_by_alt_text(\"Playwright logo\").click()
```
Parameters
@@ -10037,14 +10271,25 @@ def get_by_label(
) -> "Locator":
"""Page.get_by_label
- Allows locating input elements by the text of the associated label. For example, this method will find the input by
- label text \"Password\" in the following DOM:
+ Allows locating input elements by the text of the associated label.
+
+ **Usage**
+
+ For example, this method will find the input by label text \"Password\" in the following DOM:
```html
```
+ ```py
+ await page.get_by_label(\"Password\").fill(\"secret\")
+ ```
+
+ ```py
+ page.get_by_label(\"Password\").fill(\"secret\")
+ ```
+
Parameters
----------
text : Union[Pattern[str], str]
@@ -10068,11 +10313,24 @@ def get_by_placeholder(
) -> "Locator":
"""Page.get_by_placeholder
- Allows locating input elements by the placeholder text. For example, this method will find the input by placeholder
- \"Country\":
+ Allows locating input elements by the placeholder text.
+
+ **Usage**
+
+ For example, consider the following DOM structure.
```html
-
+
+ ```
+
+ You can fill the input after locating it by the placeholder text:
+
+ ```py
+ await page.get_by_placeholder(\"name@example.com\").fill(\"playwright@microsoft.com\")
+ ```
+
+ ```py
+ page.get_by_placeholder(\"name@example.com\").fill(\"playwright@microsoft.com\")
```
Parameters
@@ -10193,14 +10451,48 @@ def get_by_role(
Allows locating elements by their [ARIA role](https://www.w3.org/TR/wai-aria-1.2/#roles),
[ARIA attributes](https://www.w3.org/TR/wai-aria-1.2/#aria-attributes) and
- [accessible name](https://w3c.github.io/accname/#dfn-accessible-name). Note that role selector **does not replace**
- accessibility audits and conformance tests, but rather gives early feedback about the ARIA guidelines.
+ [accessible name](https://w3c.github.io/accname/#dfn-accessible-name).
+
+ **Usage**
+
+ Consider the following DOM structure.
+
+ ```html
+
Sign up
+
+
+
+ ```
+
+ You can locate each element by it's implicit role:
+
+ ```py
+ await expect(page.get_by_role(\"heading\", name=\"Sign up\")).to_be_visible()
+
+ await page.get_by_role(\"checkbox\", name=\"Subscribe\").check()
+
+ await page.get_by_role(\"button\", name=re.compile(\"submit\", re.IGNORECASE)).click()
+ ```
+
+ ```py
+ expect(page.get_by_role(\"heading\", name=\"Sign up\")).to_be_visible()
- Note that many html elements have an implicitly
- [defined role](https://w3c.github.io/html-aam/#html-element-role-mappings) that is recognized by the role selector.
- You can find all the [supported roles here](https://www.w3.org/TR/wai-aria-1.2/#role_definitions). ARIA guidelines
- **do not recommend** duplicating implicit roles and attributes by setting `role` and/or `aria-*` attributes to
- default values.
+ page.get_by_role(\"checkbox\", name=\"Subscribe\").check()
+
+ page.get_by_role(\"button\", name=re.compile(\"submit\", re.IGNORECASE)).click()
+ ```
+
+ **Details**
+
+ Role selector **does not replace** accessibility audits and conformance tests, but rather gives early feedback
+ about the ARIA guidelines.
+
+ Many html elements have an implicitly [defined role](https://w3c.github.io/html-aam/#html-element-role-mappings)
+ that is recognized by the role selector. You can find all the
+ [supported roles here](https://www.w3.org/TR/wai-aria-1.2/#role_definitions). ARIA guidelines **do not recommend**
+ duplicating implicit roles and attributes by setting `role` and/or `aria-*` attributes to default values.
Parameters
----------
@@ -10271,8 +10563,30 @@ def get_by_test_id(
) -> "Locator":
"""Page.get_by_test_id
- Locate element by the test id. By default, the `data-testid` attribute is used as a test id. Use
- `selectors.set_test_id_attribute()` to configure a different test id attribute if necessary.
+ Locate element by the test id.
+
+ **Usage**
+
+ Consider the following DOM structure.
+
+ ```html
+
+ ```
+
+ You can locate the element by it's test id:
+
+ ```py
+ await page.get_by_test_id(\"directions\").click()
+ ```
+
+ ```py
+ page.get_by_test_id(\"directions\").click()
+ ```
+
+ **Details**
+
+ By default, the `data-testid` attribute is used as a test id. Use `selectors.set_test_id_attribute()` to
+ configure a different test id attribute if necessary.
Parameters
----------
@@ -10294,7 +10608,14 @@ def get_by_text(
) -> "Locator":
"""Page.get_by_text
- Allows locating elements that contain given text. Consider the following DOM structure:
+ Allows locating elements that contain given text.
+
+ See also `locator.filter()` that allows to match by another criteria, like an accessible role, and then
+ filter by the text content.
+
+ **Usage**
+
+ Consider the following DOM structure:
```html
Hello world
@@ -10337,14 +10658,13 @@ def get_by_text(
page.get_by_text(re.compile(\"^hello$\", re.IGNORECASE))
```
- See also `locator.filter()` that allows to match by another criteria, like an accessible role, and then
- filter by the text content.
+ **Details**
- **NOTE** Matching by text always normalizes whitespace, even with exact match. For example, it turns multiple
- spaces into one, turns line breaks into spaces and ignores leading and trailing whitespace.
+ Matching by text always normalizes whitespace, even with exact match. For example, it turns multiple spaces into
+ one, turns line breaks into spaces and ignores leading and trailing whitespace.
- **NOTE** Input elements of the type `button` and `submit` are matched by their `value` instead of the text content.
- For example, locating by text `\"Log in\"` matches ``.
+ Input elements of the type `button` and `submit` are matched by their `value` instead of the text content. For
+ example, locating by text `\"Log in\"` matches ``.
Parameters
----------
@@ -10369,11 +10689,24 @@ def get_by_title(
) -> "Locator":
"""Page.get_by_title
- Allows locating elements by their title. For example, this method will find the button by its title \"Place the
- order\":
+ Allows locating elements by their title attribute.
+
+ **Usage**
+
+ Consider the following DOM structure.
```html
-
+ 25 issues
+ ```
+
+ You can check the issues count after locating it by the title text:
+
+ ```py
+ await expect(page.get_by_title(\"Issues count\")).to_have_text(\"25 issues\")
+ ```
+
+ ```py
+ expect(page.get_by_title(\"Issues count\")).to_have_text(\"25 issues\")
```
Parameters
@@ -14715,19 +15048,32 @@ def last(self) -> "Locator":
Returns locator to the last matching element.
- Returns
- -------
- Locator
- """
- return mapping.from_impl(self._impl_obj.last)
+ **Usage**
- async def bounding_box(
+ ```py
+ banana = await page.get_by_role(\"listitem\").last()
+ ```
+
+ ```py
+ banana = page.get_by_role(\"listitem\").last()
+ ```
+
+ Returns
+ -------
+ Locator
+ """
+ return mapping.from_impl(self._impl_obj.last)
+
+ async def bounding_box(
self, *, timeout: typing.Optional[float] = None
) -> typing.Optional[FloatRect]:
"""Locator.bounding_box
- This method returns the bounding box of the element, or `null` if the element is not visible. The bounding box is
- calculated relative to the main frame viewport - which is usually the same as the browser window.
+ This method returns the bounding box of the element matching the locator, or `null` if the element is not visible.
+ The bounding box is calculated relative to the main frame viewport - which is usually the same as the browser
+ window.
+
+ **Details**
Scrolling affects the returned bounding box, similarly to
[Element.getBoundingClientRect](https://developer.mozilla.org/en-US/docs/Web/API/Element/getBoundingClientRect).
@@ -14742,12 +15088,12 @@ async def bounding_box(
**Usage**
```py
- box = await element.bounding_box()
+ box = await page.get_by_role(\"button\").bounding_box()
await page.mouse.click(box[\"x\"] + box[\"width\"] / 2, box[\"y\"] + box[\"height\"] / 2)
```
```py
- box = element.bounding_box()
+ box = page.get_by_role(\"button\").bounding_box()
page.mouse.click(box[\"x\"] + box[\"width\"] / 2, box[\"y\"] + box[\"height\"] / 2)
```
@@ -14777,7 +15123,11 @@ async def check(
) -> None:
"""Locator.check
- This method checks the element by performing the following steps:
+ Ensure that checkbox or radio element is checked.
+
+ **Details**
+
+ Performs the following steps:
1. Ensure that element is a checkbox or a radio input. If not, this method throws. If the element is already
checked, this method returns immediately.
1. Wait for [actionability](https://playwright.dev/python/docs/actionability) checks on the element, unless `force` option is set.
@@ -14791,6 +15141,16 @@ async def check(
When all steps combined have not finished during the specified `timeout`, this method throws a `TimeoutError`.
Passing zero timeout disables this.
+ **Usage**
+
+ ```py
+ await page.get_by_role(\"checkbox\").check()
+ ```
+
+ ```py
+ page.get_by_role(\"checkbox\").check()
+ ```
+
Parameters
----------
position : Union[{x: float, y: float}, None]
@@ -14852,6 +15212,32 @@ async def click(
When all steps combined have not finished during the specified `timeout`, this method throws a `TimeoutError`.
Passing zero timeout disables this.
+ **Usage**
+
+ Click a button:
+
+ ```py
+ await page.get_by_role(\"button\").click()
+ ```
+
+ ```py
+ page.get_by_role(\"button\").click()
+ ```
+
+ Shift-right-click at a specific position on a canvas:
+
+ ```py
+ await page.locator(\"canvas\").click(
+ button=\"right\", modifiers=[\"Shift\"], position={\"x\": 23, \"y\": 32}
+ )
+ ```
+
+ ```py
+ page.locator(\"canvas\").click(
+ button=\"right\", modifiers=[\"Shift\"], position={\"x\": 23, \"y\": 32}
+ )
+ ```
+
Parameters
----------
modifiers : Union[List[Union["Alt", "Control", "Meta", "Shift"]], None]
@@ -14910,6 +15296,10 @@ async def dblclick(
) -> None:
"""Locator.dblclick
+ Double-click an element.
+
+ **Details**
+
This method double clicks the element by performing the following steps:
1. Wait for [actionability](https://playwright.dev/python/docs/actionability) checks on the element, unless `force` option is set.
1. Scroll the element into view if needed.
@@ -14972,20 +15362,24 @@ async def dispatch_event(
) -> None:
"""Locator.dispatch_event
- The snippet below dispatches the `click` event on the element. Regardless of the visibility state of the element,
- `click` is dispatched. This is equivalent to calling
- [element.click()](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/click).
+ Programmaticaly dispatch an event on the matching element.
**Usage**
```py
- await element.dispatch_event(\"click\")
+ await locator.dispatch_event(\"click\")
```
```py
- element.dispatch_event(\"click\")
+ locator.dispatch_event(\"click\")
```
+ **Details**
+
+ The snippet above dispatches the `click` event on the element. Regardless of the visibility state of the element,
+ `click` is dispatched. This is equivalent to calling
+ [element.click()](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/click).
+
Under the hood, it creates an instance of an event based on the given `type`, initializes it with `eventInit`
properties and dispatches it on the element. Events are `composed`, `cancelable` and bubble by default.
@@ -15003,13 +15397,13 @@ async def dispatch_event(
```py
# note you can only create data_transfer in chromium and firefox
data_transfer = await page.evaluate_handle(\"new DataTransfer()\")
- await element.dispatch_event(\"#source\", \"dragstart\", {\"dataTransfer\": data_transfer})
+ await locator.dispatch_event(\"#source\", \"dragstart\", {\"dataTransfer\": data_transfer})
```
```py
# note you can only create data_transfer in chromium and firefox
data_transfer = page.evaluate_handle(\"new DataTransfer()\")
- element.dispatch_event(\"#source\", \"dragstart\", {\"dataTransfer\": data_transfer})
+ locator.dispatch_event(\"#source\", \"dragstart\", {\"dataTransfer\": data_transfer})
```
Parameters
@@ -15038,12 +15432,16 @@ async def evaluate(
) -> typing.Any:
"""Locator.evaluate
- Returns the return value of `expression`.
+ Execute JavaScript code in the page, taking the matching element as an argument.
- This method passes this handle as the first argument to `expression`.
+ **Details**
- If `expression` returns a [Promise], then `handle.evaluate` would wait for the promise to resolve and return its
- value.
+ Returns the return value of `expression`, called with the matching element as a first argument, and `arg` as a
+ second argument.
+
+ If `expression` returns a [Promise], this method will wait for the promise to resolve and return its value.
+
+ If `expression` throws or rejects, this method throws.
**Usage**
@@ -15084,22 +15482,27 @@ async def evaluate_all(
) -> typing.Any:
"""Locator.evaluate_all
- The method finds all elements matching the specified locator and passes an array of matched elements as a first
- argument to `expression`. Returns the result of `expression` invocation.
+ Execute JavaScript code in the page, taking all matching elements as an argument.
- If `expression` returns a [Promise], then `locator.evaluate_all()` would wait for the promise to resolve and
- return its value.
+ **Details**
+
+ Returns the return value of `expression`, called with an array of all matching elements as a first argument, and
+ `arg` as a second argument.
+
+ If `expression` returns a [Promise], this method will wait for the promise to resolve and return its value.
+
+ If `expression` throws or rejects, this method throws.
**Usage**
```py
- elements = page.locator(\"div\")
- div_counts = await elements.evaluate_all(\"(divs, min) => divs.length >= min\", 10)
+ locator = page.locator(\"div\")
+ more_than_ten = await locator.evaluate_all(\"(divs, min) => divs.length > min\", 10)
```
```py
- elements = page.locator(\"div\")
- div_counts = elements.evaluate_all(\"(divs, min) => divs.length >= min\", 10)
+ locator = page.locator(\"div\")
+ more_than_ten = locator.evaluate_all(\"(divs, min) => divs.length > min\", 10)
```
Parameters
@@ -15130,15 +15533,20 @@ async def evaluate_handle(
) -> "JSHandle":
"""Locator.evaluate_handle
- Returns the return value of `expression` as a `JSHandle`.
+ Execute JavaScript code in the page, taking the matching element as an argument, and return a `JSHandle` with the
+ result.
- This method passes this handle as the first argument to `expression`.
+ **Details**
+
+ Returns the return value of `expression` as a`JSHandle`, called with the matching element as a first argument, and
+ `arg` as a second argument.
The only difference between `locator.evaluate()` and `locator.evaluate_handle()` is that
`locator.evaluate_handle()` returns `JSHandle`.
- If the function passed to the `locator.evaluate_handle()` returns a [Promise], then
- `locator.evaluate_handle()` would wait for the promise to resolve and return its value.
+ If `expression` returns a [Promise], this method will wait for the promise to resolve and return its value.
+
+ If `expression` throws or rejects, this method throws.
See `page.evaluate_handle()` for more details.
@@ -15174,6 +15582,20 @@ async def fill(
) -> None:
"""Locator.fill
+ Set a value to the input field.
+
+ **Usage**
+
+ ```py
+ await page.get_by_role(\"textbox\").fill(\"example value\")
+ ```
+
+ ```py
+ page.get_by_role(\"textbox\").fill(\"example value\")
+ ```
+
+ **Details**
+
This method waits for [actionability](https://playwright.dev/python/docs/actionability) checks, focuses the element, fills it and triggers an
`input` event after filling. Note that you can pass an empty string to clear the input field.
@@ -15214,6 +15636,10 @@ async def clear(
) -> None:
"""Locator.clear
+ Clear the input field.
+
+ **Details**
+
This method waits for [actionability](https://playwright.dev/python/docs/actionability) checks, focuses the element, clears it and triggers an
`input` event after clearing.
@@ -15222,6 +15648,16 @@ async def clear(
[control](https://developer.mozilla.org/en-US/docs/Web/API/HTMLLabelElement/control), the control will be cleared
instead.
+ **Usage**
+
+ ```py
+ await page.get_by_role(\"textbox\").clear()
+ ```
+
+ ```py
+ page.get_by_role(\"textbox\").clear()
+ ```
+
Parameters
----------
timeout : Union[float, None]
@@ -15288,10 +15724,22 @@ def get_by_alt_text(
) -> "Locator":
"""Locator.get_by_alt_text
- Allows locating elements by their alt text. For example, this method will find the image by alt text \"Castle\":
+ Allows locating elements by their alt text.
+
+ **Usage**
+
+ For example, this method will find the image by alt text \"Playwright logo\":
```html
-
+
+ ```
+
+ ```py
+ await page.get_by_alt_text(\"Playwright logo\").click()
+ ```
+
+ ```py
+ page.get_by_alt_text(\"Playwright logo\").click()
```
Parameters
@@ -15317,14 +15765,25 @@ def get_by_label(
) -> "Locator":
"""Locator.get_by_label
- Allows locating input elements by the text of the associated label. For example, this method will find the input by
- label text \"Password\" in the following DOM:
+ Allows locating input elements by the text of the associated label.
+
+ **Usage**
+
+ For example, this method will find the input by label text \"Password\" in the following DOM:
```html
```
+ ```py
+ await page.get_by_label(\"Password\").fill(\"secret\")
+ ```
+
+ ```py
+ page.get_by_label(\"Password\").fill(\"secret\")
+ ```
+
Parameters
----------
text : Union[Pattern[str], str]
@@ -15348,11 +15807,24 @@ def get_by_placeholder(
) -> "Locator":
"""Locator.get_by_placeholder
- Allows locating input elements by the placeholder text. For example, this method will find the input by placeholder
- \"Country\":
+ Allows locating input elements by the placeholder text.
+
+ **Usage**
+
+ For example, consider the following DOM structure.
```html
-
+
+ ```
+
+ You can fill the input after locating it by the placeholder text:
+
+ ```py
+ await page.get_by_placeholder(\"name@example.com\").fill(\"playwright@microsoft.com\")
+ ```
+
+ ```py
+ page.get_by_placeholder(\"name@example.com\").fill(\"playwright@microsoft.com\")
```
Parameters
@@ -15473,14 +15945,48 @@ def get_by_role(
Allows locating elements by their [ARIA role](https://www.w3.org/TR/wai-aria-1.2/#roles),
[ARIA attributes](https://www.w3.org/TR/wai-aria-1.2/#aria-attributes) and
- [accessible name](https://w3c.github.io/accname/#dfn-accessible-name). Note that role selector **does not replace**
- accessibility audits and conformance tests, but rather gives early feedback about the ARIA guidelines.
+ [accessible name](https://w3c.github.io/accname/#dfn-accessible-name).
+
+ **Usage**
+
+ Consider the following DOM structure.
+
+ ```html
+
Sign up
+
+
+
+ ```
+
+ You can locate each element by it's implicit role:
+
+ ```py
+ await expect(page.get_by_role(\"heading\", name=\"Sign up\")).to_be_visible()
+
+ await page.get_by_role(\"checkbox\", name=\"Subscribe\").check()
+
+ await page.get_by_role(\"button\", name=re.compile(\"submit\", re.IGNORECASE)).click()
+ ```
+
+ ```py
+ expect(page.get_by_role(\"heading\", name=\"Sign up\")).to_be_visible()
+
+ page.get_by_role(\"checkbox\", name=\"Subscribe\").check()
+
+ page.get_by_role(\"button\", name=re.compile(\"submit\", re.IGNORECASE)).click()
+ ```
+
+ **Details**
- Note that many html elements have an implicitly
- [defined role](https://w3c.github.io/html-aam/#html-element-role-mappings) that is recognized by the role selector.
- You can find all the [supported roles here](https://www.w3.org/TR/wai-aria-1.2/#role_definitions). ARIA guidelines
- **do not recommend** duplicating implicit roles and attributes by setting `role` and/or `aria-*` attributes to
- default values.
+ Role selector **does not replace** accessibility audits and conformance tests, but rather gives early feedback
+ about the ARIA guidelines.
+
+ Many html elements have an implicitly [defined role](https://w3c.github.io/html-aam/#html-element-role-mappings)
+ that is recognized by the role selector. You can find all the
+ [supported roles here](https://www.w3.org/TR/wai-aria-1.2/#role_definitions). ARIA guidelines **do not recommend**
+ duplicating implicit roles and attributes by setting `role` and/or `aria-*` attributes to default values.
Parameters
----------
@@ -15551,8 +16057,30 @@ def get_by_test_id(
) -> "Locator":
"""Locator.get_by_test_id
- Locate element by the test id. By default, the `data-testid` attribute is used as a test id. Use
- `selectors.set_test_id_attribute()` to configure a different test id attribute if necessary.
+ Locate element by the test id.
+
+ **Usage**
+
+ Consider the following DOM structure.
+
+ ```html
+
+ ```
+
+ You can locate the element by it's test id:
+
+ ```py
+ await page.get_by_test_id(\"directions\").click()
+ ```
+
+ ```py
+ page.get_by_test_id(\"directions\").click()
+ ```
+
+ **Details**
+
+ By default, the `data-testid` attribute is used as a test id. Use `selectors.set_test_id_attribute()` to
+ configure a different test id attribute if necessary.
Parameters
----------
@@ -15574,7 +16102,14 @@ def get_by_text(
) -> "Locator":
"""Locator.get_by_text
- Allows locating elements that contain given text. Consider the following DOM structure:
+ Allows locating elements that contain given text.
+
+ See also `locator.filter()` that allows to match by another criteria, like an accessible role, and then
+ filter by the text content.
+
+ **Usage**
+
+ Consider the following DOM structure:
```html
Hello world
@@ -15617,14 +16152,13 @@ def get_by_text(
page.get_by_text(re.compile(\"^hello$\", re.IGNORECASE))
```
- See also `locator.filter()` that allows to match by another criteria, like an accessible role, and then
- filter by the text content.
+ **Details**
- **NOTE** Matching by text always normalizes whitespace, even with exact match. For example, it turns multiple
- spaces into one, turns line breaks into spaces and ignores leading and trailing whitespace.
+ Matching by text always normalizes whitespace, even with exact match. For example, it turns multiple spaces into
+ one, turns line breaks into spaces and ignores leading and trailing whitespace.
- **NOTE** Input elements of the type `button` and `submit` are matched by their `value` instead of the text content.
- For example, locating by text `\"Log in\"` matches ``.
+ Input elements of the type `button` and `submit` are matched by their `value` instead of the text content. For
+ example, locating by text `\"Log in\"` matches ``.
Parameters
----------
@@ -15649,11 +16183,24 @@ def get_by_title(
) -> "Locator":
"""Locator.get_by_title
- Allows locating elements by their title. For example, this method will find the button by its title \"Place the
- order\":
+ Allows locating elements by their title attribute.
+
+ **Usage**
+
+ Consider the following DOM structure.
```html
-
+ 25 issues
+ ```
+
+ You can check the issues count after locating it by the title text:
+
+ ```py
+ await expect(page.get_by_title(\"Issues count\")).to_have_text(\"25 issues\")
+ ```
+
+ ```py
+ expect(page.get_by_title(\"Issues count\")).to_have_text(\"25 issues\")
```
Parameters
@@ -15674,10 +16221,10 @@ def get_by_title(
def frame_locator(self, selector: str) -> "FrameLocator":
"""Locator.frame_locator
- **Usage**
+ When working with iframes, you can create a frame locator that will enter the iframe and allow locating elements in
+ that iframe:
- When working with iframes, you can create a frame locator that will enter the iframe and allow selecting elements
- in that iframe:
+ **Usage**
```py
locator = page.frame_locator(\"iframe\").get_by_text(\"Submit\")
@@ -15706,8 +16253,8 @@ async def element_handle(
) -> "ElementHandle":
"""Locator.element_handle
- Resolves given locator to the first matching DOM element. If no elements matching the query are visible, waits for
- them up to a given timeout. If multiple elements match the selector, throws.
+ Resolves given locator to the first matching DOM element. If there are no matching elements, waits for one. If
+ multiple elements match the locator, throws.
Parameters
----------
@@ -15725,7 +16272,7 @@ async def element_handle(
async def element_handles(self) -> typing.List["ElementHandle"]:
"""Locator.element_handles
- Resolves given locator to all matching DOM elements.
+ Resolves given locator to all matching DOM elements. If there are no matching elements, returns an empty list.
Returns
-------
@@ -15739,6 +16286,16 @@ def nth(self, index: int) -> "Locator":
Returns locator to the n-th matching element. It's zero based, `nth(0)` selects the first element.
+ **Usage**
+
+ ```py
+ banana = await page.get_by_role(\"listitem\").nth(2)
+ ```
+
+ ```py
+ banana = page.get_by_role(\"listitem\").nth(2)
+ ```
+
Parameters
----------
index : int
@@ -15805,7 +16362,7 @@ def filter(
async def focus(self, *, timeout: typing.Optional[float] = None) -> None:
"""Locator.focus
- Calls [focus](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/focus) on the element.
+ Calls [focus](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/focus) on the matching element.
Parameters
----------
@@ -15857,7 +16414,17 @@ async def all(self) -> typing.List["Locator"]:
async def count(self) -> int:
"""Locator.count
- Returns the number of elements matching given selector.
+ Returns the number of elements matching the locator.
+
+ **Usage**
+
+ ```py
+ count = await page.get_by_role(\"listitem\").count()
+ ```
+
+ ```py
+ count = page.get_by_role(\"listitem\").count()
+ ```
Returns
-------
@@ -15879,6 +16446,10 @@ async def drag_to(
) -> None:
"""Locator.drag_to
+ Drag the source element towards the target element and drop it.
+
+ **Details**
+
This method drags the locator to another target locator or target position. It will first move to the source
element, perform a `mousedown`, then move to the target element or position and perform a `mouseup`.
@@ -15951,7 +16522,7 @@ async def get_attribute(
) -> typing.Optional[str]:
"""Locator.get_attribute
- Returns element attribute value.
+ Returns the matching element's attribute value.
Parameters
----------
@@ -15984,6 +16555,20 @@ async def hover(
) -> None:
"""Locator.hover
+ Hover over the matching element.
+
+ **Usage**
+
+ ```py
+ await page.get_by_role(\"link\").hover()
+ ```
+
+ ```py
+ page.get_by_role(\"link\").hover()
+ ```
+
+ **Details**
+
This method hovers over the element by performing the following steps:
1. Wait for [actionability](https://playwright.dev/python/docs/actionability) checks on the element, unless `force` option is set.
1. Scroll the element into view if needed.
@@ -16031,7 +16616,7 @@ async def hover(
async def inner_html(self, *, timeout: typing.Optional[float] = None) -> str:
"""Locator.inner_html
- Returns the `element.innerHTML`.
+ Returns the [`element.innerHTML`](https://developer.mozilla.org/en-US/docs/Web/API/Element/innerHTML).
Parameters
----------
@@ -16049,7 +16634,7 @@ async def inner_html(self, *, timeout: typing.Optional[float] = None) -> str:
async def inner_text(self, *, timeout: typing.Optional[float] = None) -> str:
"""Locator.inner_text
- Returns the `element.innerText`.
+ Returns the [`element.innerText`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/innerText).
Parameters
----------
@@ -16067,9 +16652,22 @@ async def inner_text(self, *, timeout: typing.Optional[float] = None) -> str:
async def input_value(self, *, timeout: typing.Optional[float] = None) -> str:
"""Locator.input_value
- Returns `input.value` for the selected `` or `