Guide

Install

• Install Node.js, at least v4
• Install argus-eyes using npm:

$ npm install argus-eyes -g

Step 1: Setup config file

Before argus eyes can measure visual differences, it needs a list of pages and components. By default argus eyes expects an argus-eyes.json file in the current working directory.

The config file must be a valid JSON object, containing 3 arrays: sizes, pages and components. Sizes are simple strings. Page objects require a name, url and list of components. Components require a name and a CSS-selector. Components can optionally take a list of selectors of elements to ignore, this selector is appended to the component selector. See the Reference section for a more detailed format description.

Example config file:

{
  "sizes": ["320x480", "1280x768"],
  "pages": [ {
      "name": "homepage",
      "url": "http://localhost:3000/",
      "components": [ "navigation", "news-items" ]
    }, {
      "name": "contact",
      "url": "http://localhost:3000/contact.html",
      "components": [ "navigation" ]
    } ],
  "components": [ {
      "name": "navigation",
      "selector": ".nav"
    }, {
      "name": "news-items",
      "selector": ".news-items",
      "ignore": [ ".last-updated" ]
    } ]
}

Step 2: Take screenshots

After setting up the JSON, argus eyes can be put to work. Let's create your first set of screenshots of the components we specified. To do that, you can use the argus-eyes capture command:

$ argus-eyes capture <name>

It's best to name your set of screenshots semantically, after your current git branch for example.

Argus eyes now creates a folder called .argus-eyes/<name>/, and saves the screenshots of all components specified in the config file.

Now, you can switch branches and save another set of screenshots.

Step 3: Test for visual differences

When any 2 sets of screenshots were created, argus eyes can compare them for visual differences. Comparison is done with the argus-eyes compare command:

$ argus-eyes compare <left> <right>

If visual differences between supposedly identical components are found, a new folder is created. This folder contains images of the offending components, highlighting their differences in red.

Note: Please make sure to add '.argus-eyes' to your .gitignore!

Gitflow: Testing separate branches

Argus eyes is especially useful for checking visual regression between different branches. Say you're working on a feature branch and you want to make sure your changes have no unintended side effects:

On the feature/navigation branch:

$ argus-eyes capture feature/navigation

On the develop branch:

$ argus-eyes capture develop
$ argus-eyes compare develop feature/navigation

If any differences are found, the visual diff images are stored in .argus-eyes/diff_develop_feature-navigation/