If you run juxtaposer with the --report flag, you will see the html report:

Getting Started

Step 1 Make a file in the root of your project called juxtaposer.json with the contents:

juxtaposer.json

{

"imagesDir":"test_images",

"substitutions":{

"prod":{

"query":"production"

},

"dev":{

"query":"development"

}

}

}

Step 2 Make a file in the root of your project called targets.json with the contents:

targets.json

[

{

"name":"sample_query.png",

"url":"https://www.google.com/#q={{query}}"

}

]

Step 3 Run juxtaposer --report

Step 4 Customize juxtaposer.json and targets.json

Examples

Basic Example

Create your config file:

juxtaposer.json

{

"imagesDir":"my_images",

"substitutions":{

"prod":{

"subdomain":"www",

"test_env":""

},

"dev":{

"subdomain":"testing",

"test_env":"development."

}

}

}

Specify the targets:

targets.json

[

{

"name":"photo_homepage.png",

"url":"http://{{subdomain}}.{{test_env}}example.com/login"

}

]

When you run the command $ juxtaposer, it will store the url http://www.example.com/login at my_images/baselines/photo_homepage.png and the url http://testing.development.example.com/login at my_images/samples/photo_homepage.png and then the two images are compared.

advanced example

juxtaposer.json

{

"showReport":true,

"export":true,

"targetEnv":"staging",

"baselineEnv":"production",

"substitutions":{

"production":{

"subdomain":"www"

},

"staging":{

"subdomain":"staging"

}

}

}

targets.json

[

{

"name":"excluding_two_regions.png",

"url":"http://{{subdomain}}.example.com",

"exclude":[".stats_section","#user-info"]

},

{

"name":"only_the_given_coordinates.png",

"url":"http://{{subdomain}}.example.com",

"only":[200,0,960,50]

},

{

"name":"only_the_content_div.png",

"url":"http://{{subdomain}}.example.com",

"only":"#content"

},

{

"name":"narrow_view.png",

"url":"http://{{subdomain}}.example.com",

"width":350

}

]

Environment translations

The substitution values in the config file are used to build the url. It uses the swig template engine to build the urls. Example:

For the url http://{{subdomain}}.{{test_env}}example.com
And the substitutions:

"substitutions": {

"prod":{

"subdomain":"www",

"test_env":""

},

"qa":{

"subdomain":"testing",

"test_env":"qa."

},

"dev":{

"subdomain":"testing",

"test_env":"development."

}

}

Will generate the following domains:

prod: http://www.example.com

qa: http://testing.qa.example.com

dev: http://testing.development.example.com

Note:test_env for both qa and dev in this example have trailing ..

Custom report templates

You can specify your own report template for the html report using the command line flag --report-template or with reportTemplate in the config file. The report template is rendered with the swig template language

baselineEnv

testOnly

Value boolean

Default false

If testOnly is true, it will skip the capturing of images and only compare images in the baselineDir with the images in the samplesDir. This is useful if you want to use your own scripts to capture the images.

showReport

Value boolean

Default false

Auto open the html report when run is completed. Only works on a mac for now.

reportTemplate

Value string

Default N/A

The path relative from the current directory to the html file. The template language used is swig. See the custom template section below.

export

Value boolean

Default false

Create a zip file of the images captured and the html report.

exportPath

Value: string

Default: jux-{{base_env}}-vs-{{sample_env}}-{{date}}.zip

The path and filename relative to the current working directory. The string is evaluated with the swig template language. The following values are passed passed into the path:

base_env: The name of the base env.

sample_env: The name of the sample env.

date: The timestamp of the test run in ISO format

imagesDir

Value: string

Default: test_images

The directory used to store all the images collected. It is resolved relative to the current working directory.

baselinesDir

Value: string

Default: baselines

The folder for the baseline images. It is resolved relative to the imagesDir.

samplesDir

Value: string

Default: samples

The folder for the sample images. It is resolved relative to the imagesDir.

diffsDir

Value: string

Default: diffs

The folder for the diff images. It is resolved relative to the imagesDir.

substitutions

Value: object

Default: an empty object

A key value pair of the environment names and the translation values. See the environment substitutions for more info.

command line flags

--config

Value string

Default: juxtaposer.json

Overrides the path used for loading the config file.

--env

Value: string

Overrides: targetEnv

--base-env

Value: string

Overrides: baselineEnv

--test-only

Value: boolean

Overrides: testOnly

--report

Value: boolean

Overrides: showReport

--report-template

Value: string

Overrides: reportTemplate

--export

Value: boolean

Overrides: export

--export-path

Value: string

Overrides: exportPath

Flow

Runs the prechecks

checks to make sure imagemagick is installed

ensures the directory structure is there

checks to see if it needs to capture the baseline images

Cleans up the directories

This step can be skipped with the flag --test-only

removes png's and gif's from samplesDir and diffsDir

If baseline images are going to to be captures, it removes png's from the baselinesDir

Images are captured

This step can be skipped with the flag --test-only

the baseline images are only captured if the baselinesDir is empty or the flag --base-env=SOME_VALUE is passed

The command populateCmd will be called for both the samples and the baseline images

For each target in the config file, it does the following:

Sets the size of the viewport

Captures the region if one is specified.

Records the dimentions of excluded sections.

Saves the image.

Images are tested.

Every png in baselinesDir is compared against the png of the same name in samplesDir

If a baseline images doesn't match the sample image, a series of images diffs are made in diffsDir

If there is not a sample image for a baseline image, that image is marked as skipped

Results are recored

The results are displayed in the command line

The html report is generated and saved at the path: {{imagesDir}}/{{reportPath}}

The template for the html report can be changed with the flag --report-template. The path will be relative form the working dir.

If the flag --report is passed, the html report will be opened with the command: open {{imagesDir}}/{{reportPath}}

Results are exported in a zip file

This step will only happen if the flag --export is used

The contents of imagesDir will be added to a zip file.

If you want to customize the path, you can specify a path relative to the working dir i.e. --export-path=../archives/{{data}}.zip

License

Copyright (C) 2014 by Shutterstock Images, LLC

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.