Layout Test Style Guidelines

Feel free to propose new rules to put here or change to existing ones at blink-dev@. We have a thread for this topic.

See also Layout Tests for non-style but important info about layout test writing.

https://sites.google.com/a/chromium.org/dev/blink/blink-testing-and-the-w3c

Scope of this guideline

Feel free to follow some other style if there's special reason like:
  • [Imported tests] The test has been imported from W3C platform test repository
  • [Tests to be upstreamed] The test is going to be upstreamed to W3C platform test repository and need to follow the rule of the repo
Otherwise, we encourage you to follow the rules in this page.

Testing framework

Two testing frameworks are available in Blink layout test files. Consider using either of them to reduce boilerplate code and HTML elements.

js-test.js (From WebKit)

Pros:
  • Helpers like evalAndLog() and shouldBe() produce verbose output, which can make the output self-documenting
Cons:
  • shouldBe family functions use eval(). Values to be checked need to live in global scope (window, self).

testharness.js and testharnessreport.js (From W3C test suites)

Pros:
  • Can be upstreamed to W3C web-platform-tests
  • Passing expectations are not needed.
  • Contains helpers for writing tests with workers and asynchronous steps
Cons:
  • blink-dev doesn't have direct control on testharness.js development; changes can be upstreamed, but process may be slow.
  • Only prints whether each test case has passed, or the first failed assertion.

Comparison (=== vs. ==)

You might want to use the triple-equals operator for comparing actual/expected value strictly by avoiding type conversion where it makes sense.

Where the double-equals operator is sufficient, feel free to use it.

assert(!"");          // empty string is falsy
assert(!!"0");        // and non-empty string is truthy

assert("0" == 0);     // type coercion: string to number
assert("" == false);  // type coercion: string to boolean
assert("0" == false); // type coercion: string to number, then number to boolean!
assert("0" != "");    // but it's not transitive!

DOCTYPE declaration

Unless the test is explicitly testing quirks mode, include a DOCTYPE declaration at the top of the document.

<html>, <head>, <body>

These tags are normally omitted.

<!DOCTYPE html>
<script src="../resources/js-test.js"></script>
<script>
  ...
</script>

Indentation

Either of 2 space and 4 space indentation.

The usage should be consistent within a test file.

Braces


The usage should be consistent within a test file.

Quotation

Some tests use double quote for HTML (e.g. <script src="some.js">) and single quote for JavaScript (e.g. var image = 'resources/image.jpg';), but it could be either.

The usage should be consistent within a test file.

Comments

First, try to give a descriptive name to variables and functions. Then, write comments wherever it makes sense to improve readability.

File naming

Give a descriptive name. Separate words by hyphens. Be consistent.

Special directories

Put files that are used by layout test files in a sub-directory named "resources". See base.py.

TestRunner API

Some tests may require special help by the content_shell. See test_runner.cc for what kind of APIs are available on window.testRunner.

Most Layout Tests can be run in a browser without these additional APIs - which can assist in rapid iteration or quick debugging, and comparing the behavior with other browsers. For tests that do rely on helpers (e.g. observable garbage collection, event generation, etc) it is recommended that you feature-detect for the helpers and fail the test early with a diagnostic message explaining the requirement.

ServiceWorker tests

ServiceWorker development team has their own style guide. Some of them may apply to your project.

Comments