Browser Testing API

Living Standard — Last Updated

Participate:
GitHub whatwg/browser-test (new issue, open issues)
IRC: #whatwg on Freenode
Commits:
GitHub whatwg/browser-test/commits
Snapshot as of this commit
@_
Tests:
web-platform-tests browser-test/ (ongoing work)
Editor:
James Graham (Mozilla)

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 behaviour 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 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<void> 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

Copyright © WHATWG (Apple, Google, Mozilla, Microsoft). This work is licensed under a Creative Commons Attribution 4.0 International License.

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<void> gc();
};

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