-
Notifications
You must be signed in to change notification settings - Fork 2
/
Copy pathreference.html
311 lines (297 loc) · 19.5 KB
/
reference.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<title>Argus Eyes — Reference documentation</title>
<meta name="description" content="A lightweight CLI tool for visual regression testing: Argus Eyes captures screenshots for components over time and identifies visual differences with diff images">
<meta name="keywords" content="argus eyes, testing, visual regression, regression, automated, screenshots, captures, components, differences">
<meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">
<link rel="stylesheet" href="//fonts.googleapis.com/css?family=Lato:300,400,400italic,700,700italic|Ubuntu+Mono:400,400italic,700">
<link rel="stylesheet" href="/static/css/all.css">
<link rel="apple-touch-icon" sizes="57x57" href="/static/img/favicon/apple-touch-icon-57x57.png">
<link rel="apple-touch-icon" sizes="60x60" href="/static/img/favicon/apple-touch-icon-60x60.png">
<link rel="apple-touch-icon" sizes="72x72" href="/static/img/favicon/apple-touch-icon-72x72.png">
<link rel="apple-touch-icon" sizes="76x76" href="/static/img/favicon/apple-touch-icon-76x76.png">
<link rel="apple-touch-icon" sizes="114x114" href="/static/img/favicon/apple-touch-icon-114x114.png">
<link rel="apple-touch-icon" sizes="120x120" href="/static/img/favicon/apple-touch-icon-120x120.png">
<link rel="apple-touch-icon" sizes="144x144" href="/static/img/favicon/apple-touch-icon-144x144.png">
<link rel="apple-touch-icon" sizes="152x152" href="/static/img/favicon/apple-touch-icon-152x152.png">
<link rel="apple-touch-icon" sizes="180x180" href="/static/img/favicon/apple-touch-icon-180x180.png">
<link rel="icon" type="image/png" href="/static/img/favicon/favicon-32x32.png" sizes="32x32">
<link rel="icon" type="image/png" href="/static/img/favicon/favicon-194x194.png" sizes="194x194">
<link rel="icon" type="image/png" href="/static/img/favicon/favicon-96x96.png" sizes="96x96">
<link rel="icon" type="image/png" href="/static/img/favicon/android-chrome-192x192.png" sizes="192x192">
<link rel="icon" type="image/png" href="/static/img/favicon/favicon-16x16.png" sizes="16x16">
<link rel="manifest" href="/static/img/favicon/manifest.json">
<link rel="mask-icon" href="/static/img/favicon/safari-pinned-tab.svg" color="#5bbad5">
<link rel="shortcut icon" href="/static/img/favicon/favicon.ico">
<meta name="msapplication-TileColor" content="#603cba">
<meta name="msapplication-TileImage" content="/static/img/favicon/mstile-144x144.png">
<meta name="msapplication-config" content="/static/img/favicon/browserconfig.xml">
<meta name="theme-color" content="#ffffff">
</head>
<body>
<div class="layout__container layout__container_has-aside">
<header class="layout__header">
<figure class="header-logo">
<a href="/"><img src="/static/img/argus-eyes-line.svg" alt="Argus Eyes logo"></a>
</figure>
<nav class="nav-main">
<ol>
<li><a href="/" class="nav-main__item">Home</a></li>
<li><a href="/guide.html" class="nav-main__item">Guide</a></li>
<li><a href="/reference.html" class="nav-main__item nav-main__item_is-active">Reference</a></li>
<li><a href="http://github.com/arguseyes/argus-eyes/releases" class="nav-main__item" target="_blank">Releases</a></li>
<li><a href="http://github.com/arguseyes/argus-eyes" class="nav-main__item nav-main__item_github" title="Github" target="_blank"></a></li>
</ol>
</nav>
</header>
<main class="layout__main">
<article>
<!-- start -->
<h2 id="reference">Reference</h2>
<h3 id="config">Config</h3>
<p>Argus eyes will look in the current working directory for a file named <strong><code>argus-eyes.json</code></strong>. This file contains your
sizes, pages and components. You can specify a different location file using the <strong><code>--config</code></strong> argument, as described
in <a href="#options">Options</a>.</p>
<p>The config needs to be valid <a href="http://www.json.org/">JSON</a>, and it needs to obey this format specification:</p>
<pre><code class="lang-js">{
<span class="hljs-string">"sizes"</span>: [
<span class="hljs-built_in">String</span> <span class="hljs-comment">// Size string, example: "1024x768"</span>
<span class="hljs-comment">// ...</span>
],
<span class="hljs-string">"pages"</span>: [
{
<span class="hljs-string">"name"</span>: <span class="hljs-built_in">String</span>, <span class="hljs-comment">// Identifier, used in filenames</span>
<span class="hljs-string">"url"</span>: <span class="hljs-built_in">String</span>, <span class="hljs-comment">// Valid URL</span>
<span class="hljs-string">"components"</span>: [
<span class="hljs-built_in">String</span> <span class="hljs-comment">// Component identifiers</span>
<span class="hljs-comment">// ...</span>
],
<span class="hljs-string">"wait-for-delay"</span>: <span class="hljs-built_in">Number</span>, <span class="hljs-comment">// [Optional] Number of milliseconds to wait</span>
<span class="hljs-string">"wait-for-script"</span>: <span class="hljs-built_in">String</span>, <span class="hljs-comment">// [Optional] Path to JS file with function body</span>
<span class="hljs-string">"run-script"</span>: <span class="hljs-built_in">String</span> <span class="hljs-comment">// [Optional] Path to JS file with script</span>
}
<span class="hljs-comment">// ...</span>
],
<span class="hljs-string">"components"</span>: [
{
<span class="hljs-string">"name"</span>: <span class="hljs-built_in">String</span>, <span class="hljs-comment">// Identifier, used in page objects and filenames</span>
<span class="hljs-string">"selector"</span>: <span class="hljs-built_in">String</span>, <span class="hljs-comment">// CSS selector, to clip the screenshot</span>
<span class="hljs-string">"ignore"</span>: [ <span class="hljs-comment">// [Optional] Array of excluded child elements</span>
<span class="hljs-built_in">String</span> <span class="hljs-comment">// CSS selector, to `display:none` a child element</span>
<span class="hljs-comment">// ...</span>
],
<span class="hljs-string">"wait-for-delay"</span>: <span class="hljs-built_in">Number</span>, <span class="hljs-comment">// [Optional] Number of milliseconds to wait</span>
<span class="hljs-string">"wait-for-script"</span>: <span class="hljs-built_in">String</span>, <span class="hljs-comment">// [Optional] Path to JS file with function body</span>
<span class="hljs-string">"run-script"</span>: <span class="hljs-built_in">String</span> <span class="hljs-comment">// [Optional] Path to JS file with script</span>
}
<span class="hljs-comment">// ...</span>
],
<span class="hljs-string">"wait-for-delay"</span>: <span class="hljs-built_in">Number</span>, <span class="hljs-comment">// [Optional] Number of milliseconds to wait</span>
<span class="hljs-string">"wait-for-script"</span>: <span class="hljs-built_in">String</span>, <span class="hljs-comment">// [Optional] Path to JS file with function body</span>
<span class="hljs-string">"run-script"</span>: <span class="hljs-built_in">String</span>, <span class="hljs-comment">// [Optional] Path to JS file with script</span>
<span class="hljs-string">"credentials"</span>: <span class="hljs-built_in">String</span>, <span class="hljs-comment">// [Optional] HTTP Basic auth, example: "john:secret"</span>
<span class="hljs-string">"phantomjs-flags"</span>: [ <span class="hljs-comment">// [Optional] Array of PhantomJS flags</span>
<span class="hljs-built_in">String</span> <span class="hljs-comment">// PhantomJS CLI flag</span>
<span class="hljs-comment">// ...</span>
]
}
</code></pre>
<p>By default, argus eyes takes the screenshots after the <code>window.onload</code> event. When parts of your site are still being
loaded after that, you'll need to tell argus eyes what to wait for. This way you can make sure that everything has
finished loading, rendering and animating at the moment the screenshot is taken.</p>
<p>To simply wait for a fixed time, use <code>wait-for-delay</code>. For more complex conditions, you can write JavaScript that
returns a truthy value whenever the page is ready: see <code>wait-for-script</code>. If you've got any one-time actions such as
components to activate or dialogs to close, you should use <code>run-script</code>.</p>
<p>You are allowed to specify <code>wait-for-delay</code>, <code>wait-for-script</code> and <code>run-script</code> on 3 levels: global, page and component.
The highest delay is executed first, then all <code>wait-for-script</code> files in order, then all <code>run-script</code> files.</p>
<p><strong>Be advised</strong>: There's a global timeout of 10 seconds on the internal PhantomJS script, the screenshots of all
components on a page should be taken within that time.</p>
<h4 id="wait-for-delay">Wait for delay</h4>
<p>This will delay taking the screenshots, specify the milliseconds as a JavaScript number. When multiple delays are found
only the highest delay is executed, the others are discarded.</p>
<h4 id="wait-for-script">Wait for script</h4>
<p>You can specify a JavaScript function body to tell argus eyes whenever the page and it's components are finished loading.
The <code>wait-for-script</code> string must contain a filename. If a relative path is given, it's relative to your config file.</p>
<p>Multiple scripts will be executed in the order: global, page, component.</p>
<p>The contents of the script can be seen as a function body, without the <code>function() {</code> and <code>}</code> parts around it. You are
required to return a truthy value to indicate argus eyes can take the screenshot. Your function is <strong>invoked
continuously</strong> until it returns something truthy, so be careful with saving state.</p>
<p>Internally, the contents of the file are passed as a string to the
<a href="http://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function"><code>Function()</code> constructor</a>,
thus an entire function body as a string is expected, and multiple lines are allowed.</p>
<p><strong>Example:</strong></p>
<pre><code class="lang-json">{ <span class="hljs-attr">"wait-for-script"</span>: <span class="hljs-string">"scripts/page-finished-loading.js"</span> }
</code></pre>
<p><strong>scripts/page-finished-loading.js:</strong></p>
<pre><code class="lang-js"><span class="hljs-keyword">var</span> isFinished = <span class="hljs-built_in">document</span>.body.hasAttribute(<span class="hljs-string">'data-finished-loading'</span>);
<span class="hljs-keyword">return</span> isFinished;
</code></pre>
<h4 id="run-script">Run script</h4>
<p>The <code>run-script</code> option differs from <code>wait-for-script</code> in that it's only executed once, after any <code>wait-for-script</code>
and <code>wait-for-delay</code>.</p>
<p>Multiple scripts will be executed in the order: global, page, component.</p>
<p>Internally, the contents of the file are passed as a string to the
<a href="http://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function"><code>Function()</code> constructor</a>,
thus an entire function body as a string is expected, and multiple lines are allowed.</p>
<p><strong>Example:</strong></p>
<pre><code class="lang-json">{ <span class="hljs-attr">"run-script"</span>: <span class="hljs-string">"scripts/component-search-open.js"</span> }
</code></pre>
<p><strong>scripts/component-search-open.js:</strong></p>
<pre><code class="lang-js"><span class="hljs-keyword">var</span> search = <span class="hljs-built_in">document</span>.querySelector(<span class="hljs-string">'.header__search'</span>);
search.classList.add(<span class="hljs-string">'.header__search_is-open'</span>);
</code></pre>
<h4 id="credentials">Credentials</h4>
<p>It's possible to specify credentials to be used as HTTP Basic authentication. A string with the username and password
separated by a colon (<code>:</code>) is expected.</p>
<p><strong>Example:</strong></p>
<pre><code class="lang-json">{ <span class="hljs-attr">"credentials"</span>: <span class="hljs-string">"john:secret"</span> }
</code></pre>
<h4 id="phantomjs-flags">PhantomJS flags</h4>
<p>If you need to specify any PhantomJS commandline flags, it's possible to do so as an array of strings. See the official
<a href="http://phantomjs.org/api/command-line.html">PhantomJS CLI documentation</a> for all supported CLI options. If any relative
paths are given, they're relative to your config file.</p>
<p><strong>Example:</strong></p>
<pre><code class="lang-json">{ <span class="hljs-attr">"phantomjs-flags"</span>: [<span class="hljs-string">"--load-images=false"</span>] }
</code></pre>
<h3 id="usage">Usage</h3>
<h4 id="capture">Capture</h4>
<p>Run argus eyes and save all the screenshots under <strong><code>.argus-eyes/<name>/</code></strong></p>
<h4 id="compare">Compare</h4>
<p>Compare the two sets of screenshots, creating overlay-images and reporting any difference. The process will exit with
code 0 when no significant differences were found, code 1 when differences were found.</p>
<h4 id="configtest">Configtest</h4>
<p>Run a config file syntax and test. It parses the config file and either reports <em>Config valid</em> or detailed information
about the error.</p>
<h3 id="options">Options</h3>
<p>Argus eyes can take several optional arguments on the CLI. Because <code>capture</code> and <code>compare</code> take positional arguments, any
of these options must be placed last.</p>
<h4 id="config-file">Config file</h4>
<p><em>Default:</em> <strong><code>argus-eyes.json</code></strong></p>
<p>Use a different config file.</p>
<pre><code class="lang-bash">$ argus-eyes capture feature/navigation --config=config.json
</code></pre>
<h4 id="threshold">Threshold</h4>
<p><em>Default:</em> 0</p>
<p>Set the threshold for comparison differences, expects a percentage between 0 and 100. If the difference between 2 files
is bigger than this percentage, it will be treated as different and reported as such.</p>
<p>When comparing screenshots, argus eyes checks if all pixels in screenshots are identical. The difference is calculated
by dividing the number of different pixels by the total number of pixels, giving a percentage. The image is considered
different when this percentage exceeds the threshold percentage.</p>
<p><strong>Be advised</strong>: You can <a href="#config">exclude html elements</a> from being captured! You might want to look into that before
increasing the threshold, since that will also increase the chance of unintended changes getting through.</p>
<pre><code class="lang-bash">$ argus-eyes compare develop feature/navigation --threshold=10
</code></pre>
<h4 id="concurrency">Concurrency</h4>
<p><em>Default:</em> 10</p>
<p>Set the number of PhantomJS instances to run in parallel. This must be a number between 1 and 100. A single PhantomJS
instance is used for every page, not for every component. Screenshots of components are captured synchronously.</p>
<p><strong>Be advised</strong>: At this moment only the <a href="#capture">Capture</a> uses this option, since PhantomJS is the biggest performance
hit. The <a href="#compare">Compare</a> action might be using this in the future as well.</p>
<pre><code class="lang-bash">$ argus-eyes capture feature/navigation --concurrency=25
</code></pre>
<p><strong>Be advised</strong>: A higher concurrency isn’t always the better option. Be careful with increasing the concurrency,
PhantomJS takes a lot of memory and it will affect the performance negatively if you run out of memory.</p>
<h4 id="base">Base</h4>
<p><em>Default:</em> <strong><code>.argus-eyes</code></strong></p>
<p>Use a different base directory for storing the screenshots and comparison results.</p>
<pre><code class="lang-bash">$ argus-eyes capture develop --base==visual-regression
</code></pre>
<h4 id="verbose">Verbose</h4>
<p>Turn on verbose output. All output is prefixed with a date string in simplified ISO 8601 format.</p>
<pre><code class="lang-bash">$ argus-eyes compare develop feature/navigation --verbose
</code></pre>
<h4 id="no-color">No color</h4>
<p>Turn off colored output. Output is colored by default.</p>
<pre><code class="lang-bash">$ argus-eyes capture develop --no-color
</code></pre>
<h4 id="help">Help</h4>
<p>Print usage information.</p>
<pre><code class="lang-bash">$ argus-eyes --help
</code></pre>
<h4 id="version">Version</h4>
<p>Print version.</p>
<pre><code class="lang-bash">$ argus-eyes --version
</code></pre>
<!-- end -->
</article>
</main>
<aside class="layout__aside">
<nav class="nav-aside">
<ol>
<li class="nav-aside_lvl1">
<a href="#reference">Reference</a>
</li>
<li class="nav-aside_lvl2">
<a href="#config">Config</a>
</li>
<li class="nav-aside_lvl3">
<a href="#wait-for-delay">Wait for delay</a>
</li>
<li class="nav-aside_lvl3">
<a href="#wait-for-script">Wait for script</a>
</li>
<li class="nav-aside_lvl3">
<a href="#run-script">Run script</a>
</li>
<li class="nav-aside_lvl3">
<a href="#credentials">Credentials</a>
</li>
<li class="nav-aside_lvl3">
<a href="#phantomjs-flags">PhantomJS flags</a>
</li>
<li class="nav-aside_lvl2">
<a href="#usage">Usage</a>
</li>
<li class="nav-aside_lvl3">
<a href="#capture">Capture</a>
</li>
<li class="nav-aside_lvl3">
<a href="#compare">Compare</a>
</li>
<li class="nav-aside_lvl3">
<a href="#configtest">Configtest</a>
</li>
<li class="nav-aside_lvl2">
<a href="#options">Options</a>
</li>
<li class="nav-aside_lvl3">
<a href="#config-file">Config file</a>
</li>
<li class="nav-aside_lvl3">
<a href="#threshold">Threshold</a>
</li>
<li class="nav-aside_lvl3">
<a href="#concurrency">Concurrency</a>
</li>
<li class="nav-aside_lvl3">
<a href="#base">Base</a>
</li>
<li class="nav-aside_lvl3">
<a href="#verbose">Verbose</a>
</li>
<li class="nav-aside_lvl3">
<a href="#no-color">No color</a>
</li>
<li class="nav-aside_lvl3">
<a href="#help">Help</a>
</li>
<li class="nav-aside_lvl3">
<a href="#version">Version</a>
</li>
</ol>
</nav>
</aside>
</div>
<script>
(function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
(i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
})(window,document,'script','//www.google-analytics.com/analytics.js','ga');
ga('create', 'UA-4923292-4', 'auto');
ga('send', 'pageview');
</script>
</body>
</html>