From b0ceed51a54f9c11dd8ed553396b4350bdd6548e Mon Sep 17 00:00:00 2001
From: Adam Gastineau <adam@agg.im>
Date: Thu, 27 Feb 2025 11:00:50 -0800
Subject: [PATCH] docs: Improve toHaveURL doc clarity (#34935)

---
 docs/src/api/class-pageassertions.md | 15 +++++++++++++--
 packages/playwright/types/test.d.ts  | 22 +++++++++++++++++-----
 2 files changed, 30 insertions(+), 7 deletions(-)

diff --git a/docs/src/api/class-pageassertions.md b/docs/src/api/class-pageassertions.md
index 38a05b9df8..ef8c7d4f6e 100644
--- a/docs/src/api/class-pageassertions.md
+++ b/docs/src/api/class-pageassertions.md
@@ -296,7 +296,18 @@ Ensures the page is navigated to the given URL.
 **Usage**
 
 ```js
-await expect(page).toHaveURL(/.*checkout/);
+// Check for the page URL to be 'https://playwright.dev/docs/intro' (including query string)
+await expect(page).toHaveURL('https://playwright.dev/docs/intro');
+
+// Check for the page URL to contain 'doc', followed by an optional 's', followed by '/'
+await expect(page).toHaveURL(/docs?\//);
+
+// Check for the predicate to be satisfied
+// For example: verify query strings
+await expect(page).toHaveURL(url => {
+  const params = url.searchParams;
+  return params.has('search') && params.has('options') && params.get('id') === '5';
+});
 ```
 
 ```java
@@ -328,7 +339,7 @@ await Expect(Page).ToHaveURLAsync(new Regex(".*checkout"));
 - `url` <[string]|[RegExp]|[function]\([URL]\):[boolean]>
 
 Expected URL string, RegExp, or predicate receiving [URL] to match.
-When a [`option: Browser.newContext.baseURL`] via the context options was provided and the passed URL is a path, it gets merged via the [`new URL()`](https://developer.mozilla.org/en-US/docs/Web/API/URL/URL) constructor.
+When [`option: Browser.newContext.baseURL`] is provided via the context options and the `url` argument is a string, the two values are merged via the [`new URL()`](https://developer.mozilla.org/en-US/docs/Web/API/URL/URL) constructor and used for the comparison against the current browser URL.
 
 ### option: PageAssertions.toHaveURL.ignoreCase
 * since: v1.44
diff --git a/packages/playwright/types/test.d.ts b/packages/playwright/types/test.d.ts
index 4cc816993a..bdb45169b6 100644
--- a/packages/playwright/types/test.d.ts
+++ b/packages/playwright/types/test.d.ts
@@ -8902,13 +8902,25 @@ interface PageAssertions {
    * **Usage**
    *
    * ```js
-   * await expect(page).toHaveURL(/.*checkout/);
+   * // Check for the page URL to be 'https://playwright.dev/docs/intro' (including query string)
+   * await expect(page).toHaveURL('https://playwright.dev/docs/intro');
+   *
+   * // Check for the page URL to contain 'doc', followed by an optional 's', followed by '/'
+   * await expect(page).toHaveURL(/docs?\//);
+   *
+   * // Check for the predicate to be satisfied
+   * // For example: verify query strings
+   * await expect(page).toHaveURL(url => {
+   *   const params = url.searchParams;
+   *   return params.has('search') && params.has('options') && params.get('id') === '5';
+   * });
    * ```
    *
-   * @param url Expected URL string, RegExp, or predicate receiving [URL] to match. When a
-   * [`baseURL`](https://playwright.dev/docs/api/class-browser#browser-new-context-option-base-url) via the context
-   * options was provided and the passed URL is a path, it gets merged via the
-   * [`new URL()`](https://developer.mozilla.org/en-US/docs/Web/API/URL/URL) constructor.
+   * @param url Expected URL string, RegExp, or predicate receiving [URL] to match. When
+   * [`baseURL`](https://playwright.dev/docs/api/class-browser#browser-new-context-option-base-url) is provided via the
+   * context options and the `url` argument is a string, the two values are merged via the
+   * [`new URL()`](https://developer.mozilla.org/en-US/docs/Web/API/URL/URL) constructor and used for the comparison
+   * against the current browser URL.
    * @param options
    */
   toHaveURL(url: string|RegExp|((url: URL) => boolean), options?: {