Bug 1523562 [wpt PR 14829] - Add worker WPT test writing guide and examples, a=testonly

Automatic update from web-platform-tests
Add worker WPT test writing guide and examples

Change-Id: I5de23aad37379fdbf3e0f5934b024b7905a5b7d5
Reviewed-on: https://chromium-review.googlesource.com/c/1406165
Reviewed-by: Hiroki Nakagawa <nhiroki@chromium.org>
Reviewed-by: Matt Falkenhagen <falken@chromium.org>
Commit-Queue: Hiroshige Hayashizaki <hiroshige@chromium.org>
Cr-Commit-Position: refs/heads/master@{#623988}

--

wpt-commits: 4fb2d9c4d14af3edc62f6c6157c9152d07306da0
wpt-pr: 14829

testing/web-platform/tests/workers/README.md

@@ -1,2 +1,137 @@
+# Worker WPT tests
+
 These are the workers (`Worker`, `SharedWorker`) tests for the
 [Web workers chapter of the HTML Standard](https://html.spec.whatwg.org/multipage/workers.html).
+
+See also
+[testharness.js API > Web Workers](https://web-platform-tests.org/writing-tests/testharness-api.html#web-workers).
+
+## Writing `*.any.js`
+
+The easiest and most recommended way to write tests for workers
+is to create .any.js-style tests.
+
+Official doc:
+[WPT > File Name Flags > Test Features](https://web-platform-tests.org/writing-tests/file-names.html#test-features).
+
+- Standard `testharness.js`-style can be used (and is enforced).
+- The same test can be run on window and many types of workers.
+- All glue code are automatically generated.
+- No need to care about how to create and communicate with each type of workers,
+  thanks to `fetch_tests_from_worker` in `testharness.js`.
+
+Converting existing tests into `.any.js`-style also has benefits:
+
+- Multiple tests can be merged into one.
+- Tests written for window can be run on workers
+  with a very low development cost.
+
+### How to write tests
+
+If you write `testharness.js`-based tests in `foo.any.js` and
+specify types of workers to be tested,
+the test can run on any of dedicated, shared and service workers.
+
+See `examples/general.any.js` for example.
+
+Even for testing specific features in a specific type of workers
+(e.g. shared worker's `onconnect`), `.any.js`-style tests can be used.
+
+See `examples/onconnect.any.js` for example.
+
+### How to debug tests
+
+Whether each individual test passed or failed,
+and its assertion failures (if any) are all reported in the final results.
+
+`console.log()` might not appear in the test results and
+thus might not be useful for printf debugging.
+For example, in Chromium, this message
+
+- Appears (in stderr) on a window or a dedicated worker, but
+- Does NOT appear on a shared worker or a service worker.
+
+### How it works
+
+`.any.js`-style tests use
+`fetch_tests_from_worker` functionality of `testharness.js`.
+
+The WPT test server generates necessary glue code
+(including generated Document HTML and worker top-level scripts).
+See
+[serve.py](https://github.com/web-platform-tests/wpt/blob/master/tools/serve/serve.py)
+for the actual glue code.
+
+Note that `.any.js` file is not the worker top-level script,
+and currently we cannot set response headers to the worker top-level script,
+e.g. to set Referrer Policy of the workers.
+
+## Writing `*.worker.js`
+
+Similar to `.any.js`, you can also write `.worker.js`
+for tests only for dedicated workers.
+Almost the same as `.any.js`, except for the things listed below.
+
+Official doc:
+[WPT > File Name Flags > Test Features](https://web-platform-tests.org/writing-tests/file-names.html#test-features).
+
+### How to write tests
+
+You have to write two things manually (which is generated in `.any.js` tests):
+
+- `importScripts("/resources/testharness.js");` at the beginning.
+- `done();` at the bottom.
+
+Note: Even if you write `async_test()` or `promise_test()`,
+this global `done()` is always needed
+(this is different from async_test's `done()`)
+for dedicated workers and shared workers.
+See official doc:
+[testharness.js API > Determining when all tests are complete](https://web-platform-tests.org/writing-tests/testharness-api.html#determining-when-all-tests-are-complete).
+
+See `examples/general.worker.js` for example.
+
+### How it works
+
+`.worker.js`-style tests also use
+`fetch_tests_from_worker` functionality of `testharness.js`.
+
+The WPT test server generates glue code in Document HTML-side,
+but not for worker top-level scripts.
+This is why you have to manually write `importScripts()` etc.
+See
+[serve.py](https://github.com/web-platform-tests/wpt/blob/master/tools/serve/serve.py)
+for the actual glue code.
+
+Unlike `*.any.js` cases, the `*.worker.js` is the worker top-level script.
+
+## Using `fetch_tests_from_worker`
+
+If you need more flexibility,
+writing tests using `fetch_tests_from_worker` is the way to go.
+For example, when
+
+- Additional processing is needed on the parent Document.
+- Workers should be created in a specific way.
+- You are writing non-WPT tests using `testharness.js`.
+
+You have to write the main HTMLs and the worker scripts,
+but most of the glue code needed for running tests on workers
+are provided by `fetch_tests_from_worker`.
+
+### How to write tests
+
+See
+
+- `examples/fetch_tests_from_worker.html` and
+  `examples/fetch_tests_from_worker.js`.
+
+## Writing the whole tests manually
+
+If `fetch_tests_from_worker` isn't suitable for your specific case
+(which should be rare but might be still possible),
+you have to write the whole tests,
+including the main Document HTML, worker scripts,
+and message passing code between them.
+
+TODO: Supply the templates for writing this kind of tests.

testing/web-platform/tests/workers/examples/fetch_tests_from_worker.html

@@ -0,0 +1,21 @@
+<!doctype html>
+<!--
+  This file is an example of a hand-written test using
+  fetch_tests_from_worker().
+  Unlike *.any.js or *.worker.js tests, fetch_tests_from_worker.html/js files
+  are manually written and no generated glue code are involved.
+-->
+<script src="/resources/testharness.js"></script>
+<script src="/resources/testharnessreport.js"></script>
+<script>
+fetch_tests_from_worker(new Worker("fetch_tests_from_worker.js"));
+
+// If you want to test on SharedWorker,
+// fetch_tests_from_worker(new SharedWorker("fetch_tests_from_worker.js"));
+
+// See ServiceWorkersHandler in
+// https://github.com/web-platform-tests/wpt/blob/master/tools/serve/serve.py
+// for the generated snippet used in .any.js for service workers.
+// Note: when testing service workers, also add ".https." file flag in the
+// main HTML's file name to run the test on HTTPS.
+</script>

testing/web-platform/tests/workers/examples/fetch_tests_from_worker.js

@@ -0,0 +1,28 @@
+// This file is an example of a hand-written test using
+// fetch_tests_from_worker().
+// Unlike *.any.js or *.worker.js tests, fetch_tests_from_worker.html/js files
+// are manually written and no generated glue code are involved.
+
+// fetch_tests_from_worker() requires testharness.js both on the parent
+// document and on the worker.
+importScripts("/resources/testharness.js");
+
+// ============================================================================
+
+// Test body.
+test(() => {
+    assert_equals(1, 1, "1 == 1");
+  },
+  "Test that should pass"
+);
+
+// ============================================================================
+
+// `done()` is always needed at the bottom for dedicated workers and shared
+// workers, even if you write `async_test()` or `promise_test()`.
+// `async_test()` and `promise_test()` called before this `done()`
+// will continue and assertions/failures after this `done()` are not ignored.
+// See
+// https://web-platform-tests.org/writing-tests/testharness-api.html#determining-when-all-tests-are-complete
+// for details.
+done();

testing/web-platform/tests/workers/examples/general.any.js

@@ -0,0 +1,34 @@
+// META: global=!default,worker
+
+// See
+// https://web-platform-tests.org/writing-tests/testharness.html#multi-global-tests
+// for how to specify in which global scopes to run this tests,
+// how to specify additional scripts needed, etc.
+
+// testharness.js is imported (via importScripts()) by generated glue code by
+// WPT server.
+// See AnyWorkerHandler in
+// https://github.com/web-platform-tests/wpt/blob/master/tools/serve/serve.py.
+
+// ============================================================================
+
+// Test body.
+// .any.js tests are always testharness.js-based.
+test(() => {
+    assert_equals(1, 1, "1 == 1");
+  },
+  "Test that should pass"
+);
+
+test(() => {
+    // This file is "general.any.js" but the worker top-level script is
+    // "general.any.worker.js", which is generated by the WPT server.
+    assert_equals(location.pathname, "/workers/examples/general.any.worker.js");
+  },
+  "Worker top-level script is a generated script."
+);
+
+// done() is NOT needed in .any.js tests, as it is called by generated
+// glue code by the WPT server.
+// See AnyWorkerHandler in
+// https://github.com/web-platform-tests/wpt/blob/master/tools/serve/serve.py.

testing/web-platform/tests/workers/examples/general.worker.js

@@ -0,0 +1,35 @@
+// This file is an example of a test using *.worker.js mechanism.
+// The parent document that calls fetch_tests_from_worker() is auto-generated
+// but there are no generated code in the worker side.
+
+// fetch_tests_from_worker() requires testharness.js both on the parent
+// document and on the worker.
+importScripts("/resources/testharness.js");
+
+// ============================================================================
+
+// Test body.
+test(() => {
+    assert_equals(1, 1, "1 == 1");
+  },
+  "Test that should pass"
+);
+
+test(() => {
+    // This file is "general.worker.js" and this file itself is the worker
+    // top-level script (which is different from the .any.js case).
+    assert_equals(location.pathname, "/workers/examples/general.worker.js");
+  },
+  "Worker top-level script is the .worker.js file itself."
+);
+
+// ============================================================================
+
+// `done()` is always needed at the bottom for dedicated workers and shared
+// workers, even if you write `async_test()` or `promise_test()`.
+// `async_test()` and `promise_test()` called before this `done()`
+// will continue and assertions/failures after this `done()` are not ignored.
+// See
+// https://web-platform-tests.org/writing-tests/testharness-api.html#determining-when-all-tests-are-complete
+// for details.
+done();

testing/web-platform/tests/workers/examples/onconnect.any.js

@@ -0,0 +1,4 @@
+// META: global=!default,sharedworker
+const t = async_test("onconnect is called");
+onconnect = t.step_func_done((event) => {
+});