From 5f0c76f7d40c4370a8402168ea0b597a8212bd77 Mon Sep 17 00:00:00 2001
From: Ryan Chung <ryan.chung.cs@gmail.com>
Date: Sat, 28 Dec 2024 06:51:08 -0500
Subject: [PATCH] docs(test-assertions-js): add base matcher mutability caution
 note

---
 docs/src/test-assertions-js.md | 12 ++++++++++++
 1 file changed, 12 insertions(+)

diff --git a/docs/src/test-assertions-js.md b/docs/src/test-assertions-js.md
index 162d0351eb..457533b18f 100644
--- a/docs/src/test-assertions-js.md
+++ b/docs/src/test-assertions-js.md
@@ -308,6 +308,18 @@ test('amount', async () => {
 });
 ```
 
+Note that `expect.extend()` is mutable, so overriding base matchers may cause infinite loops, such as below.
+
+```js title="example.spec.ts"
+import { expect as baseExpect } from '@playwright/test';
+
+export const expect = baseExpect.extend({
+  toHaveURL: async (...args: any[]) => {
+    await expect.toHaveURL(...args);
+  },
+});
+```
+
 ### Compatibility with expect library
 
 :::note