index.bs

<pre class='metadata'>
Group: WHATWG
H1: Test Utils
Shortname: testutils
Text Macro: TWITTER testutils
Text Macro: LATESTRD 2022-03
Abstract: This document defines APIs that provide additional testing functionality in browsers
</pre>

Introduction {#intro}
=====================

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|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.

Infrastructure {#infrastructure}
================================

<p>This specification depends on the Infra Standard. [[!INFRA]]

<p>This specification uses terminology from the Web IDL standard. [[!WEBIDL]]

Availability {#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.

The TestUtils Namespace {#the-testutils-namespace}
============================================

<xmp class=idl>
[Exposed=(Window,Worker)]
namespace TestUtils {
  [NewObject] Promise<undefined> gc();
};
</xmp>

The {{TestUtils/gc()}} method must run these steps:

 1. Let |p| be a new promise.

 2. Run the following [=in parallel=]:

    2.1 Run <a>implementation-defined</a> steps to perform a garbage collection
        covering at least the <a spec=html>entry Realm</a>.

    2.2 Resolve |p|.


<h2 class=no-num id=acknowledgements>Acknowledgments</h2>

Thanks to the following people who have contributed to the
Test Utils standard:

Kagami Sascha Rosylight

You are awesome!

This standard is written by <a href=https://hoppipolla.co.uk>James Graham</a>
(<a href=https://www.mozilla.org/>Mozilla</a>,
<a href=mailto:james@hoppipolla.co.uk>james@hoppipolla.co.uk</a>).