docs/testing/layout_test_expectations.md

# Layout Test Expectations and Baselines


The primary function of the LayoutTests is as a regression test suite; this
means that, while we care about whether a page is being rendered correctly, we
care more about whether the page is being rendered the way we expect it to. In
other words, we look more for changes in behavior than we do for correctness.

[TOC]

All layout tests have "expected results", or "baselines", which may be one of
several forms. The test may produce one or more of:

* A text file containing JavaScript log messages.
* A text rendering of the Render Tree.
* A screen capture of the rendered page as a PNG file.
* WAV files of the audio output, for WebAudio tests.

For any of these types of tests, baselines are checked into the LayoutTests
directory. The filename of a baseline is the same as that of the corresponding
test, but the extension is replaced with `-expected.{txt,png,wav}` (depending on
the type of test output). Baselines usually live alongside tests, with the
exception when baselines vary by platforms; read
[Layout Test Baseline Fallback](layout_test_baseline_fallback.md) for more
details.

Lastly, we also support the concept of "reference tests", which check that two
pages are rendered identically (pixel-by-pixel). As long as the two tests'
output match, the tests pass. For more on reference tests, see
[Writing ref tests](https://trac.webkit.org/wiki/Writing%20Reftests).

## Failing tests

When the output doesn't match, there are two potential reasons for it:

* The port is performing "correctly", but the output simply won't match the
  generic version. The usual reason for this is for things like form controls,
  which are rendered differently on each platform.
* The port is performing "incorrectly" (i.e., the test is failing).

In both cases, the convention is to check in a new baseline (aka rebaseline),
even though that file may be codifying errors. This helps us maintain test
coverage for all the other things the test is testing while we resolve the bug.

*** promo
If a test can be rebaselined, it should always be rebaselined instead of adding
lines to TestExpectations.
***

Bugs at [crbug.com](https://crbug.com) should track fixing incorrect behavior,
not lines in
[TestExpectations](../../third_party/WebKit/LayoutTests/TestExpectations). If a
test is never supposed to pass (e.g. it's testing Windows-specific behavior, so
can't ever pass on Linux/Mac), move it to the
[NeverFixTests](../../third_party/WebKit/LayoutTests/NeverFixTests) file. That
gets it out of the way of the rest of the project.

There are some cases where you can't rebaseline and, unfortunately, we don't
have a better solution than either:

1. Reverting the patch that caused the failure, or
2. Adding a line to TestExpectations and fixing the bug later.

In this case, **reverting the patch is strongly preferred**.

These are the cases where you can't rebaseline:

* The test is a reference test.
* The test gives different output in release and debug; in this case, generate a
  baseline with the release build, and mark the debug build as expected to fail.
* The test is flaky, crashes or times out.
* The test is for a feature that hasn't yet shipped on some platforms yet, but
  will shortly.

## Handling flaky tests

The
[flakiness dashboard](https://test-results.appspot.com/dashboards/flakiness_dashboard.html)
is a tool for understanding a test’s behavior over time.
Originally designed for managing flaky tests, the dashboard shows a timeline
view of the test’s behavior over time. The tool may be overwhelming at first,
but
[the documentation](https://dev.chromium.org/developers/testing/flakiness-dashboard)
should help. Once you decide that a test is truly flaky, you can suppress it
using the TestExpectations file, as described below.

We do not generally expect Chromium sheriffs to spend time trying to address
flakiness, though.

## How to rebaseline

Since baselines themselves are often platform-specific, updating baselines in
general requires fetching new test results after running the test on multiple
platforms.

### Rebaselining using try jobs

The recommended way to rebaseline for a currently-in-progress CL is to use
results from try jobs, by using the command-tool
`third_party/WebKit/Tools/Scripts/webkit-patch rebaseline-cl`:

1. First, upload a CL.
2. Trigger try jobs by running `webkit-patch rebaseline-cl`. This should
   trigger jobs on
   [tryserver.blink](https://build.chromium.org/p/tryserver.blink/builders).
3. Wait for all try jobs to finish.
4. Run `webkit-patch rebaseline-cl` again to fetch new baselines.
   By default, this will download new baselines for any failing tests
   in the try jobs.
   (Run `webkit-patch rebaseline-cl --help` for more specific options.)
5. Commit the new baselines and upload a new patch.

This way, the new baselines can be reviewed along with the changes, which helps
the reviewer verify that the new baselines are correct. It also means that there
is no period of time when the layout test results are ignored.

#### Options

### Rebaselining with try jobs

The tests which `webkit-patch rebaseline-cl` tries to download new baselines for
depends on its arguments.

* By default, it tries to download all baselines for tests that failed in the
  try jobs.
* If you pass `--only-changed-tests`, then only tests modified in the CL will be
  considered.
* You can also explicitly pass a list of test names, and then just those tests
  will be rebaselined.
* If some of the try jobs failed to run, and you wish to continue rebaselining
  assuming that there are no platform-specific results for those platforms,
  you can add the flag `--fill-missing`.

### Rebaselining manually

1. If the tests is already listed in TestExpectations as flaky, mark the test
   `NeedsManualRebaseline` and comment out the flaky line so that your patch can
   land without turning the tree red. If the test is not in TestExpectations,
   you can add a `[ Rebaseline ]` line to TestExpectations.
2. Run `third_party/WebKit/Tools/Scripts/webkit-patch rebaseline-expectations`
3. Post the patch created in step 2 for review.

## Kinds of expectations files

* [TestExpectations](../../third_party/WebKit/LayoutTests/TestExpectations): The
  main test failure suppression file. In theory, this should be used for
  temporarily marking tests as flaky.
* [ASANExpectations](../../third_party/WebKit/LayoutTests/ASANExpectations):
  Tests that fail under ASAN.
* [LeakExpectations](../../third_party/WebKit/LayoutTests/LeakExpectations):
  Tests that have memory leaks under the leak checker.