Test Utils

Living Standard — Last Updated

Participate:
GitHub whatwg/testutils (new issue, open issues)
Chat on Matrix
Commits:
GitHub whatwg/testutils/commits
Snapshot as of this commit
@testutils
Tests:
web-platform-tests testutils/ (ongoing work)

Abstract

This document defines APIs that provide additional testing functionality in browsers

1. Introduction

Testing browsers often requires use of specialised API surface that is not suitable for exposing to web authors, for example because it could undermine platform invariants, or allow behavior that could put users at risk. This can make writing cross-browser tests difficult because each implementation of the web platform will have its own approach to defining such test APIs. The WebDriver standard provides some of these APIs, with a focus on automated testing of web applications. However for testing of browser implementations themselves, there are some additional APIs that don’t fit into the WebDriver framework, but are nevertheless important to testing.

This specification defines additional in-browser APIs for use in tests, but which are not suitable to enable for end users. The primary client of these APIs is the web-platform-tests testsuite.

2. Infrastructure

This specification depends on the Infra Standard. [INFRA]

This specification uses terminology from the Web IDL standard. [WEBIDL]

3. Availability

The interfaces defined in this specification must not be enabled in the default shipping configuration of user agents. They must only be enabled in testing configurations for example with special build flags, or when a specific non-default preference is set.

4. The TestUtils Object

[Exposed=Window,Worker]
interface TestUtils {
  Promise<undefined> gc();
};

partial interface mixin WindowOrWorkerGlobalScope {
  readonly attribute TestUtils testUtils;
};

The `gc()` method must run these steps:

  1. Let p be a new promise.

  2. Run the following in parallel:

    2.1 Run implemenation defined steps to perform a garbage collection covering at least the entry Realm.

    2.2 Resolve p

Acknowledgments

This standard is written by James Graham (Mozilla, james@hoppipolla.co.uk).

Intellectual property rights

Copyright © WHATWG (Apple, Google, Mozilla, Microsoft). This work is licensed under a Creative Commons Attribution 4.0 International License. To the extent portions of it are incorporated into source code, such portions in the source code are licensed under the BSD 3-Clause License instead.

Index

Terms defined by this specification

Terms defined by reference

References

Normative References

[HTML]
Anne van Kesteren; et al. HTML Standard. Living Standard. URL: https://html.spec.whatwg.org/multipage/
[INFRA]
Anne van Kesteren; Domenic Denicola. Infra Standard. Living Standard. URL: https://infra.spec.whatwg.org/
[WEBDRIVER]
Simon Stewart; David Burns. WebDriver. URL: https://w3c.github.io/webdriver/
[WEBIDL]
Boris Zbarsky. Web IDL. URL: https://heycam.github.io/webidl/

IDL Index

[Exposed=Window,Worker]
interface TestUtils {
  Promise<undefined> gc();
};

partial interface mixin WindowOrWorkerGlobalScope {
  readonly attribute TestUtils testUtils;
};