From ee39af260d1442256c9964e50562390e6307bae5 Mon Sep 17 00:00:00 2001 From: Pavel Feldman Date: Fri, 31 Mar 2023 20:24:08 -0700 Subject: [PATCH] chore: discourage waitForSelector (#22133) --- docs/src/api/class-frame.md | 2 ++ docs/src/api/class-page.md | 4 +++ packages/playwright-core/types/types.d.ts | 35 +++++++++++++++++++++++ 3 files changed, 41 insertions(+) diff --git a/docs/src/api/class-frame.md b/docs/src/api/class-frame.md index ac7bb4147e..994e92628f 100644 --- a/docs/src/api/class-frame.md +++ b/docs/src/api/class-frame.md @@ -2104,6 +2104,8 @@ a navigation. ## async method: Frame.waitForSelector * since: v1.8 +* discouraged: Use web assertions that assert visibility or a locator-based [`method: Locator.waitFor`] instead. + Read more about [locators](../locators.md). - returns: <[null]|[ElementHandle]> Returns when element specified by selector satisfies [`option: state`] option. Returns `null` if waiting for `hidden` or diff --git a/docs/src/api/class-page.md b/docs/src/api/class-page.md index 4892f530cf..b952ac6e36 100644 --- a/docs/src/api/class-page.md +++ b/docs/src/api/class-page.md @@ -4654,6 +4654,8 @@ changed by using the [`method: BrowserContext.setDefaultTimeout`] or [`method: P ## async method: Page.waitForSelector * since: v1.8 +* discouraged: Use web assertions that assert visibility or a locator-based [`method: Locator.waitFor`] instead. + Read more about [locators](../locators.md). - returns: <[null]|[ElementHandle]> Returns when element specified by selector satisfies [`option: state`] option. Returns `null` if waiting for `hidden` or @@ -4814,6 +4816,8 @@ Codition to wait for. ## async method: Page.waitForTimeout * since: v1.8 +* discouraged: Never wait for timeout in production. Tests that wait for time are + inherently flaky. Use [Locator] actions and web assertions that wait automatically. Waits for the given [`param: timeout`] in milliseconds. diff --git a/packages/playwright-core/types/types.d.ts b/packages/playwright-core/types/types.d.ts index 99337e9769..00fe441089 100644 --- a/packages/playwright-core/types/types.d.ts +++ b/packages/playwright-core/types/types.d.ts @@ -611,6 +611,10 @@ export interface Page { waitForFunction(pageFunction: PageFunction, arg?: any, options?: PageWaitForFunctionOptions): Promise>; /** + * **NOTE** Use web assertions that assert visibility or a locator-based + * [locator.waitFor([options])](https://playwright.dev/docs/api/class-locator#locator-wait-for) instead. Read more + * about [locators](https://playwright.dev/docs/locators). + * * Returns when element specified by selector satisfies `state` option. Returns `null` if waiting for `hidden` or * `detached`. * @@ -645,6 +649,10 @@ export interface Page { */ waitForSelector(selector: K, options?: PageWaitForSelectorOptionsNotHidden): Promise>; /** + * **NOTE** Use web assertions that assert visibility or a locator-based + * [locator.waitFor([options])](https://playwright.dev/docs/api/class-locator#locator-wait-for) instead. Read more + * about [locators](https://playwright.dev/docs/locators). + * * Returns when element specified by selector satisfies `state` option. Returns `null` if waiting for `hidden` or * `detached`. * @@ -679,6 +687,10 @@ export interface Page { */ waitForSelector(selector: string, options?: PageWaitForSelectorOptionsNotHidden): Promise>; /** + * **NOTE** Use web assertions that assert visibility or a locator-based + * [locator.waitFor([options])](https://playwright.dev/docs/api/class-locator#locator-wait-for) instead. Read more + * about [locators](https://playwright.dev/docs/locators). + * * Returns when element specified by selector satisfies `state` option. Returns `null` if waiting for `hidden` or * `detached`. * @@ -713,6 +725,10 @@ export interface Page { */ waitForSelector(selector: K, options: PageWaitForSelectorOptions): Promise | null>; /** + * **NOTE** Use web assertions that assert visibility or a locator-based + * [locator.waitFor([options])](https://playwright.dev/docs/api/class-locator#locator-wait-for) instead. Read more + * about [locators](https://playwright.dev/docs/locators). + * * Returns when element specified by selector satisfies `state` option. Returns `null` if waiting for `hidden` or * `detached`. * @@ -4558,6 +4574,9 @@ export interface Page { }): Promise; /** + * **NOTE** Never wait for timeout in production. Tests that wait for time are inherently flaky. Use [Locator] actions and web + * assertions that wait automatically. + * * Waits for the given `timeout` in milliseconds. * * Note that `page.waitForTimeout()` should only be used for debugging. Tests using the timer in production are going @@ -5202,6 +5221,10 @@ export interface Frame { waitForFunction(pageFunction: PageFunction, arg?: any, options?: PageWaitForFunctionOptions): Promise>; /** + * **NOTE** Use web assertions that assert visibility or a locator-based + * [locator.waitFor([options])](https://playwright.dev/docs/api/class-locator#locator-wait-for) instead. Read more + * about [locators](https://playwright.dev/docs/locators). + * * Returns when element specified by selector satisfies `state` option. Returns `null` if waiting for `hidden` or * `detached`. * @@ -5236,6 +5259,10 @@ export interface Frame { */ waitForSelector(selector: K, options?: PageWaitForSelectorOptionsNotHidden): Promise>; /** + * **NOTE** Use web assertions that assert visibility or a locator-based + * [locator.waitFor([options])](https://playwright.dev/docs/api/class-locator#locator-wait-for) instead. Read more + * about [locators](https://playwright.dev/docs/locators). + * * Returns when element specified by selector satisfies `state` option. Returns `null` if waiting for `hidden` or * `detached`. * @@ -5270,6 +5297,10 @@ export interface Frame { */ waitForSelector(selector: string, options?: PageWaitForSelectorOptionsNotHidden): Promise>; /** + * **NOTE** Use web assertions that assert visibility or a locator-based + * [locator.waitFor([options])](https://playwright.dev/docs/api/class-locator#locator-wait-for) instead. Read more + * about [locators](https://playwright.dev/docs/locators). + * * Returns when element specified by selector satisfies `state` option. Returns `null` if waiting for `hidden` or * `detached`. * @@ -5304,6 +5335,10 @@ export interface Frame { */ waitForSelector(selector: K, options: PageWaitForSelectorOptions): Promise | null>; /** + * **NOTE** Use web assertions that assert visibility or a locator-based + * [locator.waitFor([options])](https://playwright.dev/docs/api/class-locator#locator-wait-for) instead. Read more + * about [locators](https://playwright.dev/docs/locators). + * * Returns when element specified by selector satisfies `state` option. Returns `null` if waiting for `hidden` or * `detached`. *