1 files changed, 140 insertions, 0 deletions
diff --git a/testing/web-platform/tests/workers/README.md b/testing/web-platform/tests/workers/README.md
new file mode 100644
index 0000000000..58ee7cca1a
--- /dev/null
+++ b/testing/web-platform/tests/workers/README.md
@@ -0,0 +1,140 @@
+# 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).
+
+Note that because workers are defined in the HTML Standard, the idlharness.js
+tests are in [/html/dom]([/html/dom) instead of here.
+
+## 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.