Prerender WPT tests

This directory contains Web Platform Tests for Prerendering Revamped.

These tests are generally intended to be upstreamed to the Web Platform Tests repository (i.e., moved from wpt_internal to external/wpt). There are various reasons they cannot be upstreamed today. The main blocker is https://crbug.com/1226460.

In general, these tests should follow Chromium's web tests guidelines and web-platform-tests guidelines. This document describes additional conventions for these particular tests.

Describe requirements for upstreaming the test

All tests should have a comment near the top of the file that explains what must change before the test can be upstreamed. Typical reasons include:

• The need for a WebDriver API to get a permission. See the later section for details.
• The tests expects behaviors that are not yet described in the specification.

Good:

<!--
This file cannot be upstreamed to WPT until:
* internals.setPermission() usage is replaced with a WebDriver API
* The specification describes the loading of cross-origin iframes. The test
  expects that they are not loaded during prerendering.
-->

Use the long timeout

These tests tend to be slow. The probable reason for the slowness is that they do several navigations, for the main test page, the "initial" page that triggers prerendering, the prerendered page, and the activation.

All tests should use the "long" WPT test harness timeout.

Good:

<meta name="timeout" content="long">

Use internals.setPermission() to test permission-based APIs

For tests that use permission-gated APIs, use internals.setPermission() to grant permission to the API before using it.

Good:

// Grant the permission here to make a more discerning test because
// navigator.wakeLock.request() waits until the permission is granted, which
// may be deferred during prerendering, so the test would trivially pass without
// the permission.
await internals.setPermission({name: 'screen-wake-lock'}, 'granted',
                              location.origin, location.origin);

Propagate assert_* results up to the promise_test

It is often convenient to use assert_equals and other asserts outside of the test itself. For example, the triggering page or prerendering page may want to do asserts. However, if these asserts are just used without messaging the main test page, the promise_test does not detect assertion failures. Instead, the test will only have stderr output from the console, and it may timeout instead of cleanly failing.

To avoid this, enclose the asserts in try/catch blocks, and message the error to the main test page, so that the promise_test can detect the failure.

Good:

In my-test.html (the test page):

const channel = new BroadcastChannel('test-channel');

const gotMessage = new Promise(resolve => {
  channel.addEventListener('message', e => {
    resolve(e.data);
  }, {once: true});
});

const msg = await gotMessage;
assert_equals(msg, 'PASS');

In resources/my-test.html (the prerendered page):

async function main() {
  assert_equals('a', 'b');
}

// Run main() then message the test page with the result.
const testChannel = new BroadcastChannel('test-channel');
main().then(() => {
  testChannel.postMessage('PASS');
}).catch((e) => {
  testChannel.postMessage('FAIL: ' + e);
});

This test fails cleanly with output like:

FAIL assert_equals: expected "PASS" but got "FAIL: Error: assert_equals:
expected 'b' but got 'a'"

Bad:

In resources/my-test.html (the prerendered page):

assert_equals('a', 'b');
const testChannel = new BroadcastChannel('test-channel');
testChannel.postMessage('PASS');

This test might timeout instead of fail by assertion failure.

Wrap lines at 80 columns

This is the convention for most Chromium/WPT style tests. Note that git cl format [--js] does not reformat js code in .html files.