Gatling¶ ↑

An integrated visual RSpec matcher which makes real visual testing easy.

gem install gatling

In spec_helper.rb:

#main app
require 'gatling'

#plug and play custom rspec matcher
require 'gatling/matchers/look_like_matcher'

For Rails application, a default reference images folder will be created at spec/reference_images. This folder is root to all the reference images to be compares.

Also created are subfolders:

• /candidate - will hold candidate images which can be used as reference images

• /diff - will hold the diff images generated by failed comparison tests

• /temp - will only ever hold one screenshot at a time, used to create the cropped element

• sets how many times Gatling will try and match the element against the reference image. Handy to reduce fragility of tests due to animations and load times. Defaults to 5.

• sets the sleep time (in seconds) between match tries (requires max_no_tries > 1). Defaults to 0.5

• *Currently only available with Selenium-Webdriver / Capybara* - create reference folders based on the current Selenium driver’s browser. Allows for cross-browser visual testing.

Gatling.config do |c|
  c.reference_image_path = 'some/path'
  c.max_no_tries = 4
  c.sleep_between_tries = 5
  c.browser_folders = false
end

GATLING::CONFIGURATION will be depreciated in future versions.

Identify an element to match, for example:

@element = page.find(:css, '#button')

Use Gatling’s custom matcher (conveniently supplied in the gatling gem) and specify the reference image:

@element.should look_like('button_ref.png')

Gatling will take care of cropping the element and try and make a targeted match without the noise of the whole page.

If the matcher fails, the test will fail, an exception will be raised and both a diff image and a new candidate image will be created.

If no reference image exits, the test will still pass and a reference file will be created for future comparisons.

GATLING_TRAINER WILL BE DEPRECIATED. Gatling now saves reference files natively when files do not exists.

Gatling can be run in training mode which will create reference images where ones do not exist.

CAUTION: Trainer mode will pass all the test which rely on the Gatling custom matcher, this can mean a false green build. Please make sure you are saving ‘clean’ references

Trainer mode will not overwrite existing references. If you are updating, just delete the old reference image.

To set trainer mode, prefix rspec command line with $GATLING_TRAINER = true

Example:

$GATLING_TRAINER = true rspec spec/my_spec.rb

Imagemagick must be installed:

$sudo apt-get install imagemagick

• Check out the latest master to make sure the feature hasn’t been implemented or the bug hasn’t been fixed yet

• Check out the issue tracker to make sure someone already hasn’t requested it and/or contributed it

• Fork the project

• Start a feature/bugfix branch

• Commit and push until you are happy with your contribution

• Make sure to add tests for it. This is important so I don’t break it in a future version unintentionally.

• Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.

Copyright © 2011 Gabriel Rotbart, Amanda Koh. See LICENSE.txt for further details.