From d08dfdf53262b7cd5bde7e169c317374d9c0eb1c Mon Sep 17 00:00:00 2001
From: Max Schmitt <max@schmitt.mx>
Date: Tue, 30 Nov 2021 20:04:44 +0100
Subject: [PATCH] docs(python): add assertion examples (#10532)

---
 docs/src/api/class-locatorassertions.md    | 326 ++++++++++++++++++++-
 docs/src/api/class-pageassertions.md       |  66 +++++
 docs/src/api/class-playwrightassertions.md |  14 +-
 3 files changed, 399 insertions(+), 7 deletions(-)

diff --git a/docs/src/api/class-locatorassertions.md b/docs/src/api/class-locatorassertions.md
index 4b4e0509a1..b89f9c127f 100644
--- a/docs/src/api/class-locatorassertions.md
+++ b/docs/src/api/class-locatorassertions.md
@@ -3,6 +3,16 @@
 
 The [LocatorAssertions] class provides assertion methods that can be used to make assertions about the [Locator] state in the tests. A new instance of [LocatorAssertions] is created by calling [`method: PlaywrightAssertions.expectLocator`]:
 
+```js
+import { test, expect } from '@playwright/test';
+
+test('status becomes submitted', async ({ page }) => {
+  // ...
+  await page.click('#submit-button');
+  await expect(page.locator('.status')).toHaveText('Submitted');
+});
+```
+
 ```java
 ...
 import static com.microsoft.playwright.assertions.PlaywrightAssertions.assertThat;
@@ -18,12 +28,34 @@ public class TestLocator {
 }
 ```
 
+```python async
+from playwright.async_api import Page, expect
+
+async def test_status_becomes_submitted(page: Page) -> None:
+    # ..
+    await page.click("#submit-button")
+    await expect(page.locator(".status")).to_have_text("Submitted")
+```
+
+```python sync
+from playwright.sync_api import Page, expect
+
+def test_status_becomes_submitted(page: Page) -> None:
+    # ..
+    page.click("#submit-button")
+    expect(page.locator(".status")).to_have_text("Submitted")
+```
+
 ## method: LocatorAssertions.not
 * langs: java, js
 - returns: <[LocatorAssertions]>
 
 Makes the assertion check for the opposite condition. For example, this code tests that the Locator doesn't contain text `"error"`:
 
+```js
+await expect(locator).not.toContainText('error');
+```
+
 ```java
 assertThat(locator).not().containsText("error");
 ```
@@ -234,6 +266,20 @@ await expect(locator).toBeChecked();
 assertThat(page.locator(".subscribe")).isChecked();
 ```
 
+```python async
+from playwright.async_api import expect
+
+locator = page.locator(".subscribe")
+await expect(locator).to_be_checked()
+```
+
+```python sync
+from playwright.sync_api import expect
+
+locator = page.locator(".subscribe")
+expect(locator).to_be_checked()
+```
+
 ### option: LocatorAssertions.toBeChecked.timeout = %%-assertions-timeout-%%
 
 
@@ -253,6 +299,20 @@ await expect(locator).toBeDisabled();
 assertThat(page.locator("button.submit")).isDisabled();
 ```
 
+```python async
+from playwright.async_api import expect
+
+locator = page.locator("button.submit")
+await expect(locator).to_be_disabled()
+```
+
+```python sync
+from playwright.sync_api import expect
+
+locator = page.locator("button.submit")
+expect(locator).to_be_disabled()
+```
+
 ### option: LocatorAssertions.toBeDisabled.timeout = %%-assertions-timeout-%%
 
 
@@ -271,6 +331,20 @@ await expect(locator).toBeEditable();
 assertThat(page.locator("input")).isEditable();
 ```
 
+```python async
+from playwright.async_api import expect
+
+locator = page.locator(".input")
+await expect(locator).to_be_editable()
+```
+
+```python sync
+from playwright.sync_api import expect
+
+locator = page.locator(".input")
+expect(locator).to_be_editable()
+```
+
 ### option: LocatorAssertions.toBeEditable.timeout = %%-assertions-timeout-%%
 
 
@@ -289,6 +363,20 @@ await expect(locator).toBeEmpty();
 assertThat(page.locator("div.warning")).isEmpty();
 ```
 
+```python async
+from playwright.async_api import expect
+
+locator = page.locator("div.warning")
+await expect(locator).to_be_empty()
+```
+
+```python sync
+from playwright.sync_api import expect
+
+locator = page.locator("div.warning")
+expect(locator).to_be_empty()
+```
+
 ### option: LocatorAssertions.toBeEmpty.timeout = %%-assertions-timeout-%%
 
 
@@ -307,6 +395,20 @@ await expect(locator).toBeEnabled();
 assertThat(page.locator("button.submit")).isEnabled();
 ```
 
+```python async
+from playwright.async_api import expect
+
+locator = page.locator("button.submit")
+await expect(locator).to_be_enabled()
+```
+
+```python sync
+from playwright.sync_api import expect
+
+locator = page.locator("button.submit")
+expect(locator).to_be_enabled()
+```
+
 ### option: LocatorAssertions.toBeEnabled.timeout = %%-assertions-timeout-%%
 
 
@@ -325,6 +427,20 @@ await expect(locator).toBeFocused();
 assertThat(page.locator("input")).isFocused();
 ```
 
+```python async
+from playwright.async_api import expect
+
+locator = page.locator('input')
+await expect(locator).to_be_focused()
+```
+
+```python sync
+from playwright.sync_api import expect
+
+locator = page.locator('input')
+expect(locator).to_be_focused()
+```
+
 ### option: LocatorAssertions.toBeFocused.timeout = %%-assertions-timeout-%%
 
 
@@ -343,6 +459,20 @@ await expect(locator).toBeHidden();
 assertThat(page.locator(".my-element")).isHidden();
 ```
 
+```python async
+from playwright.async_api import expect
+
+locator = page.locator('.my-element')
+await expect(locator).to_be_hidden()
+```
+
+```python sync
+from playwright.sync_api import expect
+
+locator = page.locator('.my-element')
+expect(locator).to_be_hidden()
+```
+
 ### option: LocatorAssertions.toBeHidden.timeout = %%-assertions-timeout-%%
 
 
@@ -361,6 +491,20 @@ await expect(locator).toBeVisible();
 assertThat(page.locator(".my-element")).toBeVisible();
 ```
 
+```python async
+from playwright.async_api import expect
+
+locator = page.locator('.my-element')
+await expect(locator).to_be_visible()
+```
+
+```python sync
+from playwright.sync_api import expect
+
+locator = page.locator('.my-element')
+expect(locator).to_be_visible()
+```
+
 ### option: LocatorAssertions.toBeVisible.timeout = %%-assertions-timeout-%%
 
 ## method: LocatorAssertions.toContainText
@@ -379,6 +523,24 @@ await expect(locator).toContainText(/\d messages/);
 assertThat(page.locator(".title")).containsText("substring");
 ```
 
+```python async
+import re
+from playwright.async_api import expect
+
+locator = page.locator('.title')
+await expect(locator).to_contain_text("substring")
+await expect(locator).to_contain_text(re.compile(r"\d messages"))
+```
+
+```python sync
+import re
+from playwright.sync_api import expect
+
+locator = page.locator('.title')
+expect(locator).to_contain_text("substring")
+expect(locator).to_contain_text(re.compile(r"\d messages"))
+```
+
 Note that if array is passed as an expected value, entire lists can be asserted:
 
 ```js
@@ -390,6 +552,22 @@ await expect(locator).toContainText(['Text 1', 'Text 4', 'Text 5']);
 assertThat(page.locator("list > .list-item")).containsText(new String[] {"Text 1", "Text 4", "Text 5"});
 ```
 
+```python async
+import re
+from playwright.async_api import expect
+
+locator = page.locator("list > .list-item")
+await expect(locator).to_contain_text(["Text 1", "Text 4", "Text 5"])
+```
+
+```python sync
+import re
+from playwright.sync_api import expect
+
+locator = page.locator("list > .list-item")
+expect(locator).to_contain_text(["Text 1", "Text 4", "Text 5"])
+```
+
 ### param: LocatorAssertions.toContainText.expected
 * langs: python, js
 - `expected` <[string]|[RegExp]|[Array]<[string]|[RegExp]>>
@@ -425,6 +603,20 @@ await expect(locator).toHaveAttribute('type', 'text');
 assertThat(page.locator("input")).hasAttribute("type", "text");
 ```
 
+```python async
+from playwright.async_api import expect
+
+locator = page.locator("input")
+await expect(locator).to_have_attribute("type", "text")
+```
+
+```python sync
+from playwright.sync_api import expect
+
+locator = page.locator("input")
+expect(locator).to_have_attribute("type", "text")
+```
+
 ### param: LocatorAssertions.toHaveAttribute.name
 - `name` <[string]>
 
@@ -452,6 +644,20 @@ await expect(locator).toHaveClass(/selected/);
 assertThat(page.locator("#component")).hasClass(Pattern.compile("selected"));
 ```
 
+```python async
+from playwright.async_api import expect
+
+locator = page.locator("#component")
+await expect(locator).to_have_class(re.compile(r"selected"))
+```
+
+```python sync
+from playwright.sync_api import expect
+
+locator = page.locator("#component")
+expect(locator).to_have_class(re.compile(r"selected"))
+```
+
 Note that if array is passed as an expected value, entire lists can be asserted:
 
 ```js
@@ -463,6 +669,20 @@ await expect(locator).toHaveClass(['component', 'component selected', 'component
 assertThat(page.locator("list > .component")).hasClass(new String[] {"component", "component selected", "component"});
 ```
 
+```python async
+from playwright.async_api import expect
+
+locator = page.locator("list > .component")
+await expect(locator).to_have_class(["component", "component selected", "component"])
+```
+
+```python sync
+from playwright.sync_api import expect
+
+locator = page.locator("list > .component")
+expect(locator).to_have_class(["component", "component selected", "component"])
+```
+
 ### param: LocatorAssertions.toHaveClass.expected
 * langs: python, js
 - `expected` <[string]|[RegExp]|[Array]<[string]|[RegExp]>>
@@ -493,6 +713,20 @@ await expect(list).toHaveCount(3);
 assertThat(page.locator("list > .component")).hasCount(3);
 ```
 
+```python async
+from playwright.async_api import expect
+
+locator = page.locator("list > .component")
+await expect(locator).to_have_count(3)
+```
+
+```python sync
+from playwright.sync_api import expect
+
+locator = page.locator("list > .component")
+expect(locator).to_have_count(3)
+```
+
 ### param: LocatorAssertions.toHaveCount.count
 - `count` <[int]>
 
@@ -515,6 +749,20 @@ await expect(locator).toHaveCSS('display', 'flex');
 assertThat(page.locator("button")).hasCSS("display", "flex");
 ```
 
+```python async
+from playwright.async_api import expect
+
+locator = page.locator("button")
+await expect(locator).to_have_css("display", "flex")
+```
+
+```python sync
+from playwright.sync_api import expect
+
+locator = page.locator("button")
+expect(locator).to_have_css("display", "flex")
+```
+
 ### param: LocatorAssertions.toHaveCSS.name
 - `name` <[string]>
 
@@ -542,6 +790,20 @@ await expect(locator).toHaveId('lastname');
 assertThat(page.locator("input")).hasId("lastname");
 ```
 
+```python async
+from playwright.async_api import expect
+
+locator = page.locator("input")
+await expect(locator).to_have_id("lastname")
+```
+
+```python sync
+from playwright.sync_api import expect
+
+locator = page.locator("input")
+expect(locator).to_have_id("lastname")
+```
+
 ### param: LocatorAssertions.toHaveId.id
 - `id` <[string]|[RegExp]>
 
@@ -563,7 +825,21 @@ await expect(locator).toHaveJSProperty('loaded', true);
 ```
 
 ```java
-assertThat(page.locator("input")).hasJSProperty("type", "text");
+assertThat(page.locator("input")).hasJSProperty("loaded", true);
+```
+
+```python async
+from playwright.async_api import expect
+
+locator = page.locator(".component")
+await expect(locator).to_have_js_property("loaded", True)
+```
+
+```python sync
+from playwright.sync_api import expect
+
+locator = page.locator(".component")
+expect(locator).to_have_js_property("loaded", True)
 ```
 
 ### param: LocatorAssertions.toHaveJSProperty.name
@@ -595,6 +871,24 @@ assertThat(page.locator(".title")).hasText("Welcome, Test User");
 assertThat(page.locator(".title")).hasText(Pattern.compile("Welcome, .*"));
 ```
 
+```python async
+import re
+from playwright.async_api import expect
+
+locator = page.locator(".title")
+await expect(locator).to_have_text(re.compile(r"Welcome, Test User"))
+await expect(locator).to_have_text(re.compile(r"Welcome, .*"))
+```
+
+```python sync
+import re
+from playwright.sync_api import expect
+
+locator = page.locator(".title")
+expect(locator).to_have_text(re.compile(r"Welcome, Test User"))
+expect(locator).to_have_text(re.compile(r"Welcome, .*"))
+```
+
 Note that if array is passed as an expected value, entire lists can be asserted:
 
 ```js
@@ -606,6 +900,20 @@ await expect(locator).toHaveText(['Text 1', 'Text 2', 'Text 3']);
 assertThat(page.locator("list > .component")).hasText(new String[] {"Text 1", "Text 2", "Text 3"});
 ```
 
+```python async
+from playwright.async_api import expect
+
+locator = page.locator("list > .component")
+await expect(locator).to_have_text(["Text 1", "Text 2", "Text 3"])
+```
+
+```python sync
+from playwright.sync_api import expect
+
+locator = page.locator("list > .component")
+expect(locator).to_have_text(["Text 1", "Text 2", "Text 3"])
+```
+
 ### param: LocatorAssertions.toHaveText.expected
 * langs: python, js
 - `expected` <[string]|[RegExp]|[Array]<[string]|[RegExp]>>
@@ -640,6 +948,22 @@ await expect(locator).toHaveValue(/[0-9]/);
 assertThat(page.locator("input[type=number]")).hasValue(Pattern.compile("[0-9]"));
 ```
 
+```python async
+import re
+from playwright.async_api import expect
+
+locator = page.locator("input[type=number]")
+await expect(locator).to_have_value(re.compile(r"[0-9]"))
+```
+
+```python sync
+import re
+from playwright.sync_api import expect
+
+locator = page.locator("input[type=number]")
+expect(locator).to_have_value(re.compile(r"[0-9]"))
+```
+
 ### param: LocatorAssertions.toHaveValue.value
 - `value` <[string]|[RegExp]>
 
diff --git a/docs/src/api/class-pageassertions.md b/docs/src/api/class-pageassertions.md
index eed1aba4d0..65bd078150 100644
--- a/docs/src/api/class-pageassertions.md
+++ b/docs/src/api/class-pageassertions.md
@@ -3,6 +3,16 @@
 
 The [PageAssertions] class provides assertion methods that can be used to make assertions about the [Page] state in the tests. A new instance of [LocatorAssertions] is created by calling [`method: PlaywrightAssertions.expectPage`]:
 
+```js
+import { test, expect } from '@playwright/test';
+
+test('navigates to login', async ({ page }) => {
+  // ...
+  await page.click('#login');
+  await expect(page).toHaveURL(/.*\/login/);
+});
+```
+
 ```java
 ...
 import static com.microsoft.playwright.assertions.PlaywrightAssertions.assertThat;
@@ -18,6 +28,26 @@ public class TestPage {
 }
 ```
 
+```python async
+import re
+from playwright.async_api import Page, expect
+
+async def test_navigates_to_login_page(page: Page) -> None:
+    # ..
+    await page.click("#login")
+    await expect(page).to_have_url(re.compile(r".*/login"))
+```
+
+```python sync
+import re
+from playwright.sync_api import Page, expect
+
+def test_navigates_to_login_page(page: Page) -> None:
+    # ..
+    page.click("#login")
+    expect(page).to_have_url(re.compile(r".*/login"))
+```
+
 
 ## method: PageAssertions.not
 * langs: java, js
@@ -25,6 +55,10 @@ public class TestPage {
 
 Makes the assertion check for the opposite condition. For example, this code tests that the page URL doesn't contain `"error"`:
 
+```js
+await expect(page).not.toHaveURL('error');
+```
+
 ```java
 assertThat(page).not().hasURL("error");
 ```
@@ -69,6 +103,22 @@ await expect(page).toHaveTitle(/.*checkout/);
 assertThat(page).hasTitle("Playwright");
 ```
 
+```python async
+import re
+from playwright.async_api import expect
+
+# ...
+await expect(page).to_have_title(re.compile(r".*checkout"))
+```
+
+```python sync
+import re
+from playwright.sync_api import expect
+
+# ...
+expect(page).to_have_title(re.compile(r".*checkout"))
+```
+
 ### param: PageAssertions.toHaveTitle.titleOrRegExp
 - `titleOrRegExp` <[string]|[RegExp]>
 
@@ -90,6 +140,22 @@ await expect(page).toHaveURL(/.*checkout/);
 assertThat(page).hasURL(".com");
 ```
 
+```python async
+import re
+from playwright.async_api import expect
+
+# ...
+await expect(page).to_have_url(re.compile(".*checkout"))
+```
+
+```python sync
+import re
+from playwright.sync_api import expect
+
+# ...
+expect(page).to_have_url(re.compile(".*checkout"))
+```
+
 ### param: PageAssertions.toHaveURL.urlOrRegExp
 - `urlOrRegExp` <[string]|[RegExp]>
 
diff --git a/docs/src/api/class-playwrightassertions.md b/docs/src/api/class-playwrightassertions.md
index 22b56ed153..1e375bb227 100644
--- a/docs/src/api/class-playwrightassertions.md
+++ b/docs/src/api/class-playwrightassertions.md
@@ -18,17 +18,19 @@ test('status becomes submitted', async ({ page }) => {
 ```python async
 from playwright.async_api import Page, expect
 
-async def test_assertions_page_to_have_title(page: Page) -> None:
-    await page.click('#submit-button')
-    await expect(page.locator('.status')).to_have_text('Submitted')
+async def test_status_becomes_submitted(page: Page) -> None:
+    # ..
+    await page.click("#submit-button")
+    await expect(page.locator(".status")).to_have_text("Submitted")
 ```
 
 ```python sync
 from playwright.sync_api import Page, expect
 
-def test_assertions_page_to_have_title(page: Page) -> None:
-    page.click('#submit-button')
-    expect(page.locator('.status')).to_have_text('Submitted')
+def test_status_becomes_submitted(page: Page) -> None:
+    # ..
+    page.click("#submit-button")
+    expect(page.locator(".status")).to_have_text("Submitted")
 ```
 
 ```java