Skip to content

Playwright is a framework for Web Testing and Automation. It allows testing Chromium, Firefox and WebKit with a single API.

docs: Improve toHaveURL doc clarity (#34935)

Adam Gastineaub0ceed51a54f
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?: {