Skip to content

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

docs(bfcache): add note about Back/Forward Cache (BFCache) limitations and default behavior (#41872)

Kashish Sahu6a301da1070b
diff --git a/docs/src/api/class-page.md b/docs/src/api/class-page.md
index 04d0932668..6549e7e10d 100644
--- a/docs/src/api/class-page.md
+++ b/docs/src/api/class-page.md
@@ -2354,6 +2354,11 @@ last redirect. If cannot go back, returns `null`.
Navigate to the previous page in history.
+:::warning
+**Testing Back/Forward Cache (BFCache) is not supported.**
+By default, Playwright disables the Back/Forward Cache across all browsers. Even if explicitly enabled, Playwright's internal state relies on network-level navigation events. Because BFCache restores unfreeze the DOM without firing these events, using `page.goBack()` or `page.goForward()` to trigger a BFCache restore will result in timeouts and a desynchronized `Page` state.
+:::
+
### option: Page.goBack.waitUntil = %%-navigation-wait-until-%%
* since: v1.8
@@ -2374,6 +2379,11 @@ last redirect. If cannot go forward, returns `null`.
Navigate to the next page in history.
+:::warning
+**Testing Back/Forward Cache (BFCache) is not supported.**
+By default, Playwright disables the Back/Forward Cache across all browsers. Even if explicitly enabled, Playwright's internal state relies on network-level navigation events. Because BFCache restores unfreeze the DOM without firing these events, using `page.goBack()` or `page.goForward()` to trigger a BFCache restore will result in timeouts and a desynchronized `Page` state.
+:::
+
## async method: Page.requestGC
* since: v1.48
diff --git a/docs/src/navigations.md b/docs/src/navigations.md
index 44bab9187a..95c374a082 100644
--- a/docs/src/navigations.md
+++ b/docs/src/navigations.md
@@ -150,6 +150,16 @@ await page.GetByText("Click me").ClickAsync();
await page.WaitForURL("**/login");
```
+## Back/Forward Cache (BFCache)
+
+Modern browsers utilize a Back/Forward Cache (BFCache) to instantly load a page when a user navigates back or forward. This is achieved by freezing the page's DOM and JavaScript heap in memory, and thawing it upon return.
+
+By default, Playwright disables the BFCache across all browsers to ensure consistent, clean testing environments.
+
+Even if you explicitly enable BFCache, **testing BFCache restorations is not supported**. Because a BFCache restore skips the network fetch phase, the browser does not fire standard navigation lifecycle events (such as `commit`, `domcontentloaded`, or `load`). Playwright's internal `Page` state heavily relies on these network-level events to stay synchronized.
+
+Consequently, triggering a BFCache restore (e.g., via `page.goBack()`) will bypass Playwright's lifecycle tracking, resulting in timeouts and a completely desynchronized `Page` object where subsequent interactions will fail.
+
## Navigation events
Playwright splits the process of showing a new document in a page into **navigation** and **loading**.
diff --git a/packages/playwright-client/types/types.d.ts b/packages/playwright-client/types/types.d.ts
index 0b3c58906b..39d79b3c53 100644
--- a/packages/playwright-client/types/types.d.ts
+++ b/packages/playwright-client/types/types.d.ts
@@ -3291,6 +3291,13 @@ export interface Page {
* the last redirect. If cannot go back, returns `null`.
*
* Navigate to the previous page in history.
+ *
+ * **NOTE** **Testing Back/Forward Cache (BFCache) is not supported.** By default, Playwright disables the
+ * Back/Forward Cache across all browsers. Even if explicitly enabled, Playwright's internal state relies on
+ * network-level navigation events. Because BFCache restores unfreeze the DOM without firing these events, using
+ * `page.goBack()` or `page.goForward()` to trigger a BFCache restore will result in timeouts and a desynchronized
+ * `Page` state.
+ *
* @param options
*/
goBack(options?: {
@@ -3332,6 +3339,13 @@ export interface Page {
* the last redirect. If cannot go forward, returns `null`.
*
* Navigate to the next page in history.
+ *
+ * **NOTE** **Testing Back/Forward Cache (BFCache) is not supported.** By default, Playwright disables the
+ * Back/Forward Cache across all browsers. Even if explicitly enabled, Playwright's internal state relies on
+ * network-level navigation events. Because BFCache restores unfreeze the DOM without firing these events, using
+ * `page.goBack()` or `page.goForward()` to trigger a BFCache restore will result in timeouts and a desynchronized
+ * `Page` state.
+ *
* @param options
*/
goForward(options?: {
diff --git a/packages/playwright-core/types/types.d.ts b/packages/playwright-core/types/types.d.ts
index 0b3c58906b..39d79b3c53 100644
--- a/packages/playwright-core/types/types.d.ts
+++ b/packages/playwright-core/types/types.d.ts
@@ -3291,6 +3291,13 @@ export interface Page {
* the last redirect. If cannot go back, returns `null`.
*
* Navigate to the previous page in history.
+ *
+ * **NOTE** **Testing Back/Forward Cache (BFCache) is not supported.** By default, Playwright disables the
+ * Back/Forward Cache across all browsers. Even if explicitly enabled, Playwright's internal state relies on
+ * network-level navigation events. Because BFCache restores unfreeze the DOM without firing these events, using
+ * `page.goBack()` or `page.goForward()` to trigger a BFCache restore will result in timeouts and a desynchronized
+ * `Page` state.
+ *
* @param options
*/
goBack(options?: {
@@ -3332,6 +3339,13 @@ export interface Page {
* the last redirect. If cannot go forward, returns `null`.
*
* Navigate to the next page in history.
+ *
+ * **NOTE** **Testing Back/Forward Cache (BFCache) is not supported.** By default, Playwright disables the
+ * Back/Forward Cache across all browsers. Even if explicitly enabled, Playwright's internal state relies on
+ * network-level navigation events. Because BFCache restores unfreeze the DOM without firing these events, using
+ * `page.goBack()` or `page.goForward()` to trigger a BFCache restore will result in timeouts and a desynchronized
+ * `Page` state.
+ *
* @param options
*/
goForward(options?: {