From e6941b11c16d8ac554c09de77d5dbe5994e1bdfc Mon Sep 17 00:00:00 2001 From: Tom McKee Date: Mon, 22 Feb 2021 08:06:00 -0800 Subject: [PATCH] Update ResourceTiming style guide to explain asserts vs. errors In ResourceTiming Web Platform Tests, we want to use assertion failures to indicate divergence from the spec but use exceptions to indicate issues with the test code. This change updates the style guide to call out this goal. Bug: 1171767 Change-Id: If9df3b05de75cbb516bc5c9f1ac0897abac0b4ab GithubIssue: https://github.com/w3c/resource-timing/issues/254 Reviewed-on: https://chromium-review.googlesource.com/c/chromium/src/+/2707184 Commit-Queue: Tom McKee Reviewed-by: Yoav Weiss Reviewed-by: Steve Kobes Cr-Commit-Position: refs/heads/master@{#856285} --- resource-timing/CodingConventions.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/resource-timing/CodingConventions.md b/resource-timing/CodingConventions.md index 461cae421e66c3..e8cb33a51e49a8 100644 --- a/resource-timing/CodingConventions.md +++ b/resource-timing/CodingConventions.md @@ -50,6 +50,11 @@ with recurring patterns. web performance APIs, in general). * Prefer [`fetch_tests_from_window`][3] to collect test results from embedded iframes instead of hand-rolled `postMessage` approaches +* Use the [`assert_*`][4] family of functions to check conformance to the spec + but throw exceptions explicitly when the test itself is broken. + * A failed assert indicates "the implementation doesn't conform to the + spec" + * Other uncaught exceptions indicate "the test case itself has a bug" * Where possible, we want tests to be scalable - adding another test case should be as simple as calling the tests with new parameters, rather than copying an existing test and modifying it. @@ -57,3 +62,4 @@ with recurring patterns. [1]: https://www.w3.org/TR/resource-timing-2/ [2]: https://web-platform-tests.org/writing-tests/testharness-api.html#promise-tests [3]: https://web-platform-tests.org/writing-tests/testharness-api.html#consolidating-tests-from-other-documents +[4]: https://web-platform-tests.org/writing-tests/testharness-api.html#list-of-assertions