Add some docs around WPT test failures (#469)

bytecodealliance · Sep 7, 2023 · 088b51d · 088b51d
1 parent 5c0ac2d
commit 088b51d
Show file tree

Hide file tree

Showing 2 changed files with 15 additions and 0 deletions.
diff --git a/docs/contributing.md b/docs/contributing.md
@@ -15,3 +15,7 @@ The versions for `javy` and `javy-apis` must always be the same. So a version ch
 After publishing a release, immediately update the version number to the next patch version with an `-alpha.1` suffix. The first time an additive change is made, reset the patch version to `0` and increment the minor version and reset the suffix to `-alpha.1`. When making additional additive changes, increment the number in the suffix, for example `-alpha.2`. The first time a breaking change is made, reset the patch version and minor version to `0` and increment the major version and reset the suffix to `-alpha.1`. When making additional breaking changes, increment the number in the suffix, for example `-alpha.2`.
 
 When releasing, remove the suffix and then publish.
+
+## Web platform tests (WPT)
+
+We run a subset of the web platform test suite during continuous integration. We recommend reading our suite's [WPT readme](../wpt/README.md) for tips on how to add tests to the suite and what to do when tests won't pass.
diff --git a/wpt/README.md b/wpt/README.md
@@ -28,5 +28,16 @@ $ npm test
 
 Test suites can be added in `test_spec.js`. Individual tests can be ignored by including their name in the test's ignore list.
 
+## Tips for getting tests to pass
+
+- Adding tests to the ignored list is acceptable if there is no intent to support the feature the test is testing.
+- We highly recommend running the WPT suite with the `experimental_event_loop` Cargo feature enabled on the `javy-core` crate so tests relying on the event loop are able to pass.
+- Strongly consider adding tests in Rust for APIs you're adding to get faster feedback on failures the WPT suite catches while working on a fix.
+
+### If you need to change upstream tests
+
+- You may need to copy the test into the `custom_tests` directory and make small changes, then have the `test_spec.js` file run the copied test file instead of the upstream one.
+  - An example of this is commenting out small parts of test cases that are testing functionality that is intentionally not supported (for example, UTF-16 support for `TextDecoder`).
+
 [wpt]: https://wpt.fyi
 [rollup]: https://rollupjs.org