diff --git a/.changeset/wpt-framework-profiles.md b/.changeset/wpt-framework-profiles.md index d486bbb..b01834b 100644 --- a/.changeset/wpt-framework-profiles.md +++ b/.changeset/wpt-framework-profiles.md @@ -2,4 +2,4 @@ '@bomb.sh/web-platform-tests': patch --- -Adds framework profiles that map the DOM features React 19.3, Preact 11.2, Vue 3.5, Solid 1.9, and Svelte 5.57 use to the WPT cases covering them. `framework()` returns selectors for a framework and its optional modules, and `uncoveredByWPT()` lists required features without adapted WPT coverage. +Adds framework profiles that map the DOM features React 19.3, Preact 11.2, Vue 3.5, Solid 1.9, and Svelte 5.57 use to the WPT cases covering them. `framework()` returns selectors for a framework and its optional modules, and `uncoveredByWPT()` lists required features without mapped upstream WPT coverage. diff --git a/.changeset/wpt-suite-fidelity.md b/.changeset/wpt-suite-fidelity.md index a4b4356..c97a467 100644 --- a/.changeset/wpt-suite-fidelity.md +++ b/.changeset/wpt-suite-fidelity.md @@ -2,6 +2,4 @@ '@bomb.sh/web-platform-tests': patch --- -Align the DOM compatibility suite with upstream WPT cases at a shared revision, mirror upstream source paths for tests and helpers, and remove locally authored scenarios and unused code. Keep local harness code in `src/shared`. Expose typed document and global bindings through the test fixture. Configure global bindings alongside upstream file and case selection in `wpt.config.ts`, with includes taking precedence over exclusions instead of requiring other test groups to be enabled. Register a todo when every case is excluded. - -Complete supported upstream matrices and record the concrete fixture limitations behind remaining omissions. +Run original upstream Web Platform Tests from a pinned submodule through a package CLI and Vitest transform. Consumers supply a document factory, global bindings, and source/case selection in `wpt.config.ts`. Execute whole files with their upstream helpers and shared state, then report selected subtests individually. Replace the adapted suite, generated registry, and browser adaptation tooling while preserving framework and feature selections. diff --git a/.eslintignore b/.eslintignore index 9cc1f8a..0d8a923 100644 --- a/.eslintignore +++ b/.eslintignore @@ -1,3 +1,2 @@ -# Preserve upstream WPT conventions. The shared harness files remain linted. -packages/web-platform-tests/src/compatibility/*/**/*.ts -packages/web-platform-tests/src/wpt/**/*.ts +# Preserve the original upstream WPT sources. The harness remains linted. +packages/web-platform-tests/wpt/** diff --git a/.github/workflows/check.yml b/.github/workflows/check.yml index 04f3145..cacedc6 100644 --- a/.github/workflows/check.yml +++ b/.github/workflows/check.yml @@ -38,6 +38,7 @@ jobs: - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 with: persist-credentials: false + submodules: true - uses: jdx/mise-action@c2a87611a18de5b3828c5652fe268e992400cb5c # v4.3.0 - run: pnpm install --frozen-lockfile - run: pnpm test @@ -51,9 +52,3 @@ jobs: - uses: jdx/mise-action@c2a87611a18de5b3828c5652fe268e992400cb5c # v4.3.0 - run: pnpm install --frozen-lockfile - run: pnpm --filter @bomb.sh/web-platform-tests typecheck - - run: pnpm --filter @bomb.sh/web-platform-tests exec playwright install --with-deps chromium - - run: pnpm --filter @bomb.sh/web-platform-tests test:wpt-selectors - - name: Report Chromium input compatibility - # Browser conformance differences are informational, not UI build failures. - continue-on-error: true - run: pnpm --filter @bomb.sh/web-platform-tests test:browser:input diff --git a/.gitmodules b/.gitmodules new file mode 100644 index 0000000..88bcb7d --- /dev/null +++ b/.gitmodules @@ -0,0 +1,3 @@ +[submodule "packages/web-platform-tests/wpt"] + path = packages/web-platform-tests/wpt + url = https://github.com/web-platform-tests/wpt.git diff --git a/.prettierignore b/.prettierignore new file mode 100644 index 0000000..f7aa94a --- /dev/null +++ b/.prettierignore @@ -0,0 +1 @@ +packages/web-platform-tests/wpt/** diff --git a/oxlint.config.ts b/oxlint.config.ts index a3d2bca..913ce4b 100644 --- a/oxlint.config.ts +++ b/oxlint.config.ts @@ -5,11 +5,7 @@ export default { overrides: [ ...(config.overrides ?? []), { - files: [ - 'packages/web-platform-tests/src/**/*.ts', - 'packages/web-platform-tests/test/browser/*.ts', - 'packages/web-platform-tests/test/browser/*.mts', - ], + files: ['packages/web-platform-tests/src/**/*.ts'], rules: { // Test registration and factories must return synchronously to the runner. 'bombshell-dev/exported-function-async': 'off', diff --git a/package.json b/package.json index d364764..51ed10b 100644 --- a/package.json +++ b/package.json @@ -33,7 +33,7 @@ "format": "bsh format", "format:check": "bsh format --check", "lint": "bsh lint .", - "test": "pnpm --filter @bomb.sh/web-platform-tests build && bsh test" + "test": "pnpm --filter @bomb.sh/web-platform-tests build && bsh test && pnpm --filter @clack/ui exec wpt" }, "devDependencies": { "@bomb.sh/tools": "^0.8.0", diff --git a/packages/ui/package.json b/packages/ui/package.json index af75cf0..dc2e2f0 100644 --- a/packages/ui/package.json +++ b/packages/ui/package.json @@ -33,7 +33,7 @@ "build": "bsh build --dts", "format": "bsh format", "lint": "bsh lint", - "test": "pnpm --filter @bomb.sh/web-platform-tests build && bsh test" + "test": "pnpm --filter @bomb.sh/web-platform-tests build && bsh test && wpt" }, "dependencies": { "@bomb.sh/tty": "catalog:", diff --git a/packages/ui/src/dom.compatibility.test.ts b/packages/ui/src/dom.compatibility.test.ts deleted file mode 100644 index c97e887..0000000 --- a/packages/ui/src/dom.compatibility.test.ts +++ /dev/null @@ -1,10 +0,0 @@ -import { describe, it, expect } from 'vitest'; -import { testDOMCompatibility } from '@bomb.sh/web-platform-tests'; -import { createHTMLDocument } from './dom.ts'; -import config from '../test/wpt.config.ts'; - -testDOMCompatibility({ - runner: { describe, it, expect }, - config, - create: () => createHTMLDocument(() => {}), -}); diff --git a/packages/ui/test/README.md b/packages/ui/test/README.md index 2e0750d..7566250 100644 --- a/packages/ui/test/README.md +++ b/packages/ui/test/README.md @@ -1,43 +1,49 @@ # UI tests -Tests live alongside the implementation in `src/`; this directory contains their shared fixtures and WPT configuration. Run the UI tests from the workspace root: +Tests live alongside the implementation in `src/`; this directory contains their +terminal fixtures. Run the UI tests from the workspace root: ```sh pnpm --filter @clack/ui test ``` -The test script builds the private `@bomb.sh/web-platform-tests` package before running Vitest. Use `pnpm test` from the workspace root to run the workspace tests. +The script builds the private WPT harness, runs local Vitest tests, and runs the +upstream cases selected by [`wpt.config.ts`](../wpt.config.ts). Use `pnpm test` +from the workspace root to run all workspace tests. ## Terminal fixtures -[`createTestUI`](ui.ts) starts the real UI with an in-process [Termless terminal](terminal.ts). It supplies application-facing input/output streams and exposes the document and terminal screen. Use `await using` to dispose the UI and terminal together, and `expect.poll` to wait for rendered output, as in [`ui.test.ts`](../src/ui.test.ts). +[`createTestUI`](ui.ts) starts the real UI with an in-process +[Termless terminal](terminal.ts). It supplies application-facing input/output +streams and exposes the document and terminal screen. Use `await using` to dispose +the UI and terminal together, and `expect.poll` to wait for rendered output, as in +[`ui.test.ts`](../src/ui.test.ts). -[`createTestTerminal`](terminal.ts) can also be used independently. Its `type` and `press` helpers write to the application's input stream, and terminal responses return through that same stream. It is an async disposable resource. +[`createTestTerminal`](terminal.ts) can also be used independently. Its `type` and +`press` helpers write to the application's input stream, and terminal responses +return through that same stream. It is an async disposable resource. -Rendering, scheduling, notifications, and lifecycle behavior belong in the UI tests. [`render.test.ts`](../src/render.test.ts) exercises render requests and cancellation; [`ui.lifecycle.test.ts`](../src/ui.lifecycle.test.ts) exercises terminal restoration, pending writes, and failure propagation. +Rendering, scheduling, notifications, and lifecycle behavior belong in the UI +tests. [`render.test.ts`](../src/render.test.ts) exercises render requests and +cancellation; [`ui.lifecycle.test.ts`](../src/ui.lifecycle.test.ts) exercises +terminal restoration, pending writes, and failure propagation. -## DOM compatibility +## DOM conformance -[`dom.compatibility.test.ts`](../src/dom.compatibility.test.ts) registers the shared compatibility suite with Vitest. Its synchronous factory creates a fresh instance of the real [`Document`](../src/dom.ts) for each case, with a no-op render notification callback. This fixture owns no external resources, so it needs no disposal callback. +[`wpt.config.ts`](../wpt.config.ts) supplies the document factory and global +bindings used by original Web Platform Test files. Add source paths and original +case names there while implementing DOM behavior. The +[WPT harness README](../../web-platform-tests/README.md) describes selection, +whole-file execution, and fixture capabilities. -[`dom.test.ts`](dom.test.ts) explicitly holds local DOM coverage missing from the enabled WPT cases. This is usually because getting the WPT test prequisites set up is too onerous a task. For example, testing node properties like nextSibling and previousSibling require things like `document.implementation.createDocumentType()` - -[`wpt.config.ts`](wpt.config.ts) supplies the implementation's `globals` and selects the upstream files and cases enforced by this integration. Add new global bindings there. Omitting `config` runs all adapted cases; `exclude` removes matches and explicit `include` rules take precedence. Source keys support `*` and `**`; values are `true` for a whole source or arrays of exact case names and regular expressions. Unmatched rules are configuration errors. No other test groups must be enabled to run a case. - -The configuration explicitly excludes unsupported directories. Add includes or narrow exclusions as cases pass. Selecting a source runs all of our adapted cases from that file; it does not imply complete coverage of the upstream file or interface. - -Include the source or case in the configuration while implementing it. Vitest's `-t` can narrow the configured selection by source path and case name: +After building the harness once, run selected cases without rebuilding: ```sh -pnpm --filter @clack/ui test src/dom.compatibility.test.ts -t 'Document-createElement.html.*createElement\(foo\)' +pnpm --filter @clack/ui exec wpt Node-parentNode -t 'Root element' ``` -If the shared package is already built, avoid rebuilding by using `pnpm --filter @clack/ui exec bsh test src/dom.compatibility.test.ts` with the same name filter. - -When implementing behavior, read the source-named file under [`src/wpt`](../../web-platform-tests/src/wpt), implement its operations, and update the configuration once its cases pass. Extend the fixture when cases need document parsing, host input, or cleanup. Implementation-specific rendering, notification, and lifecycle checks remain in the UI tests. - -## Host input - -Host input cases require a [`DOMInputDriver`](../../web-platform-tests/src/shared/input-driver.ts) that delivers input through the normal terminal input pipeline. A terminal adapter must resolve mouse targets through the UI's layout, await operation completion, and release held input during cleanup, including after failures. Calling `dispatchEvent`, invoking `.click()`, or directly assigning control values does not exercise that host behavior. - -Select keyboard/mouse delivery, platform interaction policies, and trusted-event cases independently as the implementation and its adapter support them. The shared suite's [browser tooling](../../web-platform-tests/README.md#development) validates the input contract with Playwright; the UI adapter must use terminal layout and input semantics. +Read the upstream source and helpers under +[`packages/web-platform-tests/wpt`](../../web-platform-tests/wpt) when working +through failures. All subtests in selected files execute; only configured and +name-filtered results are reported. Implementation-specific rendering and +lifecycle checks remain in the local UI tests. diff --git a/packages/ui/test/wpt.config.ts b/packages/ui/wpt.config.ts similarity index 83% rename from packages/ui/test/wpt.config.ts rename to packages/ui/wpt.config.ts index 51fe144..6503583 100644 --- a/packages/ui/test/wpt.config.ts +++ b/packages/ui/wpt.config.ts @@ -1,5 +1,6 @@ -import type { WPTConfig } from '@bomb.sh/web-platform-tests'; +import type { WPTConfig } from '@bomb.sh/web-platform-tests/config'; import { + createHTMLDocument, Attr, CharacterData, Comment, @@ -16,10 +17,11 @@ import { Node, Text, XMLDocument, -} from '../src/dom.ts'; -import { NamedNodeMap } from '../src/named-node-map.ts'; +} from './src/dom.ts'; +import { NamedNodeMap } from './src/named-node-map.ts'; const config: WPTConfig = { + createDocument: () => createHTMLDocument(() => {}), globals: { AbortController: globalThis.AbortController, Attr, @@ -60,30 +62,29 @@ const config: WPTConfig = { // case remains excluded until that behavior is implemented. ], 'dom/nodes/Document-createTextNode.html': true, - 'dom/nodes/Document-createElement.html': true, - 'dom/nodes/Document-createElementNS.html': true, + 'dom/nodes/Document-createElement.html': [/^createElement\(.*\) in HTML document$/], + 'dom/nodes/Document-createElementNS.html': [ + /^createElementNS test in HTML document:/, + /^(Lower|Upper)-case /, + 'null namespace', + 'undefined namespace', + 'empty string namespace', + ], 'dom/nodes/Document-createComment.html': true, 'dom/nodes/DOMImplementation-createDocument.html': [ - 'createDocument row 0', // null qualified name: no root. - 'createDocument row 1', // undefined qualified name: an "undefined" root. - 'createDocument row 2', // A root without a namespace. - 'createDocument row 3', // Invalid qualified name. - 'createDocument row 23', // A prefix requires a namespace. - 'createDocument row 63', // A root with a namespace and prefix. - 'createDocument row 182', // A non-DocumentType doctype argument. - 'createDocument row 183', // Empty qualified name: no root. - 'createDocument row 185', // Explicit undefined arguments. + 'createDocument test: null,null,null,null', + 'createDocument test: null,undefined,null,null', + 'createDocument test: null,"foo",null,null', + 'createDocument test: null,"1foo",null,"INVALID_CHARACTER_ERR"', + 'createDocument test: null,"f:oo",null,"NAMESPACE_ERR"', + 'createDocument test: "http://example.com/","f:oo",null,null', + 'createDocument test: null,null,false,function "function TypeError() { [native code] }"', + 'createDocument test: null,"",null,null', + 'createDocument test: undefined,undefined,undefined,null', 'createDocument with missing arguments', ], 'dom/nodes/DOMImplementation-createHTMLDocument.html': [ - 'createHTMLDocument()', - 'createHTMLDocument(null)', - 'createHTMLDocument(undefined)', - 'createHTMLDocument(foo bar baz)', - 'createHTMLDocument(foo\t\tbar baz)', - 'createHTMLDocument(foo\n\nbar baz)', - 'createHTMLDocument(foo\f\fbar baz)', - 'createHTMLDocument(foo\r\rbar baz)', + /^createHTMLDocument test [0-7]:/, 'Missing title argument', ], // XML cases also require createAttribute() to preserve name casing. @@ -97,12 +98,9 @@ const config: WPTConfig = { 'dom/nodes/Element-removeAttributeNS.html': true, 'dom/nodes/Element-setAttribute-crbug-1138487.html': true, 'dom/nodes/Element-hasAttribute.html': [ - // The other case requires a parsed HTML fixture. 'hasAttribute should check for attribute presence, irrespective of namespace', ], 'dom/nodes/attributes-namednodemap.html': true, - // Excludes cases requiring XML documents, CSS style reflection, document - // fragments, parsed fixtures, or attachment to document.body. 'dom/nodes/attributes.html': [ 'Attribute loses its owner when removed', 'Basic functionality of getAttributeNode/getAttributeNodeNS', @@ -188,19 +186,7 @@ const config: WPTConfig = { 'Inserting a node before itself should not move the node', ], }, - exclude: { - 'css/**': true, - 'custom-elements/**': true, - 'dom/**': true, - 'domparsing/**': true, - 'html/**': true, - 'inert/**': true, - 'input-events/**': true, - 'selection/**': true, - 'shadow-dom/**': true, - 'uievents/**': true, - 'xhr/**': true, - }, + exclude: { '**': true }, }; export default config; diff --git a/packages/web-platform-tests/AGENTS.md b/packages/web-platform-tests/AGENTS.md index 9c4afa9..5b5ee97 100644 --- a/packages/web-platform-tests/AGENTS.md +++ b/packages/web-platform-tests/AGENTS.md @@ -1,71 +1,44 @@ -# WPT provenance and correspondence - -This package is the long-term source of upstream WPT coverage for the UI. - -Every shared DOM conformance case must faithfully reflect an existing, inspected -upstream Web Platform Test. Do not invent cases, add local assertions to upstream -cases, extend their inputs or matrices, or infer new tests from the specification. -Independent subtleties, regressions, and implementation-specific checks belong in -tests outside this package's WPT suite, even when they test standards behavior. -A citation to a related upstream test does not make a local addition a WPT case. - -This requirement applies to all adapted cases, including excluded cases. -Tests of the runner and fixtures are infrastructure tests, separate from WPT cases. - -The suite shares one upstream revision in `WPT_REVISION`. Use that revision -for source review; do not choose a separate revision for each case or file. - -Files under `src/wpt` mirror the exact upstream path, spelling, and capitalization -with `.ts` appended. For example, `src/wpt/dom/nodes/Document-createElement.html.ts` -corresponds to `dom/nodes/Document-createElement.html`. The registry derives source -identity from that convention; do not repeat it in runtime metadata or per-case -annotations. Keep each file's cases together. Upstream helpers and data also use -their natural paths under `src/wpt`. Only test entrypoints export `register`; -support files are imported by those tests. Local harness code belongs in -`src/shared`. Keep setup used by a single source in that source file. - -Keep ordinary `context.test` and `expect` calls with readable case names. Do not -introduce per-case registration wrappers. Destructure document and global bindings -from the typed fixture; their expected types are asserted once at the fixture -boundary. Wrap callback assertions with `fixture.step` so the runner observes -failures. Shared attribution and license information belong in `test/wpt`. - -When adding or migrating a case: - -1. Read the upstream source at the suite revision. Use its path for the adapted - filename and identify any helper/data sources in comments. Run `pnpm generate` - after adding, moving, or removing source files. -2. Preserve the upstream inputs, setup, operation order, assertions, exceptions, - node identities, document ownership, and matrix rows. Separate documents, - detached trees, and retained collections are meaningful test conditions. -3. Limit adaptations to integration with the consumer's runner, fixtures, and - input driver. Comment only on non-obvious adaptations, preserving the - tested behavior without adding or removing behavioral checks. Keep the code - close enough to upstream for a side-by-side review. -4. Record omitted upstream cases and their reasons in [docs/omissions.md](docs/omissions.md). - Selecting a subset of a file does not establish coverage of the entire file. - Do not merge several upstream cases into a smaller example or drop assertions - to accommodate an incomplete implementation. -5. Keep upstream authorship and license notices. A specification URL, a directory - link, or a reference to a merely similar test is insufficient provenance. - Do not claim that an existing local case was derived from WPT - without establishing that correspondence; replace it with a verified - adaptation when necessary. -6. Verify the source mapping and registered cases, review assertion correspondence, - and run browser validation and the affected consumer tests. Matching names or - passing against a browser alone does not establish correspondence. - -Fix missing implementation behavior or explicitly exclude its cases in the consumer configuration. -Never weaken a shared case, change its fixture semantics, or silently omit it -just to make the UI implementation pass. - -Test selection uses upstream source paths and original case names. All adapted -cases run by default; explicit includes override exclusions. Do not gate a case -on another test group's selection or silently omit cases based on API detection. -Supporting DOM behavior is exercised by the selected case itself. Document -creation options, global bindings, and input drivers remain fixture contracts, -checked when the selected case uses them. - -The selector omission check is an existing example of -traceability, not a waiver for other features. The entire suite must meet this -requirement before it can be described as a fully traceable WPT adaptation. +# WPT provenance and execution + +This package runs original upstream Web Platform Tests against consumer DOM +implementations. The sources live in the `wpt` git submodule; its revision must +match `WPT_REVISION`. Read that checkout when reviewing or enabling cases. + +Do not copy, rewrite, or adapt upstream tests into this package. Do not invent +cases, add assertions, change fixtures or input matrices, or infer tests from the +specification. Keep upstream sources, helpers, authorship, and license notices +unchanged. Implementation-specific tests belong with the consumer. + +The CLI transforms each selected upstream file into a Vitest test module. Execute +its scripts and static helpers in their original order, in one window context per +file. Execute all registered subtests, including unselected ones, so their shared +state and setup remain intact. Filter results only when reporting them. Never +hide source-loading, setup, or harness failures behind a subtest filter. + +Consumer `wpt.config.ts` files supply document factories, global bindings, and +source/case selectors. Explicit includes override exclusions. Use original WPT +case names. Selecting some cases from a file does not establish coverage of the +whole file. Unmatched selectors must remain visible configuration errors. + +Framework profiles and feature maps in `src/frameworks` are part of the public +selection API. Preserve them when changing the runner, and check their source +paths and case names against the original upstream files. + +When enabling coverage or changing the harness: + +1. Read the original source and any helpers at the pinned revision. +2. Preserve the complete upstream setup, operation order, assertions, exceptions, + node identities, document ownership, and shared state between subtests. +3. Supply missing fixture capabilities without changing the behavior tested. + Unsupported source features must fail explicitly rather than silently skip. +4. Keep genuine file errors observable even when every subtest is excluded. + Any exception for a pending unsupported subtest must be narrow, documented, + and disabled when that subtest is selected. +5. Verify the affected consumer cases, build, and typecheck. Format and lint the + harness. When migrating coverage, compare cases and assertions; matching + totals or passing against a browser alone does not establish correspondence. + +Fix missing DOM behavior in the consumer or explicitly exclude unsupported cases +in its configuration. Never weaken upstream assertions to make an implementation +pass. Local harness code belongs in `src/node` and `src/vitest`; the consumer +should need only its configuration to integrate with this package. diff --git a/packages/web-platform-tests/README.md b/packages/web-platform-tests/README.md index 68f1f8e..18c620c 100644 --- a/packages/web-platform-tests/README.md +++ b/packages/web-platform-tests/README.md @@ -1,105 +1,138 @@ # @bomb.sh/web-platform-tests -Private workspace package containing reusable DOM compatibility assertions. It contains no DOM implementation. Only `@clack/ui` tests consume its package API; browser validation is development tooling. +Run original [Web Platform Tests (WPT)](https://github.com/web-platform-tests/wpt) +against a DOM implementation. This private workspace package supplies a CLI, +HTML fixtures, and a Vitest transform. Each upstream source appears as a separate +test file, with individually reported subtests. -The suite includes adaptations of [Web Platform Tests (WPT)](https://github.com/web-platform-tests/wpt) covering DOM operations, state/style interactions, input, shadow DOM, forms, CSSOM, selection, traversal, and parsing. +The [`wpt`](wpt) submodule pins the upstream sources at the revision recorded in +[WPT_REVISION](WPT_REVISION). Upstream authorship and licenses remain in the +checkout; see [WPT's license](wpt/LICENSE.md). The local harness uses the package's +[MIT license](LICENSE). -The suite uses one upstream WPT revision, recorded in [WPT_REVISION](WPT_REVISION). Browse that revision [here](https://github.com/web-platform-tests/wpt/tree/b719612f963a05ece9c89a7dd7598c1c59618874). Files under `src/wpt` mirror upstream paths with `.ts` appended; the revision applies to all files and cases. See [attribution and licenses](test/wpt/README.md). +## Running tests -### Required WPT correspondence +From the workspace root: -Each file under `src/wpt` corresponds to its upstream path with the final `.ts` removed. For example, `src/wpt/dom/nodes/Document-createElement.html.ts` adapts `dom/nodes/Document-createElement.html`. Keep upstream spelling and capitalization for tests, helpers, and data. Local harness code lives in `src/shared`; comments explain non-obvious adaptations. - -Keep ordinary `context.test` and `expect` calls and readable case names. Preserve upstream inputs, setup, operation order, assertions, exceptions, node identities, and relationships between documents. A file's presence identifies the selected adaptations, not coverage of every upstream case. [Omissions](docs/omissions.md) records skipped upstream cases and why. - -The WPT suite must contain only faithful adaptations of existing upstream cases. Do not invent scenarios, add local assertions, extend upstream input matrices, or create specification-derived cases here. Independently authored subtleties, regressions, and implementation-specific checks belong in separate tests outside this suite. Necessary harness adaptations must preserve the upstream behavior being tested. Tests of the harness itself are separate infrastructure tests. +```sh +git submodule update --init packages/web-platform-tests/wpt +pnpm --filter @bomb.sh/web-platform-tests build +pnpm --filter @clack/ui exec wpt +``` -The shared suite is the long-term home of upstream WPT coverage for the UI. Implementation-specific rendering, notification, and lifecycle checks belong in the corresponding UI integration tests. +Subsequent runs need no rebuild unless the harness changes. The CLI accepts +`--config path/to/wpt.config.ts`, optional filename filters, and `-t`/`--name` for +subtest names: -```ts -import { testDOMCompatibility } from '@bomb.sh/web-platform-tests'; -import { describe, it, expect } from 'vitest'; -import { createDocument, dispose } from './implementation-fixture.ts'; -import config from './wpt.config.ts'; - -testDOMCompatibility({ - runner: { describe, it, expect }, - config, - create: createDocument, - dispose, - // input: document => createHostInputSession(document), -}); +```sh +pnpm --filter @clack/ui exec wpt Node-parentNode -t 'Root element' +pnpm --filter @clack/ui exec wpt --config wpt.config.ts Document-createElementNS ``` -### Selecting tests +`pnpm test` and `pnpm --filter @clack/ui test` build the harness, run the local +implementation tests, and run the configured WPT cases. -The `config` option is optional; omitting it runs all adapted cases. A `WPTConfig` supplies source-path selectors in `include` and `exclude`; an explicit include always wins. Each value is `true` for the entire source file or an array of exact case names and regular expressions matching case names. +## Configuration -When selection excludes every case, the harness registers a todo through `runner.it.todo` to start implementing DOM features and enable their WPT cases. +A consumer needs only a `wpt.config.ts`. It supplies a document factory and the +implementation's global bindings, then selects upstream source paths and original +case names. See the [UI configuration](../ui/wpt.config.ts). ```ts -import type { WPTConfig } from '@bomb.sh/web-platform-tests'; -import { globals } from './implementation-fixture.ts'; +import type { WPTConfig } from '@bomb.sh/web-platform-tests/config'; +import { createHTMLDocument, Node, Document, Element } from './dom.ts'; export default { - globals, - exclude: { 'dom/nodes/Node-insertBefore.html': true }, - include: { 'dom/nodes/Node-insertBefore.html': [/reference child/] }, + createDocument: () => createHTMLDocument(), + globals: { Node, Document, Element }, + include: { + 'dom/nodes/Node-parentNode.html': ['Document', 'Root element'], + }, + exclude: { '**': true }, } satisfies WPTConfig; ``` -Source paths support `*` within a path segment and `**` across directories; `**/` also matches zero directories. Other characters are literal. Case-name strings match exactly. Empty, invalid, or unmatched selectors fail configuration before any cases register, so stale exclusions remain visible. +`createDocument()` returns a fresh document for each upstream file. The harness +populates it with that file's HTML and installs `document.defaultView`. +`globals` supplies the constructors and other bindings the tests use. `timeout` +sets the maximum execution time per file in milliseconds; the default is 15,000. + +Source keys support `*` within a path segment and `**` across directories. Values +are `true` for every subtest in a source or arrays of exact names and regular +expressions. Explicit includes override exclusions; otherwise cases are included +unless excluded. Use `exclude: { '**': true }` to enable cases incrementally. +Invalid or unmatched selectors fail configuration. -Cases have no test-to-test prerequisite gates. A selected case exercises its supporting DOM operations and reports failures normally. Globals and host input are resolved lazily when the case uses them. The runner can narrow selected cases further with its usual name filter. +### Framework selections -Run `pnpm generate` after adding, moving, or removing source files. The build also regenerates the registry from filenames. Only files exporting `register` are test entrypoints; upstream support files are imported by those tests. `node scripts/generate-registry.mjs --check` verifies that the checked-in registry is current. +`framework()` returns selectors for the DOM features used by React, Preact, Vue, +Solid, or Svelte. Pass them to `include` with `exclude: { '**': true }` to run +that profile against the consumer's document factory and globals: -### Harness +```ts +import { framework, type WPTConfig } from '@bomb.sh/web-platform-tests'; +import { createDocument, globals } from './dom.ts'; -* `create(options?)`: A synchronous or asynchronous factory for a fresh `Document`. Cases using the default HTML document expect its doctype, `html`, `head`, and `body` tree. When a case supplies `DOMDocumentOptions`, honor its markup, MIME type, and URL fragment; the selector matrix uses these to test HTML, XHTML, and `:target`. -* `config.globals`: An object containing the implementation's global bindings, or a function that returns them for each fresh document. Tests destructure typed bindings from the fixture, such as `({ document, Node, Text })`. Omitting globals supplies no bindings; accessing a missing binding throws. -* `input`: An optional factory for a `DOMInputDriver` session that delivers keyboard, text, and mouse input through the implementation's normal host input pipeline. This allows testing of default actions like focus on click, form submission on `Enter`, and trusted events. -* `dispose(document)`: Optional cleanup for implementation-owned resources after each case, including failures. +export default { + createDocument, + globals, + include: framework('preact'), + exclude: { '**': true }, +} satisfies WPTConfig; +``` -### Development +Pass optional modules as a second argument, such as +`framework('vue', ['transitions'])` or `framework('preact', ['hydration'])`. +`frameworks` exposes the required features and optional modules for each profile. +`features` maps individual DOM members to upstream cases, and +`featureSelectors(['Document#createElement', 'Node#textContent'])` combines their +selections. Unknown optional modules throw `CompatibilityConfigurationError`. + +`uncoveredByWPT('preact')` lists required features that have no mapped cases yet. +It describes gaps in the profile's mappings, not missing DOM support. A profile +selects conformance work; passing the currently enabled UI cases does not mean +the full profile passes. These selections use the same original sources and +whole-file execution as explicit selectors. + +## Execution and limitations + +The harness parses HTML with parse5, populates the implementation's document, +and executes the original inline scripts and static local helpers in source +order within one window context per file. It loads upstream `testharness.js` in +its shell environment and delivers window `load` after the scripts finish. +Script elements are fixture nodes; parsing them does not execute their contents. + +Entire selected files execute, including their unselected subtests. Configuration +and CLI name filters select the results reported by Vitest. This preserves +upstream shared state and setup. Source-loading, setup, and harness errors remain +failures regardless of subtest selection. + +The excluded `Removed iframe` case in `Node-parentNode.html` is explicitly forced +to time out after window load and the selected cases finish. Selecting that case +disables this exception. It depends on an iframe load the fixture cannot deliver. + +The runner supports HTML sources and window `.any.js`/`.window.js` sources with +static helpers. It does not implement iframe navigation, parser-driven script +timing, module/async/defer scripts, server substitutions, or remote helpers. +Unsupported source features fail explicitly. Selecting part of a file does not +claim coverage of its remaining subtests or complete standards conformance. + +Parsed `