tor-browser

For [Resource Timing][1] tests, we want to have a consistent and clear coding style. The goals of this style are to:

• Make it easier for new contributors to find their way around
• Help improve readability and maintainability
• Help us understand which parts of the spec are tested or not

Lots of the following rules are arbitrary but the value is realized in consistency instead of adhering to the 'perfect' style.

We want the test suite to be navigable. Developers should be able to easily find the file or test that is relevant to their work.

• Tests should be arranged in files according to which piece of the spec they

test

• Files should be named using a consistent pattern
• HTML files should include useful meta tags

* <title> for controlling labels in results pages * <link rel="help"> to point at the relevant piece of the spec

We want the test suite to run consistently. Flaky tests are counterproductive.

• Prefer promise_test to async_test

* Note that there’s [still potential for some concurrency][2]; use add_cleanup() if needed

We want the tests to be readable. Tests should be written in a modern style with recurring patterns.

• 80 character line limits where we can
• Consistent use of anonymous functions

* prefer ` const func1 = param1 => { body(); } const func2 = (param1, param2) => { body(); } fn(param => { body(); }); `

over

` function func1(param1) { body(); } function func2(param1, param2) { body(); } fn(function(param) { body(); }); `

• Prefer const (or, if needed, let) to var
• Contain use of ‘.sub’ in filenames to known helper utilities where possible

* E.g. prefer use of get-host-info.sub.js to {{host}} or {{ports[0]}} expressions

• Avoid use of webperftestharness[extension].js as it’s a layer of cognitive

overhead between test content and test intent * Helper .js files are still encouraged where it makes sense but we want to avoid a testing framework that is specific to Resource Timing (or 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.

[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