Test Utils

Living Standard — Last Updated

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


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

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


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.


Terms defined by this specification

Terms defined by reference


Normative References

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

IDL Index

interface TestUtils {
  Promise<undefined> gc();

partial interface mixin WindowOrWorkerGlobalScope {
  readonly attribute TestUtils testUtils;