diff options
author | Daniel Baumann <daniel.baumann@progress-linux.org> | 2024-04-19 00:47:55 +0000 |
---|---|---|
committer | Daniel Baumann <daniel.baumann@progress-linux.org> | 2024-04-19 00:47:55 +0000 |
commit | 26a029d407be480d791972afb5975cf62c9360a6 (patch) | |
tree | f435a8308119effd964b339f76abb83a57c29483 /testing/web-platform/tests/docs/writing-tests/testharness.md | |
parent | Initial commit. (diff) | |
download | firefox-26a029d407be480d791972afb5975cf62c9360a6.tar.xz firefox-26a029d407be480d791972afb5975cf62c9360a6.zip |
Adding upstream version 124.0.1.upstream/124.0.1
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to 'testing/web-platform/tests/docs/writing-tests/testharness.md')
-rw-r--r-- | testing/web-platform/tests/docs/writing-tests/testharness.md | 289 |
1 files changed, 289 insertions, 0 deletions
diff --git a/testing/web-platform/tests/docs/writing-tests/testharness.md b/testing/web-platform/tests/docs/writing-tests/testharness.md new file mode 100644 index 0000000000..e426e37f22 --- /dev/null +++ b/testing/web-platform/tests/docs/writing-tests/testharness.md @@ -0,0 +1,289 @@ +# JavaScript Tests (testharness.js) + +JavaScript tests are the correct type of test to write in any +situation where you are not specifically interested in the rendering +of a page, and where human interaction isn't required; these tests are +written in JavaScript using a framework called `testharness.js`. + +A high-level overview is provided below and more information can be found here: + + * [testharness.js Documentation](testharness-api.md) — An introduction + to the library and a detailed API reference. [The tutorial on writing a + testharness.js test](testharness-tutorial) provides a concise guide to writing + a test — a good place to start for newcomers to the project. + + * [testdriver.js Automation](testdriver.md) — Automating end user actions, such as moving or + clicking a mouse. See also the + [testdriver.js extension tutorial](testdriver-extension-tutorial.md) for adding new commands. + + * [idlharness.js](idlharness.md) — A library for testing + IDL interfaces using `testharness.js`. + + * [Message Channels](channels.md) - A way to communicate between + different globals, including window globals not in the same + browsing context group. + + * [Server features](server-features.md) - Advanced testing features + that are commonly used with JavaScript tests. + +See also the [general guidelines](general-guidelines.md) for all test types. + +## Window tests + +### Without HTML boilerplate (`.window.js`) + +Create a JavaScript file whose filename ends in `.window.js` to have the necessary HTML boilerplate +generated for you at `.window.html`. I.e., for `test.window.js` the server will ensure +`test.window.html` is available. + +In this JavaScript file you can place one or more tests, as follows: +```js +test(() => { + // Place assertions and logic here + assert_equals(document.characterSet, "UTF-8"); +}, "Ensure HTML boilerplate uses UTF-8"); // This is the title of the test +``` + +If you only need to test a [single thing](testharness-api.html#single-page-tests), you could also use: +```js +// META: title=Ensure HTML boilerplate uses UTF-8 +setup({ single_test: true }); +assert_equals(document.characterSet, "UTF-8"); +done(); +``` + +See [asynchronous (`async_test()`)](testharness-api.html#asynchronous-tests) and +[promise tests (`promise_test()`)](testharness-api.html#promise-tests) for more involved setups. + +### With HTML boilerplate + +You need to be a bit more explicit and include the `testharness.js` framework directly as well as an +additional file used by implementations: + +```html +<!doctype html> +<meta charset=utf-8> +<script src="/resources/testharness.js"></script> +<script src="/resources/testharnessreport.js"></script> +<body> + <script> + test(() => { + assert_equals(document.characterSet, "UTF-8"); + }, "Ensure UTF-8 declaration is observed"); + </script> +``` + +Here too you could avoid the wrapper `test()` function: + +```html +<!doctype html> +<meta charset=utf-8> +<title>Ensure UTF-8 declaration is observed</title> +<script src="/resources/testharness.js"></script> +<script src="/resources/testharnessreport.js"></script> +<body> + <script> + setup({ single_test: true }); + assert_equals(document.characterSet, "UTF-8"); + done(); + </script> +``` + +In this case the test title is taken from the `title` element. + +## Dedicated worker tests (`.worker.js`) + +Create a JavaScript file that imports `testharness.js` and whose filename ends in `.worker.js` to +have the necessary HTML boilerplate generated for you at `.worker.html`. + +For example, one could write a test for the `FileReaderSync` API by +creating a `FileAPI/FileReaderSync.worker.js` as follows: + +```js +importScripts("/resources/testharness.js"); +test(function () { + const blob = new Blob(["Hello"]); + const fr = new FileReaderSync(); + assert_equals(fr.readAsText(blob), "Hello"); +}, "FileReaderSync#readAsText."); +done(); +``` + +This test could then be run from `FileAPI/FileReaderSync.worker.html`. + +(Removing the need for `importScripts()` and `done()` is tracked in +[issue #11529](https://github.com/web-platform-tests/wpt/issues/11529).) + +## Tests for other or multiple globals (`.any.js`) + +Tests for features that exist in multiple global scopes can be written in a way +that they are automatically run in several scopes. In this case, the test is a +JavaScript file with extension `.any.js`, which can use all the usual APIs. + +By default, the test runs in a window scope and a dedicated worker scope. + +For example, one could write a test for the `Blob` constructor by +creating a `FileAPI/Blob-constructor.any.js` as follows: + +```js +test(function () { + const blob = new Blob(); + assert_equals(blob.size, 0); + assert_equals(blob.type, ""); + assert_false(blob.isClosed); +}, "The Blob constructor."); +``` + +This test could then be run from `FileAPI/Blob-constructor.any.worker.html` as well +as `FileAPI/Blob-constructor.any.html`. + +It is possible to customize the set of scopes with a metadata comment, such as + +``` +// META: global=sharedworker +// ==> would run in the shared worker scope +// META: global=window,serviceworker +// ==> would only run in the window and service worker scope +// META: global=dedicatedworker +// ==> would run in the default dedicated worker scope +// META: global=dedicatedworker-module +// ==> would run in the dedicated worker scope as a module +// META: global=worker +// ==> would run in the dedicated, shared, and service worker scopes +``` + +For a test file <code><var>x</var>.any.js</code>, the available scope keywords +are: + +* `window` (default): to be run at <code><var>x</var>.any.html</code> +* `dedicatedworker` (default): to be run at <code><var>x</var>.any.worker.html</code> +* `dedicatedworker-module` to be run at <code><var>x</var>.any.worker-module.html</code> +* `serviceworker`: to be run at <code><var>x</var>.any.serviceworker.html</code> (`.https` is + implied) +* `serviceworker-module`: to be run at <code><var>x</var>.any.serviceworker-module.html</code> + (`.https` is implied) +* `sharedworker`: to be run at <code><var>x</var>.any.sharedworker.html</code> +* `sharedworker-module`: to be run at <code><var>x</var>.any.sharedworker-module.html</code> +* `jsshell`: to be run in a JavaScript shell, without access to the DOM + (currently only supported in SpiderMonkey, and skipped in wptrunner) +* `worker`: shorthand for the dedicated, shared, and service worker scopes +* `shadowrealm`: runs the test code in a + [ShadowRealm](https://github.com/tc39/proposal-shadowrealm) context hosted in + an ordinary Window context; to be run at <code><var>x</var>.any.shadowrealm.html</code> + +To check what scope your test is run from, you can use the following methods that will +be made available by the framework: + + self.GLOBAL.isWindow() + self.GLOBAL.isWorker() + self.GLOBAL.isShadowRealm() + +Although [the global `done()` function must be explicitly invoked for most +dedicated worker tests and shared worker +tests](testharness-api.html#determining-when-all-tests-are-complete), it is +automatically invoked for tests defined using the "multi-global" pattern. + +## Other features of `.window.js`, `.worker.js` and `.any.js` + +### Specifying a test title + +Use `// META: title=This is the title of the test` at the beginning of the resource. + +### Including other JavaScript files + +Use `// META: script=link/to/resource.js` at the beginning of the resource. For example, + +``` +// META: script=/common/utils.js +// META: script=resources/utils.js +``` + +can be used to include both the global and a local `utils.js` in a test. + +In window environments, the script will be included using a classic `<script>` tag. In classic +worker environments, the script will be imported using `importScripts()`. In module worker +environments, the script will be imported using a static `import`. + +wptserve generates markup with `/resources/testharness.js` and `/resources/testharnessreport.js` +included automatically, so there's no need to include those scripts from the `.js` test file. + +### Specifying a timeout of long + +Use `// META: timeout=long` at the beginning of the resource. + +### Specifying test [variants](#variants) + +Use `// META: variant=url-suffix` at the beginning of the resource. For example, + +``` +// META: variant=?default +// META: variant=?wss +``` + +## Variants + +A test file can have multiple variants by including `meta` elements, +for example: + +```html +<meta name="variant" content="?default"> +<meta name="variant" content="?wss"> +``` + +Test runners will execute the test for each variant specified, appending the corresponding content +attribute value to the URL of the test as they do so. + +`/common/subset-tests.js` and `/common/subset-tests-by-key.js` are two utility scripts that work +well together with variants, allowing a test to be split up into subtests in cases when there are +otherwise too many tests to complete inside the timeout. For example: + +```html +<!doctype html> +<title>Testing variants</title> +<meta name="variant" content="?1-1000"> +<meta name="variant" content="?1001-2000"> +<meta name="variant" content="?2001-last"> +<script src="/resources/testharness.js"></script> +<script src="/resources/testharnessreport.js"></script> +<script src="/common/subset-tests.js"></script> +<script> + const tests = [ + { fn: t => { ... }, name: "..." }, + ... lots of tests ... + ]; + for (const test of tests) { + subsetTest(async_test, test.fn, test.name); + } +</script> +``` + +With `subsetTestByKey`, the key is given as the first argument, and the +query string can include or exclude a key (which will be matched as a regular +expression). + +```html +<!doctype html> +<title>Testing variants by key</title> +<meta name="variant" content="?include=Foo"> +<meta name="variant" content="?include=Bar"> +<meta name="variant" content="?exclude=(Foo|Bar)"> +<script src="/resources/testharness.js"></script> +<script src="/resources/testharnessreport.js"></script> +<script src="/common/subset-tests-by-key.js"></script> +<script> + subsetTestByKey("Foo", async_test, () => { ... }, "Testing foo"); + ... +</script> +``` + +## Table of Contents + +```eval_rst +.. toctree:: + :maxdepth: 1 + + testharness-api + testdriver + testdriver-extension-tutorial + idlharness +``` |