= Gatling

Gatling Comparison allows one to build an Rspec / Capybara custom matcher comparing a :css or :xpath element to a referenced screenshot.

-------------------------------------

=== Installation:

  gem install gatling

In spec_helper.rb :

  #main app
  require 'gatling'

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

=== Usage:

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 fail, an exception will be raised and a candidate will be created which can be used as a reference.

-------------------------------------

=== The path config:

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

==== For non-Rails apps or just to change the root reference folder specify in spec_help:

  Gatling::Configuration.reference_image_path = "my custom path"


-------------------------------------

=== Training mode:

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

<b>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</b>

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

-------------------------------------

==== Non-gem dependencies:

Imagemagick must be installed: 

  $sudo apt-get install imagemagick

-------------------------------------


== Contributing to gatling
 
* 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

Copyright (c) 2011 Gabriel Rotbart, Amanda Koh. See LICENSE.txt for
further details.