Skip to content
wtf project

@wtf/project-wpt

Documentation / @wtf/project-wpt

Run a standard’s Web Platform Tests against your implementation of it, in the repo’s own Vitest run. Each testharness.js file of the WPT runs in a realm of its own (in Node, a node:vm context) whose globals are what the repo maps in, and each subtest becomes a test. It never reads or writes the test process’s own globals. Vitest is a peer dependency.

SubpathWhat you get
.The types: WptSystem, WptPaths, WptFile, Globals, FileResult, Expectations, …
./suitewptSuite(name, system, options): a WPT suite, with each subtest a test
./nodenodeSystem(): each service the runner takes, of Node; and each alone, nodeFiles, nodeExec, nodeRealm, …
./runrunTest(test, { folder, globals }): runs a test file in a context of its own
./checkoutcheckoutWpt and checkoutTests: the WPT at its commit, sparse and cached; fileOf, as served
./expectationsreadExpectations, expectationOf, checkSubtest, checkHarness, staleOf
./builtinsbuiltins(), the WinterTC values and constructors; intrinsics(), from the implementation’s realm
./metametaOf(source): the // META: lines of a test file
./errorsWptError and every other error, each with a stable code

A test file pins the WPT to a commit, names the suite’s tests and the resources they fetch, which file.fetch serves, and maps the implementation in:

test/broadcast-channel.wpt.test.ts
import { nodeSystem } from '@wtf/project-wpt/node'
import { wptSuite } from '@wtf/project-wpt/suite'


declare const MemoryChannel: unknown // import { MemoryChannel } from '../src/memory.ts'


wptSuite('broadcast-channel', nodeSystem(), {
  commit: '4ad507b28db0a636f528def9161d109fe11b93a3',
  dirs: ['webmessaging/broadcastchannel'],
  globals: () => ({ BroadcastChannel: MemoryChannel, console }),
  expectations: 'test/wpt/broadcast-channel.json'
})

To hold a suite to two implementations, write a wptSuite for each run, such as wptSuite('locks', system, { run: 'node', … }), each with its own expectations.

What it needs

The suite takes everything platform-specific as one required parameter, a WptSystem: the platform, whose timers a file runs with; the files it reads the checkout with; the exec it runs git with; the realm a file runs in; and the rejections it uses to hear unhandled ones. In Node, pass nodeSystem() of ./node.

The first run uses git to check out the parts of the WPT the suites need into node_modules/.cache/wpt/<commit>. Later runs work offline. A subtest the expectations list as failing passes its test while it fails, and fails once it passes, so the list only shrinks. See Standard tests in the tests guide.

Modules