ImageDiff

Ruby image comparison library for integration with automated Selenium tests and Cucumber. Use ImageDiff to take full page snapshot images of web pages and compare them against recent screenshots from Selenium/Capybara tests.

Installation

Add this line to your application's Gemfile:

gem 'image_diff', git: 'git@github.com:ITV/image_diff.git'

And then execute:

$ bundle install

ImageDiff uses ImageMagick for screenshot manipulation, install it via HomeBrew:

brew install imagemagick

Usage

Set up your Selenium/Cucumber project as usual and add the following profiles to /config/cucumber.yml:

generate_screenshots: IMAGE_DIFF=generate
visual_regression:    IMAGE_DIFF=regression

Add ImageDiff to features/support/env.rb:

require 'image_diff'

Create a new cucumber hook to execute against tests tagged for visual testing in features/support/hooks.rb:

After '@visual_test' do |scenario|
  filename = scenario.location
  if ENV['IMAGE_DIFF'] == 'generate'
    # Take a screenshot of the current Selenium/Capybara driver window and save to /reference
    ImageDiff::PNGSnapshot.new('reference', filename).write
  else
    # Take a screenshot of the current Selenium/Capybara driver window and compare to same file in /reference folder
    # If screenshots differ then a diff.png file will be generated
    ImageDiff::PNGSnapshot.new('visual_regression', filename).compare
    ImageDiff::Differ::Results::Output.flush

    # Optional - fail the cucumber test if screenshot difference fails
    expect(ImageDiff::Differ::Results::List.instance).to(
        be_empty, 'Visual regression tests failed'
    )
  end
end

Tag any cucumber feature tests with '@visual_test' and run the cucumber profile to generate reference screenshots for the test:

$ bundle exec cucumber -p generate_screenshots -t @visual_test

Replay the test and compare the result against the reference screenshot, if they match then the test will pass if not a diff.png file highlighting the differences will be generated:

$ bundle exec cucumber -p visual_regression -t @visual_test

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/itv/imagediff.

License

The gem is available as open source under the terms of the MIT License.