submodule/skia/site/docs/dev/testing/skiagold.md

   1 ---
   2 title: 'Skia Gold'
   3 linkTitle: 'Skia Gold'
   4 ---
   5
   6 ## Overview
   7
   8 Gold is a web application that compares the images produced by our bots against
   9 known baseline images.
  10
  11 Key features:
  12
  13 - Baselines are managed in Gold outside of Git, but in lockstep with Git
  14   commits.
  15 - Each commit creates >500k images.
  16 - Deviations from the baseline are triaged after a CL lands and images are
  17   triaged as either `positive` or `negative`. 'Positive' means the diff is
  18   considered acceptable. 'Negative' means the diff is considered unacceptable
  19   and requires a fix. If a CL causes Skia to break it is reverted or an
  20   additional CL is landed to fix the problem.
  21 - We test across a range of dimensions, e.g.:
  22
  23   - OS (Windows, Linux, Mac, Android, iOS)
  24   - Architectures (Intel, ARM)
  25   - Backends (CPU, OpenGL, Vulkan etc.)
  26   - etc.
  27
  28 - Written in Go, Polymer and deployed on the Google Cloud. The code is in the
  29   [Skia Infra Repository](https://github.com/google/skia-buildbot).
  30
  31 ## Recommended Workflows
  32
  33 ### How to best use Gold for commonly faced problems
  34
  35 These instructions will refer to various views which are accessible via the left
  36 navigation on [gold.skia.org](https://gold.skia.org/).
  37
  38 View access is public, triage access is granted to Skia contributors. You must
  39 be logged in to triage.
  40
  41 ## Problem #1: As Skia Gardener, I need to triage and “assign” many incoming new images.
  42
  43 Solution today:
  44
  45 - Access the By Blame view to see digests needing triage and associated
  46   owners/CLs
  47   - Only untriaged digests will be shown by default
  48   - Blame is not sorted in any particular order
  49   - Digests are clustered by runs and the most minimal set of blame
  50
  51 <img src=../BlameView.png style="margin-left:30px" align="left" width="800"/>
  52 <br clear="left">
  53
  54 - Select digests for triage
  55   - Digests will be listed in order with largest difference first
  56   - Click to open the digest view with detailed information
  57
  58 <img src=../Digests.png style="margin-left:40px" align="left" width="780"/>
  59 <br clear="left">
  60
  61 - Open bugs for identified owner(s)
  62   - The digest detail view has a link to open a bug from the UI
  63   - Via the Gold UI or when manually entering a bug, copy the full URL of single
  64     digest into a bug report
  65   - The URL reference to the digest in Issue Tracker will link the bug to the
  66     digest in Gold
  67
  68 <img src="../IssueHighlight.png" style="margin-left:60px" align="left" width="720" border=1/>
  69 <br clear="left">
  70
  71 <br>
  72
  73 Future improvements:
  74
  75 - Smarter, more granular blamelist
  76
  77 <br>
  78
  79 ## Problem #2: As a developer, I need to land a CL that may change many images.
  80
  81 To find your results:
  82
  83 - Immediately following commit, access the By Blame view to find untriaged
  84   digest groupings associated with your ID
  85 - Click on one of the clusters including your CL to triage
  86 - Return to the By Blame view to walk through all untriaged digests involving
  87   your change
  88 - Note: It is not yet implemented in the UI but possible to filter the view by
  89   CL. Delete hashes in the URL to only include the hash for your CL.
  90
  91 <img src=../BlameView.png style="margin-left:30px" align="left" width="800"/>
  92 <br clear="left">
  93
  94 To rebaseline images:
  95
  96 - Access the Ignores view and create a new, short-interval (hours) ignore for
  97   the most affected configuration(s)
  98
  99 <img src=../Ignores.png style="margin-left:30px" align="left" width="800"/>
 100 <br clear="left">
 101
 102 - Click on the Ignore to bring up a search view filtered by the affected
 103   configuration(s)
 104 - Mark untriaged images as positive (or negative if appropriate)
 105 - Follow one of two options for handling former positives:
 106   - Leave former positives as-is and let them fall off with time if there is low
 107     risk of recurrence
 108   - Mark former positives as negative if needed to verify the change moving
 109     forward
 110
 111 Future improvements:
 112
 113 - Trybot support prior to commit, with view limited to your CL
 114 - Pre-triage prior to commit that will persist when the CL lands
 115
 116 <br>
 117
 118 ## Problem #3: As a developer or infrastructure engineer, I need to add a new or updated config.
 119
 120 (ie: new bot, test mode, environment change)
 121
 122 Solution today:
 123
 124 - Follow the process for rebaselining images:
 125   - Wait for the bot/test/config to be committed and show up in the Gold UI
 126   - Access the Ignores view and create a short-interval ignore for the
 127     configuration(s)
 128   - Triage the ignores for that config to identify positive images
 129   - Delete the ignore
 130
 131 Future improvements:
 132
 133 - Introduction of a new or updated test can make use of try jobs and pre-triage.
 134 - New configs may be able to use these features as well.
 135
 136 <br>
 137
 138 ## Problem #4: As a developer, I need to analyze the details of a particular image digest.
 139
 140 Solution:
 141
 142 - Access the By Test view
 143
 144 <img src=../ByTest.png style="margin-left:30px" align="left" width="800"/>
 145 <br clear="left">
 146
 147 - Click the magnifier to filter by configuration
 148 - Access the Cluster view to see the distribution of digest results
 149   - Use control-click to select and do a direct compare between data points
 150   - Click on configurations under “parameters” to highlight data points and
 151     compare
 152
 153 <img src=../ClusterConfig.png style="margin-left:30px" align="left" width="800"/>
 154 <br clear="left">
 155
 156 - Access the Grid view to see NxN diffs
 157
 158 <img src=../Grid.png style="margin-left:30px" align="left" width="800"/>
 159 <br clear="left">
 160
 161 - Access the Dot diagram to see history of commits for the trace
 162   - Each dot represents a commit
 163   - Each line represents a configuration
 164   - Dot colors distinguish between digests
 165
 166 <img src=../DotDiagram.png style="margin-left:30px" align="left" width="800"/>
 167 <br clear="left">
 168
 169 <br>
 170
 171 Future improvements:
 172
 173 - Large diff display of image vs image
 174
 175 <br>
 176
 177 ## Problem #5: As a developer, I need to find results for a particular configuration.
 178
 179 Solution:
 180
 181 - Access the Search view
 182 - Select any parameters desired to search across tests
 183
 184 <img src=../Search.png style="margin-left:30px" align="left" width="800"/>
 185 <br clear="left">