# Bikeshed Documentation

## Living Standard, 19 December 2025

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:

- If WPT Path Prefix is specified, then any tests under that prefix that aren’t specified in a `wpt` element will trigger a fatal error, so you’ll be alerted when new tests are added.

- If you specify a path that doesn’t exist (or no longer exists due to tests being moved or deleted), it will trigger a fatal error.

  This check can be disabled for a given `wpt` element by giving it the `skip-existence-check` boolean attribute. This allows you to point to private tests, such as those in browser-specific repos, without receiving errors about those tests missing from the main WPT repository.

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:

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

## Conformance

Conformance requirements are expressed with a combination of descriptive assertions and RFC 2119 terminology. The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in the normative parts of this document are to be interpreted as described in RFC 2119. However, for readability, these words do not appear in all uppercase letters in this specification.

All of the text of this specification is normative except sections explicitly marked as non-normative, examples, and notes. [RFC2119]

Examples in this specification are introduced with the words “for example” or are set apart from the normative text with `class="example"`, like this:

This is an example of an informative example.

Informative notes begin with the word “Note” and are set apart from the normative text with `class="note"`, like this:

Note, this is an informative note.