From 2a8d6a8207b2160dfdf9f4c755b3e548e1a9719e Mon Sep 17 00:00:00 2001
From: Dmitry Gozman <dgozman@gmail.com>
Date: Fri, 29 Sep 2023 10:52:20 -0700
Subject: [PATCH] docs: encourage using `expect()` instead of getters like
 `textContent()` (#27362)

---
 docs/src/api/class-locator.md             | 52 +++++++++++++++++++++++
 packages/playwright-core/types/types.d.ts | 52 +++++++++++++++++++++++
 2 files changed, 104 insertions(+)

diff --git a/docs/src/api/class-locator.md b/docs/src/api/class-locator.md
index 3def5f0e5d..177b75be46 100644
--- a/docs/src/api/class-locator.md
+++ b/docs/src/api/class-locator.md
@@ -53,6 +53,10 @@ foreach (var li in await page.GetByRole("listitem").AllAsync())
 
 Returns an array of `node.innerText` values for all matching nodes.
 
+:::caution Asserting text
+If you need to assert text on the page, prefer [`method: LocatorAssertions.toHaveText`] with [`option: useInnerText`] option to avoid flakiness. See [assertions guide](../test-assertions.md) for more details.
+:::
+
 **Usage**
 
 ```js
@@ -81,6 +85,10 @@ var texts = await page.GetByRole(AriaRole.Link).AllInnerTextsAsync();
 
 Returns an array of `node.textContent` values for all matching nodes.
 
+:::caution Asserting text
+If you need to assert text on the page, prefer [`method: LocatorAssertions.toHaveText`] to avoid flakiness. See [assertions guide](../test-assertions.md) for more details.
+:::
+
 **Usage**
 
 ```js
@@ -435,6 +443,10 @@ await page.Locator("canvas").ClickAsync(new() {
 
 Returns the number of elements matching the locator.
 
+:::caution Asserting count
+If you need to assert the number of elements on the page, prefer [`method: LocatorAssertions.toHaveCount`] to avoid flakiness. See [assertions guide](../test-assertions.md) for more details.
+:::
+
 **Usage**
 
 ```js
@@ -1059,6 +1071,10 @@ await locator.ClickAsync();
 
 Returns the matching element's attribute value.
 
+:::caution Asserting attributes
+If you need to assert an element's attribute, prefer [`method: LocatorAssertions.toHaveAttribute`] to avoid flakiness. See [assertions guide](../test-assertions.md) for more details.
+:::
+
 ### param: Locator.getAttribute.name
 * since: v1.14
 - `name` <[string]>
@@ -1227,6 +1243,10 @@ Returns the [`element.innerHTML`](https://developer.mozilla.org/en-US/docs/Web/A
 
 Returns the [`element.innerText`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/innerText).
 
+:::caution Asserting text
+If you need to assert text on the page, prefer [`method: LocatorAssertions.toHaveText`] with [`option: useInnerText`] option to avoid flakiness. See [assertions guide](../test-assertions.md) for more details.
+:::
+
 ### option: Locator.innerText.timeout = %%-input-timeout-%%
 * since: v1.14
 
@@ -1239,6 +1259,10 @@ Returns the [`element.innerText`](https://developer.mozilla.org/en-US/docs/Web/A
 
 Returns the value for the matching `<input>` or `<textarea>` or `<select>` element.
 
+:::caution Asserting value
+If you need to assert input value, prefer [`method: LocatorAssertions.toHaveValue`] to avoid flakiness. See [assertions guide](../test-assertions.md) for more details.
+:::
+
 **Usage**
 
 ```js
@@ -1277,6 +1301,10 @@ Throws elements that are not an input, textarea or a select. However, if the ele
 
 Returns whether the element is checked. Throws if the element is not a checkbox or radio input.
 
+:::caution Asserting checked state
+If you need to assert that checkobx is checked, prefer [`method: LocatorAssertions.toBeChecked`] to avoid flakiness. See [assertions guide](../test-assertions.md) for more details.
+:::
+
 **Usage**
 
 ```js
@@ -1311,6 +1339,10 @@ var isChecked = await page.GetByRole(AriaRole.Checkbox).IsCheckedAsync();
 
 Returns whether the element is disabled, the opposite of [enabled](../actionability.md#enabled).
 
+:::caution Asserting disabled state
+If you need to assert that an element is disabled, prefer [`method: LocatorAssertions.toBeDisabled`] to avoid flakiness. See [assertions guide](../test-assertions.md) for more details.
+:::
+
 **Usage**
 
 ```js
@@ -1345,6 +1377,10 @@ Boolean disabled = await page.GetByRole(AriaRole.Button).IsDisabledAsync();
 
 Returns whether the element is [editable](../actionability.md#editable).
 
+:::caution Asserting editable state
+If you need to assert that an element is editable, prefer [`method: LocatorAssertions.toBeEditable`] to avoid flakiness. See [assertions guide](../test-assertions.md) for more details.
+:::
+
 **Usage**
 
 ```js
@@ -1379,6 +1415,10 @@ Boolean editable = await page.GetByRole(AriaRole.Textbox).IsEditableAsync();
 
 Returns whether the element is [enabled](../actionability.md#enabled).
 
+:::caution Asserting enabled state
+If you need to assert that an element is enabled, prefer [`method: LocatorAssertions.toBeEnabled`] to avoid flakiness. See [assertions guide](../test-assertions.md) for more details.
+:::
+
 **Usage**
 
 ```js
@@ -1413,6 +1453,10 @@ Boolean enabled = await page.GetByRole(AriaRole.Button).IsEnabledAsync();
 
 Returns whether the element is hidden, the opposite of [visible](../actionability.md#visible).
 
+:::caution Asserting visibility
+If you need to assert that element is hidden, prefer [`method: LocatorAssertions.toBeHidden`] to avoid flakiness. See [assertions guide](../test-assertions.md) for more details.
+:::
+
 **Usage**
 
 ```js
@@ -1446,6 +1490,10 @@ Boolean hidden = await page.GetByRole(AriaRole.Button).IsHiddenAsync();
 
 Returns whether the element is [visible](../actionability.md#visible).
 
+:::caution Asserting visibility
+If you need to assert that element is visible, prefer [`method: LocatorAssertions.toBeVisible`] to avoid flakiness. See [assertions guide](../test-assertions.md) for more details.
+:::
+
 **Usage**
 
 ```js
@@ -2223,6 +2271,10 @@ When all steps combined have not finished during the specified [`option: timeout
 
 Returns the [`node.textContent`](https://developer.mozilla.org/en-US/docs/Web/API/Node/textContent).
 
+:::caution Asserting text
+If you need to assert text on the page, prefer [`method: LocatorAssertions.toHaveText`] to avoid flakiness. See [assertions guide](../test-assertions.md) for more details.
+:::
+
 ### option: Locator.textContent.timeout = %%-input-timeout-%%
 * since: v1.14
 
diff --git a/packages/playwright-core/types/types.d.ts b/packages/playwright-core/types/types.d.ts
index 51fb492427..989c2e5182 100644
--- a/packages/playwright-core/types/types.d.ts
+++ b/packages/playwright-core/types/types.d.ts
@@ -10575,6 +10575,10 @@ export interface Locator {
   /**
    * Returns an array of `node.innerText` values for all matching nodes.
    *
+   * **NOTE** If you need to assert text on the page, prefer
+   * [locatorAssertions.toHaveText(expected[, options])](https://playwright.dev/docs/api/class-locatorassertions#locator-assertions-to-have-text)
+   * with `useInnerText` option to avoid flakiness. See [assertions guide](https://playwright.dev/docs/test-assertions) for more details.
+   *
    * **Usage**
    *
    * ```js
@@ -10587,6 +10591,10 @@ export interface Locator {
   /**
    * Returns an array of `node.textContent` values for all matching nodes.
    *
+   * **NOTE** If you need to assert text on the page, prefer
+   * [locatorAssertions.toHaveText(expected[, options])](https://playwright.dev/docs/api/class-locatorassertions#locator-assertions-to-have-text)
+   * to avoid flakiness. See [assertions guide](https://playwright.dev/docs/test-assertions) for more details.
+   *
    * **Usage**
    *
    * ```js
@@ -10889,6 +10897,10 @@ export interface Locator {
   /**
    * Returns the number of elements matching the locator.
    *
+   * **NOTE** If you need to assert the number of elements on the page, prefer
+   * [locatorAssertions.toHaveCount(count[, options])](https://playwright.dev/docs/api/class-locatorassertions#locator-assertions-to-have-count)
+   * to avoid flakiness. See [assertions guide](https://playwright.dev/docs/test-assertions) for more details.
+   *
    * **Usage**
    *
    * ```js
@@ -11235,6 +11247,10 @@ export interface Locator {
 
   /**
    * Returns the matching element's attribute value.
+   *
+   * **NOTE** If you need to assert an element's attribute, prefer
+   * [locatorAssertions.toHaveAttribute(name, value[, options])](https://playwright.dev/docs/api/class-locatorassertions#locator-assertions-to-have-attribute)
+   * to avoid flakiness. See [assertions guide](https://playwright.dev/docs/test-assertions) for more details.
    * @param name Attribute name to get the value for.
    * @param options
    */
@@ -11650,6 +11666,10 @@ export interface Locator {
 
   /**
    * Returns the [`element.innerText`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/innerText).
+   *
+   * **NOTE** If you need to assert text on the page, prefer
+   * [locatorAssertions.toHaveText(expected[, options])](https://playwright.dev/docs/api/class-locatorassertions#locator-assertions-to-have-text)
+   * with `useInnerText` option to avoid flakiness. See [assertions guide](https://playwright.dev/docs/test-assertions) for more details.
    * @param options
    */
   innerText(options?: {
@@ -11665,6 +11685,10 @@ export interface Locator {
   /**
    * Returns the value for the matching `<input>` or `<textarea>` or `<select>` element.
    *
+   * **NOTE** If you need to assert input value, prefer
+   * [locatorAssertions.toHaveValue(value[, options])](https://playwright.dev/docs/api/class-locatorassertions#locator-assertions-to-have-value)
+   * to avoid flakiness. See [assertions guide](https://playwright.dev/docs/test-assertions) for more details.
+   *
    * **Usage**
    *
    * ```js
@@ -11692,6 +11716,10 @@ export interface Locator {
   /**
    * Returns whether the element is checked. Throws if the element is not a checkbox or radio input.
    *
+   * **NOTE** If you need to assert that checkobx is checked, prefer
+   * [locatorAssertions.toBeChecked([options])](https://playwright.dev/docs/api/class-locatorassertions#locator-assertions-to-be-checked)
+   * to avoid flakiness. See [assertions guide](https://playwright.dev/docs/test-assertions) for more details.
+   *
    * **Usage**
    *
    * ```js
@@ -11713,6 +11741,10 @@ export interface Locator {
   /**
    * Returns whether the element is disabled, the opposite of [enabled](https://playwright.dev/docs/actionability#enabled).
    *
+   * **NOTE** If you need to assert that an element is disabled, prefer
+   * [locatorAssertions.toBeDisabled([options])](https://playwright.dev/docs/api/class-locatorassertions#locator-assertions-to-be-disabled)
+   * to avoid flakiness. See [assertions guide](https://playwright.dev/docs/test-assertions) for more details.
+   *
    * **Usage**
    *
    * ```js
@@ -11734,6 +11766,10 @@ export interface Locator {
   /**
    * Returns whether the element is [editable](https://playwright.dev/docs/actionability#editable).
    *
+   * **NOTE** If you need to assert that an element is editable, prefer
+   * [locatorAssertions.toBeEditable([options])](https://playwright.dev/docs/api/class-locatorassertions#locator-assertions-to-be-editable)
+   * to avoid flakiness. See [assertions guide](https://playwright.dev/docs/test-assertions) for more details.
+   *
    * **Usage**
    *
    * ```js
@@ -11755,6 +11791,10 @@ export interface Locator {
   /**
    * Returns whether the element is [enabled](https://playwright.dev/docs/actionability#enabled).
    *
+   * **NOTE** If you need to assert that an element is enabled, prefer
+   * [locatorAssertions.toBeEnabled([options])](https://playwright.dev/docs/api/class-locatorassertions#locator-assertions-to-be-enabled)
+   * to avoid flakiness. See [assertions guide](https://playwright.dev/docs/test-assertions) for more details.
+   *
    * **Usage**
    *
    * ```js
@@ -11776,6 +11816,10 @@ export interface Locator {
   /**
    * Returns whether the element is hidden, the opposite of [visible](https://playwright.dev/docs/actionability#visible).
    *
+   * **NOTE** If you need to assert that element is hidden, prefer
+   * [locatorAssertions.toBeHidden([options])](https://playwright.dev/docs/api/class-locatorassertions#locator-assertions-to-be-hidden)
+   * to avoid flakiness. See [assertions guide](https://playwright.dev/docs/test-assertions) for more details.
+   *
    * **Usage**
    *
    * ```js
@@ -11796,6 +11840,10 @@ export interface Locator {
   /**
    * Returns whether the element is [visible](https://playwright.dev/docs/actionability#visible).
    *
+   * **NOTE** If you need to assert that element is visible, prefer
+   * [locatorAssertions.toBeVisible([options])](https://playwright.dev/docs/api/class-locatorassertions#locator-assertions-to-be-visible)
+   * to avoid flakiness. See [assertions guide](https://playwright.dev/docs/test-assertions) for more details.
+   *
    * **Usage**
    *
    * ```js
@@ -12395,6 +12443,10 @@ export interface Locator {
 
   /**
    * Returns the [`node.textContent`](https://developer.mozilla.org/en-US/docs/Web/API/Node/textContent).
+   *
+   * **NOTE** If you need to assert text on the page, prefer
+   * [locatorAssertions.toHaveText(expected[, options])](https://playwright.dev/docs/api/class-locatorassertions#locator-assertions-to-have-text)
+   * to avoid flakiness. See [assertions guide](https://playwright.dev/docs/test-assertions) for more details.
    * @param options
    */
   textContent(options?: {