blob: 8d7369a87c62c4bd7660dbb3e30c0e0b856b0c4b [file] [log] [blame]
<!DOCTYPE html>
<html>
<head>
<title>Gold Help</title>
<link rel="shortcut icon" href="/res/img/favicon.ico">
</head>
<body>
<gold-scaffold-sk>
<h1>What is Gold?</h1>
<p>
Gold is a tool to help track and manage the output of visual tests over a range of commits.
</p>
<h2>Overview and Vocabulary</h2>
<p>
A <dfn>test</dfn> is a bit of code that produces a PNG image which is uploaded to Gold for
cataloging. The images uploaded to Gold are uniquely identified by a hash digest of their pixel
content (and potentially other metadata like colorspace); thus the term <dfn>digest</dfn> is
frequently used as a synonym of image. Digests are "triaged" to be correct (positive) or
incorrect (negative); this is generally done by a human inspecting the digests. A digest that
has not been marked positive or negative is said to be "untriaged" and generally means that
a test has started producing different output (and a human should check if it's correct).
</p>
<p>
When a digest is uploaded to Gold, it is tagged with a number of key/value pairs.
These keys (frequently called <dfn>params</dfn>) are generally used to label how a digest was
produced, for example OS=Android or GPU=Nvidia770GTX. Params can be arbitrary and Gold will
automatically identify and process any new params produced by a test - no server-side
pre-configuration is necessary. There are two special keys, one for the "name" of the test and
the other is "source_type" (aka corpus). Data in Gold tends to be grouped first by corpus, and
then by test.
</p>
<p>
A Gold <dfn>trace</dfn> refers to all digests seen belonging to a unique set of params. These
traces are visualized throughout Gold as lines of colored dots where a color refers to a
specific digest. A trace belongs to exactly one test in exactly one corpus. A trace (or test)
is allowed to have multiple positive digests; in practice this happens due to things like
nondeterminism in anti-aliasing algorithms for certain GPUs.
</p>
<p>
To keep processing tractable, Gold only focuses on the last N commits for which it has seen
data. N is generally between 200 and 500 depending on settings for an individual instance.
</p>
<h2>Pages on Gold</h2>
<h3>By Blame (default page)</h3>
<p>
On the By Blame page, Gold shows a set of recent commits that Gold believes have first
introduced on or more untriaged digests. There are links on this page that will lead to
the Search Page showing all untriaged digests and the Details page showing details about
individual digests.
</p>
<h3>Search</h3>
<p>
This is one of Gold's most powerful pages, as it allows one to search and filter over all
the input Gold has processed. By default, it will show traces that have untriaged digests
"at head", that is to say, traces which have most recently produced an unseen image. These
traces are grouped together by digest, so if multiple traces output the same digest (for
example, a Release and a Debug build), they will be closer together. Digests will automatically
be compared to another digest from the same test; in fact, the most similar digest.
</p>
<p>
It is common to triage digests on the search page. Additionally, there is a zoom button that
can allow for a closer side-by-side view of the difference between a digest and another digest.
When zoomed in, a common keyboard shortcut "u" can be used to jump to the largest difference.
</p>
<h3>Details</h3>
<p>
The details page shows information about one digest and any traces the produce it.
</p>
<!-- TODO(kjlubick) more about the other pages -->
</gold-scaffold-sk>
</body>
</html>