web-platform-tests / web-platform-tests/rfcs

Add (or generate) typescript definitions for testdriver.js and other important files

Open
#130 4 comments 1 reaction 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
No language data
Stars
110
Forks
90
PR merge metrics
No merged PRs in 30d

Description

Summary

Resources, such as testdriver.js, contain fantastic documentation and typescript compatible annotation information. It would be great if these were exported to .d.ts file(s) so they could be picked up by code editors.

Details

Because WPTests use absolute paths to script (and other reasons), the extremely useful documentation found in testdriver.js and other files can't be used by code editors, like VS Studio Code.

This means that people writing tests are missing out on all this valuable documentation and type checking information. Exposing such information would also catch test bugs, because it would could allow for TypeScript static checking.

It would also allow for introspection of test objects, to expose methods, signatures, properties, return types, etc.

What would be amazing would be if the testdriver.js annotations were in actual typescript files.

Risks

The typescript files getting out of sync with what's declared in the .js files. However, we could maybe include a warning that those files are automatically generated and shouldn't be touched (that is, if they can be automatically generated... I believe some can).

cc @saschanaz, who knows a lot more about TS than I do 🙇‍♀️

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by inspecting testdriver.js and the other resource files whose annotations should be exposed. Determine whether their type information can be generated into .d.ts files and how absolute-path WPTests consume them. Done means editors can discover the declarations and the generated types remain aligned with the JavaScript sources.

Written by the indexing model from the issue text.

Assessment

Tech stack
javascript, typescript
Domain
developer-experience, testing
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
30/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.