diff --git a/docs/src/api/class-locator.md b/docs/src/api/class-locator.md
index c1fbdb2f6a..8318dc0c61 100644
--- a/docs/src/api/class-locator.md
+++ b/docs/src/api/class-locator.md
@@ -643,6 +643,7 @@ Locator of the element to drag to.
 
 ## async method: Locator.elementHandle
 * since: v1.14
+* discouraged: Always prefer using [Locator]s and web assertions over [ElementHandle]s because latter are inherently racy.
 - returns: <[ElementHandle]>
 
 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.
@@ -652,6 +653,7 @@ Resolves given locator to the first matching DOM element. If there are no matchi
 
 ## async method: Locator.elementHandles
 * since: v1.14
+* discouraged: Always prefer using [Locator]s and web assertions over [ElementHandle]s because latter are inherently racy.
 - returns: <[Array]<[ElementHandle]>>
 
 Resolves given locator to all matching DOM elements. If there are no matching elements, returns an empty list.
diff --git a/docs/src/api/class-page.md b/docs/src/api/class-page.md
index 938dfbdaa4..a83f0da4a5 100644
--- a/docs/src/api/class-page.md
+++ b/docs/src/api/class-page.md
@@ -4031,6 +4031,7 @@ Console.WriteLine(await popup.TitleAsync()); // popup is ready to use.
 
 ## async method: Page.waitForNavigation
 * since: v1.8
+* deprecated: This method is inherently racy, please use [`method: Page.waitForURL`] instead.
 * langs:
   * alias-python: expect_navigation
   * alias-csharp: RunAndWaitForNavigation
diff --git a/packages/playwright-core/types/types.d.ts b/packages/playwright-core/types/types.d.ts
index 4d43277e74..9c6e4c7bb1 100644
--- a/packages/playwright-core/types/types.d.ts
+++ b/packages/playwright-core/types/types.d.ts
@@ -4462,6 +4462,8 @@ export interface Page {
    *
    * **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.
+   * @deprecated This method is inherently racy, please use
+   * [page.waitForURL(url[, options])](https://playwright.dev/docs/api/class-page#page-wait-for-url) instead.
    * @param options
    */
   waitForNavigation(options?: {
@@ -10085,6 +10087,8 @@ export interface Locator {
    */
   evaluateAll<R, E extends SVGElement | HTMLElement = SVGElement | HTMLElement>(pageFunction: PageFunctionOn<E[], void, R>): Promise<R>;
   /**
+   * **NOTE** Always prefer using [Locator]s and web assertions over [ElementHandle]s because latter are inherently racy.
+   *
    * 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.
    * @param options
@@ -10614,6 +10618,8 @@ export interface Locator {
   }): Promise<void>;
 
   /**
+   * **NOTE** Always prefer using [Locator]s and web assertions over [ElementHandle]s because latter are inherently racy.
+   *
    * Resolves given locator to all matching DOM elements. If there are no matching elements, returns an empty list.
    */
   elementHandles(): Promise<Array<ElementHandle>>;