How to write back-forward cache tests

In the back-forward cache tests, the main test HTML usually:

1. ) { test.style.setProperty("text-orientation", "upright"); docum

because less isolated Windows (e.g. iframes and window.open() without noopener option) are often not eligible for back-forward cache (e.g. in Chromium).

1. ) { test.style.setProperty("text-orientation", "upright"); docum

RemoteContext.execute_script() by /common/dispatcher. Follow the semantics and guideline described there.

Back-forward cache specific helpers are in:

• resources/executor.html:

The BFCache-specific executor and contains helpers for executors.

• resources/helper.sub.js:

Helpers for main test HTMLs.

We must ensure that injected scripts are evaluated only after page load (more precisely, the first pageshow event) and not during navigation, to prevent unexpected interference between injected scripts, in-flight fetch requests behind RemoteContext.execute_script(), navigation and back-forward cache. To ensure this,

• Call await remoteContext.execute_script(waitForPageShow) before any

other scripts are injected to the remote context, and

• Call prepareNavigation(callback) synchronously from the script injected

by RemoteContext.execute_script(), and trigger navigation on or after the callback is called.

In typical A-B-A scenarios (where we navigate from Page A to Page B and then navigate back to Page A, assuming Page A is (or isn't) in BFCache),

• Call prepareNavigation() on the executor, and then navigate to B, and then

navigate back to Page A.

• Call assert_bfcached() or assert_not_bfcached() on the main test HTML, to

check the BFCache status. This is important to do to ensure the test would not fail normally and instead result in PRECONDITION_FAILED if the page is unexpectedly bfcached/not bfcached.

• Check other test expectations on the main test HTML,

as in events.html and runEventTest() in resources/helper.sub.js.

Asserting PRECONDITION_FAILED for unexpected BFCache eligibility

Browsers are not actually obliged to put pages in BFCache after navigations, so BFCache WPTs shouldn't result in FAILED if it expects a certain case to be supported by BFCache. But, it is still useful to test those cases in the browsers that do support BFCache for that case.

To distinguish genuine failures from just not using BFCache, we use assert_bfcached() and assert_not_bfcached() which result in PRECONDITION_FAILED rather than FAILED. that should be put in the expectations for the failing tests (instead of marking it as FAILED or skipping the test). This means if the test starts passing (e.g. if we start BFCaching in the case being tested), we will notice that the output changed from PRECONDITION_FAILED to PASS.