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.

Imported tests / tests to be upstreamed

Feel free to follow some other style if there's special reason like:
  • The test has been imported from W3C platform test repository
  • 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)

  • Helpers like evalAndLog() and shouldBe() produce verbose output, which can make the output self-documenting
  • 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)

  • Can be upstreamed to W3C web-platform-tests
  • Passing expectations are not needed.
  • Contains helpers for writing tests with workers and asynchronous steps
  • 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.

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>


Either of 2 space and 4 space indentation.

The usage should be consistent within a test file.


The usage should be consistent within a test file.


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.


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 or underscores. Be consistent.

Special directories

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

TestRunner API

Some tests may require special help by the content_shell. See 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.

License boilerplate

<Most of layout test files don't contain any license declaration. Is this fine? Should we encourage putting it?>

ServiceWorker tests

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