1Blink layout tests
2==================
3
4How to land Skia changes that change Blink layout test results.
5
6Changes that affect a small number of layout test results
7---------------------------------------------------------
8Changes affecting fewer than ~20 layout tests can be rebaselined without
9special coordination with the Blink gardener using these steps:
10
111. Prepare your Skia change, taking note of which layout tests will turn red
12   \(see http://www.chromium.org/developers/testing/webkit-layout-tests for more
13   detail on running the Blink layout tests\).
142. Check in your code to the Skia repo.
153. Ahead of the Skia auto roll including your change, manually push a change to the
16   Blink LayoutTests/TestExpectations [file](https://chromium.googlesource.com/chromium/src/+/master/third_party/WebKit/LayoutTests/TestExpectations), flagging tests expected to fail as a result of your change as follows:
17   foo/bar/test-name.html [ Failure Pass ]  # Needs rebaseline
18
194. Wait for the Skia roll to land successfully.
205. Check in another change to the Blink TestExpectations file removing all the
21  skipped test expectations you add earlier, an run `git cl rebaseline` which will prompt the automatic rebaseline.
22
23
24
25Changes that affect a large number of test results
26--------------------------------------------------
27Where a 'large number' or 'many' means more than about 20.
28Follow the instructions below:
29
30In the following the term 'code suppression' means a build flag \(a\.k\.a\. define\).
31Such code suppressions should be given a name with the form SK\_IGNORE\_xxx\_FIX.
32
33Updating the version of Skia in Chromium is called a 'roll'.
34The Auto Roll Bot performs this roll multiple times per day, and can also be done manually.
35See https://chromium.googlesource.com/chromium/src/+log/master/DEPS and search for skia\-deps\-roller.
36
37### Setup
38#### Code suppression does not yet exist \- Direct method
391. Make a change in Skia which will change many Blink layout tests.
402. Put the change behind a code suppression.
413. Check in the change to the Skia repository.
424. Manually roll Skia or append the autoroll with the code suppression to
43   Chromium's 'skia/chromium\_skia\_defines\.gypi'
44
45#### Code suppression does not yet exist \- Alternate method
461. Add code suppression to Chromium's 'skia/chromium\_skia\_defines\.gypi' before making code
47   changes in Skia.
482. Make a change in Skia which will change many Blink layout tests.
493. Put the change behind a code suppression.
504. Check in the change to the Skia repository.
515. Wait for Skia roll into Chromium.
52
53#### Code suppression exists in header
541. Remove code suppression from header file in Chromium and add code suppression to
55   Chromium's 'skia/chromium\_skia\_defines\.gypi'.
56   The code suppression cannot be in a header file and a defined in a gyp file at the
57   same time or a multiple definition warning will be treated as an error and break
58   the Chromium build.
59
60### Rebaseline
611. Choose a time when the Blink tree is likely to be quiet. Avoid PST afternoons in
62   particular. The bigger the change, the more important this is. Regardless,
63   determine who the Blink gardener is and notify them. You will be making the
64   Chromium\.WebKit tree very red for an extended period, and the gardener needs to
65   know that they are not expected to fix it.
662. Create a CL removing the code suppression from Chromium's
67   skia/chromium\_skia\_defines\.gypi while simultaneously adding [ NeedsRebaseline ]
68   lines to Blink's LayoutTests/TestExpectations [file](https://chromium.googlesource.com/chromium/src/+/master/third_party/WebKit/LayoutTests/TestExpectations).
69   Then the auto rebaseline bot will take care of the work of actually checking in the
70   new images. This is generally acceptable for up to 600 or so rebaselined images.
71   Above that you might still use [ NeedsRebaseline ], but it's best to coordinate with
72   the gardener/sheriff. This should go through the CQ cleanly.
733. Be careful with tests that are already failing or flakey. These may or may not need
74   to be rebaselined and flakey tests should not be removed from TestExpectations
75   regardless. In such cases revert the TestExpectations changes before committing.
764. If you are not the one handling the cleanup step, please open a Skia Issue of the
77   form
78   Title: "Remove code suppression SK\_IGNORE\_xxx\_FIX\."
79   Comment: "Code suppression SK\_IGNORE\_xxx\_FIX rebaselined with Blink revision
80   123456\." and assign it to the individual responsible for the cleanup step.
81
82### Cleanup
831. Remove the now unused old code from Skia and any defines which were introduced
84   to suppress the new code.
852. Check in the cleanup change to the Skia repository.
863. Wait for Skia roll into Chromium.
87
88