Dotdiff
Dotdiff is a very basic wrapper around imåge magick compare program which works with both Capybara and RSpec to capture and compare the images with a simple rspec matcher.
It is now also possible to snapshot a particular element on the page just by using the standard capybara finders - which once the element is found will query the browser for its dimensions and placement on the page and use that metadata to crop using chunky_png from a full page snapshot.
It can also hide certain elements via executing javascript for elements which can change with different display suchas username or user specific details, but only for full page screenshots.
Installation
Add this line to your application's Gemfile:
This is the same for JRuby platform as well (both MRI and JRuby versions of gem is uploaded)
gem 'dotdiff'
And then execute:
$ bundle
Or install it yourself as:
$ gem install dotdiff
Usage
Dependencies
First ensure to install image magick binary which is available via apt-get or brew
In your spec/spec_helper
require 'dotdiff'
If you want the rspec_matcher require the following as well
require 'dotdiff/rspec_matcher'
Configuration
In an initializer you can configure certain options example shown below within Dotdiff
DotDiff.configure do |config|
config.image_magick_diff_bin = `which compare`
config.pixel_threshold = { type: 'percent', value: 0.04 }
config. = '-metric AE'
config.image_store_path = File.join('/home', 'user', 'images')
config.xpath_elements_to_hide = ["id('main')"]
config.hide_elements_on_non_full_screen_screenshot = true
config.failure_image_path = File.join('/home', 'user', 'failure_comparisions')
end
Spec usage
For a full page screenshot you can use the below;
expect(page).to match_image('HomePage', subdir: 'Normitec')
For a specific element screenshot you can use like so;
expect(find('#login-form')).to match_image('LoginForm', subdir: 'Normitec')
The only difference for the element specific is passing a specific element in the expect parameter.
Configuration Options
| Config | Description | Example | Default | Required |
|---|---|---|---|---|
| image_magick_diff_bin | Location of the image magick compare binary file | which compare |
N/A | Yes |
| image_store_path | The root path to store the base images | File.join('/home', 'user','images') | nil | Yes |
| xpath_elements_to_hide | When taking full page screenshots it will hide elements specified that might change each time and re-shows them after the screenshot. It doesn't use this option for taking screenshots of specific elements. | ["id('main')", "//div[contains(@class, 'formy'])[1]"] | [] | No |
| hide_elements_on_non_full_screen_screenshot | When taking non full page screenshots whether to also hide elements using xpath_elements_to_hide or not hide anything at all |
true | false | No |
| failure_image_path | When a comparison occurs and the perceptual_diff binary returns a failure with the message. It will dump the new image taken for comparison to this directory. If not supplied it will not move the images from the temporary location that it is generated at. | File.join('/home', 'user','failures') | nil | No |
| pixel_threshold | This validates the output from compare is within your specified threshold_config which supports pixel or percent value | { type: 'percent', value: 0.03 } | { type: 'pixel', value: 100 } | No |
| image_magick_options | This allows you to pass some custom options to image magick | '-fuzz 10% -metric RSME' | '-fuzz 5% -metric AE' | No |
Contributing
Bug reports and pull requests are welcome on GitHub at https://github.com/jnormington/dotdiff.
License
The gem is available as open source under the terms of the MIT License.
Whats still to do
Its not fully completed yet but is usable in its current state.
- Improve the message output to extract just the fail line
- Add an integration spec