Rspec::Visual
RSpec plugin for writing "visual" tests: tests that look for changes in the applications's look by comparing screenshots on current branch to the latest 'stable' screenshots
Installation and Usage
Step 1 - Installation
Add this line to your application's Gemfile:
gem 'rspec-visual'
And then execute:
$ bundle
Or install it yourself as:
$ gem install rspec-visual
Step 2 - Configuration
Configure rspec-visual
with the folder for "stable" screenshots (they will
be persisted in version control), folder for temporary screenshots, and run capybara
setup:
# spec/support/rspec-visual.rb
Rspec::Visual::Configuration.configure do |config|
config.screenshot_folder = Rails.root.join('tmp')
config.stable_screenshot_folder = Rails.root.join('docs/visual')
config.
end
Step 3 - Writing tests
Write some visual tests (make sure to tag them with visual: true
)
using following steps:
- in your test, visit the page that you want to check
- take the screenshot using
take_screenshot
helper and passing it page and example - use
look_like
matcher for assertion
# spec/features/visual/home_page_spec.rb
require 'rails_helper'
describe 'home page', type: :feature, visual: true do
it 'home_page' do |example|
visit '/'
take_screenshot(page, example)
should look_like example.description
end
end
Step 4 - Checking the result
First run
No failures will occur. Screenshots will be saved in the "stable" folder that you defined in "Configure" step.
Consequent runs
Screenshots from all "visual" tests will be matched against ones in "stable" folder.
In case there is a difference, like so:
"Stable" screenshot
Screenshot with changes (banner missing)
Diff file (diff area is highlighted in red)
The test will fail and difference file will be generated in
Rspec::Visual::Configuration.screenshot_folder
:
Also, failure message will say:
Failures:
1) home page home_page
Failure/Error: should look_like example.description
expected /path/to/tmp/home_page.png to look like /path/to/docs/visual/home_page.png
If you intended home_page to look diffrently, please copy over /path/to/tmp/home_page.png into /path/to/docs/visual
# ./spec/features/visual/home_page_visual_spec.rb:10:in `block (2 levels) in <top (required)>'
Please read the failure message carefully, and if you indeed wanted the page to change than manually copy now-correct screenshot to the "stable" folder in order for specs to pass
GOTCHAS
- depends on
rspec, capybara, poltergeist, phantomJS
and imagemagick - May conflict with
VCR
, to overcome use:ruby VCR.configure do |c| c.ignore_localhost = true end
- If you want to check the app that is NOT localhost, use Capybara config like so:
RSpec.configure do |config|
default = Capybara.server_port
config.before(:example, :visual => :true) do
Capybara.run_server = false
Capybara.server_port = 80
Capybara.app_host = 'http://stage.myapp.com'
end
config.after(:example, :visual => :true) do
Capybara.run_server = true
Capybara.server_port = default
end
end
Contributing
TODO
- add ability to take screenshots in different browsers
- add ability to take screenshots in different viewports
- add ability to configure 'similarity' percentage
- add ability to test certain areas of the page
- add test coverage
- expand beyond
poltergeist
, tryselenium-webkit
- Fork it ( https://github.com/[my-github-username]/rspec-visual/fork )
- Create your feature branch (
git checkout -b my-new-feature
) - Commit your changes (
git commit -am 'Add some feature'
) - Push to the branch (
git push origin my-new-feature
) - Create a new Pull Request