Getting started !

Abstract

Eagle uses a set of modules to detect visual regressions on your website or your webapp. It is designed to operate with Intern by adding specific commands to the Leadfoot Command object. Thus, you will be able to test visual regressions on PC as well as on smartphones and tablets.

In following sections, we provide tools and explanations to easily set up a truly working environment and directly start our Hello World test.

Initialize project

Setup automatically an environment (Debian)

Following instructions create a debian virtual machine from a windows host

Here is the VM technical details:

Debian 7.6 32 bits
With Gnome graphical interface
Latest Chromium
Chromedriver 2.10
Samba sharing (full anonymous access)
Installed packages
- NodeJs, Grunt
- Eagle dependencies (libcairo2-dev, imagemagick)

Install following components:

Latest version of VirtualBox
Latest version of Vagrant
Retrieve DevOps files to mount your environment (optional)

Be careful if you just installed VirtualBox, check and change default machine folder to have enough disk space (File>Preferences>General>Default Machine Folder)

Unzip devops.zip archive

Execute a shell in administrator mode. Go to directory where you extracted archive and launch VM provisionning like this :

vagrant up

It could take a while, between 30 min to 1 hour.

After installation, you can open SSH session with these informations:

server: localhost:2222
login: vagrant
password: vagrant

For information, root password is

vagrant

Or setup manually dependencies

If you choose to install Eagle by your own way, you need to install few dependencies:

You will also need a browser and its associated WebDriver (example : Chrome and Chromedriver)

Initialize your project

On your environment freshly installed, create a directory and go in it.

mkdir <your project folder>
cd <your project folder>

Retrieve and install latest version of Eagle and Intern in your project directory:

npm install eagle-js intern

Intern configuration file

Copy the default configuration file from intern and set the suite(s) you want to test:

cp ./node_modules/intern/tests/example.intern.js config.js

And edit config.js like this:

/* config.js file */

    // ...

    suites: ['all.js']

    // ...

Write your first test !

In order to run a test, you need to use the suite file specified in your config.js file. It regroups all tests you want to run and launches them as you need.
You can write your own file or use our simple example:

Suite example

1 define([
2     './eagletest'
3 ], function (eagleTest) {
4     eagleTest();
5 });

Once your suite is created, you need to write the test itself.

A test is composed of 4 parts

The dependencies declaration: It's the place to import modules or custom libraries (line 1 to 5 of next example)
The setup function: Where you can prepare your test environment en specify which remote browser and WebDriver you want to use(line 10 to 26)
Your test function(s): That's the main function(s) where you write your test(s) (line 27 to 31)
The teardown function: It's used to close the browser and to do specific actions after test(s) (line 32 to 34)

As you can see in the following example, it's quite simple.

First example

 1 define([ // Declare your modules
 2     'intern!object',
 3     'intern/dojo/node!leadfoot/Server',
 4     'intern/dojo/node!eagle-js',
 5 	'intern/dojo/Deferred'
 6 ], function (registerSuite, Server, Eagle, Deferred) {
 7     return function() {
 8         var server, session, eagle;
 9         registerSuite({
10             name: 'Eagle_Hello_World',
11             setup: function () { // Prepare your environment
12                 server = new Server('http://localhost:9515/');
13                 session = server.createSession({
14                     'browserName': 'chrome',
15                     'platform': 'linux'
16                 });
17                 return session
18                         .then(function(session){
19                             eagle = new Eagle(session);
20                             return eagle
21                                     .initConfig({
22                                         url:'http://orange.jobs/jobs/search.do',
23                                         dimensions: {x:1280, y:1024}
24                                     }, Deferred)
25                                     .setup();
26                         });
27             },
28             'Open_app' : function () { // Make your test
29                 return eagle
30                         .sleep(2000)
31                         .captureElementByCssSelector('body','Screenshots/Orange','body');
32             },
33             teardown: function () { // Do stuff at the end of test
34                 eagle.quit();
35             }
36         });
37     };
38 });

Just try our full example to see how it works:

Hello World example

 1 define([
 2     'intern!object',
 3     'intern/dojo/node!leadfoot/Server',
 4     'intern/dojo/node!eagle-js',
 5 	'intern/dojo/Deferred'
 6 ], function (registerSuite, Server, Eagle, Deferred) {
 7     return function() {
 8         var server, session, eagle;
 9         registerSuite({
10             name: 'Eagle_Hello_World',
11             setup: function () {
12                 server = new Server('http://localhost:9515/');
13                 session = server.createSession({
14                     'browserName': 'chrome',
15                     'platform': 'linux'
16                 });
17                 return session
18                         .then(function(session){
19                             eagle = new Eagle(session);
20                             return eagle
21                                     .initConfig({
22                                         url:'http://orange.jobs/jobs/search.do',
23                                         dimensions: {x:1280, y:1024}
24                                     }, Deferred)
25                                     .setup();
26                         });
27             },
28             'Open_app' : function () { /* Check open */
29                 return eagle
30                         .sleep(2000)
31                         .captureElementByCssSelector('body','Screenshots/Orange','body');
32             },
33             'Type-Search' : function () { /* type and search engineer jobs */
34                 return eagle
35                         .findByCssSelector('.inpt input')
36                         .type('engineer')
37                         .end()
38                         .blurActiveElement()
39                         .findByCssSelector('.inpt span')
40                         .click()
41                         .end()
42                         .sleep(2000)
43                         .captureElementByCssSelector('.jobform-ui','Screenshots/Orange','search-form')
44                         .captureElementByCssSelector('.joblist','Screenshots/Orange','results');
45             },
46             'Open_first_result' : function () { /* Open and check first result */
47                 return eagle
48                         .findByCssSelector('.joblist-list li')
49                         .click()
50                         .end()
51                         .sleep(2000)
52                         .captureElementByCssSelector('.joboffer','Screenshots/Orange','job-offer');
53             },
54             'Open_details' : function () { /* Open and check job offer details */
55                 return eagle
56                         .findById('arrow-next')
57                         .click()
58                         .end()
59                         .sleep(3000)
60                         .captureFullScreenShot('Screenshots/Orange','job-details');
61             },
62             'Back_to_app' : function () { /* Come back to main page */
63                 return eagle
64                         .findById('arrow-prev')
65                         .click()
66                         .end()
67                         .sleep(2000);
68             },
69             teardown: function () {
70                 eagle.quit();
71             }
72         });
73     };
74 });

Or you can make your own test by using commands described in the documentation.

Run your test

First, on graphical interface, open a terminal and start the chromedriver

./chromedriver

Then, to run your test, you need to be in your project directory, then simply run this command:

node node_modules/intern/client.js --config=config.js

Generate reference picture

During the first run, each capture will be saved as reference with a -REF.png suffix. Then, next runs will always compare the REF image with the LAST image. When a difference is found, a third image is generated as DIFF.

To re-generate a REF image, just delete it and a new one will be created on the next run.

Save references on SVN (optional)

Eagle explorer helps you to

View easily reference, current and differential pictures
Save on SVN referential pictures
Delete from SVN referential pictures

To run Eagle Explorer, check explorer configuration file (<PROJECT DIRECTORY>/node_modules/eagle-js/explorer/config.js )

 1 // path where screenshots are saved
 2 workingPath: '<your directory path>',
 3 // svn path where screenshots are saved
 4 repoPath: '<your svn path>',
 5 port: 3001,
 6 svn: {
 7     username: '<svn username>',
 8     password: '<svn password>',
 9     // Watch code in explorer.js to know how to encrypt your path (decrypt method at the end of the file)
10     encryptedPassword: '<svn encrypted password>'
11 }

And set up correctly these variables

workingPath
repoPath
port : explorer HTTP port
And svn variables (username, password, or encryptedPassword if needed)

Install Eagle Explorer dependencies and launch it

cd node_modules/eagle-js/explorer && npm install
node explorer.js

Eagle Explorer is launched, open a browser on explorer url and you can now navigate and manage easily referential pictures on SVN.

Test your scenario

To be sure your test is working, you should edit a REF image and change anything in it (at least one pixel). It will trigger an error on the next run.

Generate test reports

There are many reports available.
By default, console report is used.
For example, command below generate jUnit and console report

node node_modules/intern/client.js --config=config.js --reporters=junit --reporters=console