Playwright is a framework for Web Testing and Automation. It allows testing Chromium, Firefox and WebKit with a single API.
TypeScript automationchromechromiume2e-testingelectronend-to-end-testingfirefoxjavascriptplaywrighttesttest-automationtestingtesting-toolswebwebkit
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.mdindex 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.48diff --git a/docs/src/navigations.md b/docs/src/navigations.mdindex 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 eventsPlaywright 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.tsindex 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.tsindex 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?: {