Bikeshed Documentation

Living Standard,

12. Testing Integration With WPT

When writing specifications for the open web, the canonical way to test new features and ensure interoperability is to contribute the testsuite to the Web Platform Tests project. Bikeshed has some useful tools to interact with WPT information.

12.1. Annotating Specs with Tests: the wpt element

When writing tests, you can sometimes link to the section of the spec that you’re testing, to make it easier to review. But when you’re actually reading (or updating!) the spec, you can’t tell what sections are tested or untested, or what tests might need to be updated due to a change you’re making. The wpt element lets you easily link to your WPT testcases inline, right next to the text they’re testing, and helps make sure that the testsuite and the spec are kept in-sync.

The wpt element is a block-level element for parsing purposes; place it after or between paragraphs/etc. The contents of the element are line-based: each line contains a single test path (the path under the WPT repo, so not including the domain or the /web-platforms-tests/wpt/) pointing to the test covering some nearby text.

For example: 
Implementations must FOO whenever they would also BAR.

<wpt>
  /foo-spec/foo-whenever-you-bar.html
  /foo-spec/no-foo-when-no-bar.html
</wpt>

If all or most of your tests have a common path prefix, you can specify it in WPT Path Prefix metadata, and then leave it off of all the individual test lines. This also triggers Bikeshed to complain if it knows of any tests under that prefix that don’t show up in your spec.

An explicit pathprefix attribute can also provide the path prefix for a single wpt block, overriding the metadata if specified.

If the preceding example used WPT Path Prefix, the wpt element could be shorter: 
<pre class=metadata>
WPT Display: open
WPT Path Prefix: /foo-spec/
</pre>

...

Implementations must FOO whenever they would also BAR.

<wpt>
  foo-whenever-you-bar.html
  no-foo-when-no-bar.html
</wpt>

Alternately, the path prefix could be indicated just on the one block:

Implementations must FOO whenever they would also BAR.

<wpt pathprefix="/foo-spec/">
  foo-whenever-you-bar.html
  no-foo-when-no-bar.html
</wpt>

For debugging purposes, a single <wpt-rest> element can be used in a spec, which will act like a wpt element containing all the tests under the current path prefix that aren’t already specified in a wpt element. As this defeats Bikeshed’s ability to tell you when you’re missing any tests, Bikeshed will emit a warning as long as a wpt-rest element is in use.

Bikeshed’s knowledge of valid tests allows some useful checks:

By default, wpt elements don’t display in the output document; they’re intended to annotate the source file to help with spec authoring, and trigger Bikeshed’s checks. If you want to produce a test-annotated version of the output, specify the WPT Display metadata with the value "open" or "closed"; all of the wpt elements will become usefully-formatted lists of their contained tests, with links to wpt.fyi, the live test on w3c-test.org, and the source code on GitHub. The difference between "open" and "closed" is that with the former, all wpt elements are initially displayed in a collapsed state to avoid getting in the way of reading the document, while "open" causes them to be expanded initially. In either case, the use can interactively collapse or expand each element.

When WPT Display: open is set, the wpt element turns into a "TESTS" block.
When WPT Display: closed is set, the wpt element also turns into a "TESTS" block, but it is initially collapsed.

Note: For compatibility with earlier versions of Bikshed, "inline" is accepted as a synonym of "open".

When the hidden attribute is set on the wpt element, Bikeshed will take the tests listed in that element into account, but exclude them from the output, even when producing a test-annotated version.

Note: This can be useful when tests for all versions or levels of a single specification are stored together under a single directory. Using WPT Path Prefix would cause Bikeshed to complain if the tests are not listed, but the tests may only be relevant for a later version of the specification. In such cases, listing the tests in a <wpt hidden> element silences the warnings, without adding anything irrelevant to the output.

Information about a set of tests described in a wpt element can be provided to the reader by writing it in the title attribute of the wpt element. This will be inserted in the output as an introductory paragraph before the test list. A lang or dir set on the wpt element will apply to the introductory paragraph if there is one.

<h1 id=intro>Introduction</h1>

This specification introduces…

<wpt title="The following tests are crash tests
            that relate to general usage
            of the features described in this specification
            but are not tied to any particular normative statement.">
crash-001.html
crash-002.html
</wpt>

The test block in the example above would be rendered as follows:

A WPT element with a list of tests, preceded by an introductory paragraph

If multiple wpt follow each other in the source, with nothing between them other than whitespace, they will be fused together in the output, visually taking less space than if they remained as separate elements. This will work even if they have different pathprefix or title attributes. When merging elements with title attributes, the tests listed in each element will be preceded by the relevant introductory paragraph, and visually separated from tests listed in different wpt elements.

Note: More tools and options for integrating with WPT will be developed in the future.

12.2. Updating Lists of Tests

If Bikeshed reports that a test doesn’t exist, but you’re sure that it does (and have checked the spelling!), make sure your data files are up-to-date with bikeshed update (see § 3.6 bikeshed update) for details).

If you’ve just pushed a new test to WPT and Bikeshed’s update hasn’t picked it up yet, try doing a manual update with bikeshed update --wpt --skip-manifest.

← 11 CDDL Processing Table of Contents 13 Boilerplate Generation →

CC0 To the extent possible under law, the editors have waived all copyright and related or neighboring rights to this work. In addition, as of 21 January 2026, the editors have made this specification available under the Open Web Foundation Agreement Version 1.0, which is available at https://www.openwebfoundation.org/the-agreements/the-owf-1-0-agreements-granted-claims/owfa-1-0. Parts of this work may be from another specification document. If so, those parts are instead covered by the license of that specification document.