fune/dom/webgpu/tests/cts/checkout/docs/intro/developing.md

Developing

The WebGPU CTS is written in TypeScript.

Setup

After checking out the repository and installing node/npm, run:

npm ci

Before uploading, you can run pre-submit checks (npm test) to make sure it will pass CI. Use npm run fix to fix linting issues.

npm run will show available npm scripts. Some more scripts can be listed using npx grunt.

Dev Server

To start the development server, use:

npm start

Then, browse to the standalone test runner at the printed URL.

The server will generate and compile code on the fly, so no build step is necessary. Only a reload is needed to see saved changes. (TODO: except, currently, README.txt and file description changes won't be reflected in the standalone runner.)

Note: The first load of a test suite may take some time as generating the test suite listing can take a few seconds.

Standalone Test Runner / Test Plan Viewer

The standalone test runner also serves as a test plan viewer. (This can be done in a browser without WebGPU support.) You can use this to preview how your test plan will appear.

You can view different suites (webgpu, unittests, stress, etc.) or different subtrees of the test suite.

• http://localhost:8080/standalone/ (defaults to ?runnow=0&worker=0&debug=0&q=webgpu:*)
• http://localhost:8080/standalone/?q=unittests:*
• http://localhost:8080/standalone/?q=unittests:basic:*

The following url parameters change how the harness runs:

• runnow=1 runs all matching tests on page load.
• debug=1 enables verbose debug logging from tests.
• worker=1 runs the tests on a Web Worker instead of the main thread.
• power_preference=low-power runs most tests passing powerPreference: low-power to requestAdapter
• power_preference=high-performance runs most tests passing powerPreference: high-performance to requestAdapter

Web Platform Tests (wpt) - Ref Tests

You can inspect the actual and reference pages for web platform reftests in the standalone runner by navigating to them. For example, by loading:

• http://localhost:8080/out/webgpu/web_platform/reftests/canvas_clear.https.html
• http://localhost:8080/out/webgpu/web_platform/reftests/ref/canvas_clear-ref.html

You can also run a minimal ref test runner.

• open 2 terminals / command lines.
• in one, npm start
• in the other, node tools/run_wpt_ref_tests <path-to-browser-executable> [name-of-test]

Without [name-of-test] all ref tests will be run. [name-of-test] is just a simple check for substring so passing in rgba will run every test with rgba in its filename.

Examples:

MacOS

# Chrome
node tools/run_wpt_ref_tests /Applications/Google\ Chrome\ Canary.app/Contents/MacOS/Google\ Chrome\ Canary

Windows

# Chrome
node .\tools\run_wpt_ref_tests "C:\Users\your-user-name\AppData\Local\Google\Chrome SxS\Application\chrome.exe"

Editor

Since this project is written in TypeScript, it integrates best with Visual Studio Code. This is optional, but highly recommended: it automatically adds import lines and provides robust completions, cross-references, renames, error highlighting, deprecation highlighting, and type/JSDoc popups.

Open the cts.code-workspace workspace file to load settings convenient for this project. You can make local configuration changes in .vscode/, which is untracked by Git.

Pull Requests

When opening a pull request, fill out the PR checklist and attach the issue number. If an issue hasn't been opened, find the draft issue on the project tracker and choose "Convert to issue":

Opening a pull request will automatically notify reviewers.

To make the review process smoother, once a reviewer has started looking at your change:

• Avoid major additions or changes that would be best done in a follow-up PR.
• Avoid rebases (git rebase) and force pushes (git push -f). These can make it difficult for reviewers to review incremental changes as GitHub often cannot view a useful diff across a rebase. If it's necessary to resolve conflicts with upstream changes, use a merge commit (git merge) and don't include any consequential changes in the merge, so a reviewer can skip over merge commits when working through the individual commits in the PR.
• When you address a review comment, mark the thread as "Resolved".

Pull requests will (usually) be landed with the "Squash and merge" option.

TODOs

The word "TODO" refers to missing test coverage. It may only appear inside file/test descriptions and README files (enforced by linting).

To use comments to refer to TODOs inside the description, use a backreference, e.g., in the description, TODO: Also test the FROBNICATE usage flag [1], and somewhere in the code, [1]: Need to add FROBNICATE to this list..

Use MAINTENANCE_TODO for TODOs which don't impact test coverage.