README.md in capybara-screenshot-diff-1.6.3 vs README.md in capybara-screenshot-diff-1.7.0
- old
+ new
@@ -1,6 +1,6 @@
-[](https://travis-ci.org/donv/capybara-screenshot-diff)
+[](https://github.com/donv/capybara-screenshot-diff/actions/workflows/test.yml)
# Capybara::Screenshot::Diff
Ever wondered what your project looked like two years ago? To answer that, you
start taking screen shots during your tests. Capybara provides the
@@ -38,18 +38,18 @@
In your test class, include the `Capybara::Screenshot::Diff` module:
```ruby
class ApplicationSystemTestCase < ActionDispatch::SystemTestCase
include Capybara::Screenshot::Diff
- ...
+ # ...
end
```
-### rspec
+### RSpec
```ruby
-describe 'Permissions admin', :type => :feature, :js => true do
+describe 'Permissions admin', type: :feature, js: true do
include Capybara::Screenshot::Diff
it 'works with permissions' do
visit('/')
@@ -62,11 +62,11 @@
```ruby
# spec/feature_helper.rb
require 'capybara/screenshot/diff'
RSpec.configure do |config|
- config.include Capybara::Screenshot::Diff::TestMethods
+ config.include Capybara::Screenshot::Diff
end
```
### Taking screenshots
@@ -95,12 +95,12 @@
feature_index
welcome_index
```
To store the screen shot history, add the `doc/screenshots` directory to your
- version control system (git, svn, etc).
-
+version control system (git, svn, etc).
+
Screen shots are compared to the previously COMMITTED version of the same screen shot.
### Screenshot groups
Commonly it is useful to group screenshots around a feature, and record them as
@@ -184,25 +184,19 @@
`screenshot_section` and/or `screenshot_group` can still be overridden in each
test.
-
### Capturing one area instead of the whole page
+You can crop images before comparison to be run, by providing region to crop as `[left, top, right, bottom]` or by css selector like `body .tag`
+
```ruby
test 'the cool' do
visit '/feature'
- screenshot 'cool_element', crop: bounds('#my_element')
+ screenshot 'cool_element', crop: '#my_element'
end
-
-private
-
-def bounds(selector)
- element = evaluate_script("document.querySelector('#{selector}').getBoundingClientRect()")
- [element['left'], element['top'], element['right'], element['bottom']]
-end
```
### Multiple Capybara drivers
@@ -303,11 +297,11 @@
### Screen shot save path
By default, `Capybara::Screenshot::Diff` saves screenshots to a
`doc/screenshots` folder, relative to either `Rails.root` (if you're in Rails),
- or your current directory otherwise.
+or your current directory otherwise.
If you want to change where screenshots are saved to, then there are two
configuration options that that are relevant.
The most likely one you'll want to modify is ...
@@ -368,11 +362,10 @@
```
This will make the cursor (caret) transparent (invisible), so the blinking does not delay the screen shot.
-
### Removing focus from the active element
Another way to avoid the cursor blinking is to set the `blur_active_element` option:
```ruby
@@ -426,11 +419,11 @@
**Note:** For each increase in `shift_distance_limit` more pixels are searched for a matching color value, and
this will impact performance **severely** if a match cannot be found.
If `shift_distance_limit` is `nil` shift distance is not measured. If `shift_distance_limit` is set,
-even to `0`, shift distabnce is measured and reported on image differences.
+even to `0`, shift distance is measured and reported on image differences.
### Allowed difference size
You can set set a threshold for the differing area size for the comparison
using the `area_size_limit` option to the `screenshot` method:
@@ -450,48 +443,49 @@
### Skipping an area
Sometimes you have expected change that you want to ignore.
-You can use the `skip_area` option to the `screenshot` method to ignore an area:
+You can use the `skip_area` option with `[left, top, right, bottom]`
+or css selector like `'#footer'` or `'.container .skipped_element'` to the `screenshot` method to ignore an area:
```ruby
test 'unstable area' do
visit '/'
- screenshot 'index', skip_area: [17, 6, 27, 16]
+ screenshot 'index', skip_area: [[17, 6, 27, 16], '.container .skipped_element', '#footer']
end
```
-The arguments are [x1, y1, x2, y2] for the area you want to ignore. You can also set this globally:
+The arguments are `[left, top, right, bottom]` for the area you want to ignore. You can also set this globally:
```ruby
Capybara::Screenshot::Diff.skip_area = [0, 0, 64, 48]
```
-If you need to ignore multiple areas, you can supply an array of arrays:
+If you need to ignore multiple areas:
```ruby
-screenshot 'index', skip_area: [[0, 0, 64, 48], [17, 6, 27, 16]]
+screenshot 'index', skip_area: [[0, 0, 64, 48], [17, 6, 27, 16], 'css_selector .element']
```
### Available Image Processing Drivers
There are several image processing supported by this gem.
There are several options to setup active driver: `:auto`, `:chunky_png` and `:vips`.
* `:auto` - will try to load `:vips` if there is gem `ruby-vips`, in other cases will load `:chunky_png`
-* `:chunky_png` and `:vips` will load correspondent driver
+* `:chunky_png` and `:vips` will load correspondent driver
### Enable VIPS image processing
[Vips](https://www.rubydoc.info/gems/ruby-vips/Vips/Image) driver provides a faster comparison,
and could be enabled by adding `ruby-vips` to `Gemfile`.
If need to setup explicitly Vips driver, there are several ways to do this:
- * Globally: `Capybara::Screenshot::Diff.driver = :vips`
- * Per screenshot option: `screenshot 'index', driver: :vips`
+* Globally: `Capybara::Screenshot::Diff.driver = :vips`
+* Per screenshot option: `screenshot 'index', driver: :vips`
With enabled VIPS there are new alternatives to process differences, which easier to find and support.
For example, `shift_distance_limit` is very heavy operation. Instead better to use `median_filter_window_size`.
#### Tolerance level (vips only)
@@ -527,9 +521,27 @@
```ruby
test 'unstable area' do
visit '/'
screenshot 'index', median_filter_window_size: 2
+end
+```
+
+### Skipping stack frames in the error output
+
+If you would like to override the `screenshot` method or for some other reason would like to skip stack
+frames when reporting image differences, you can use the `skip_stack_frames` option:
+
+```ruby
+test 'test visiting the index' do
+ visit root_path
+ screenshot :index
+end
+
+private
+
+def screenshot(name, **options)
+ super(name, skip_stack_frames: 1, **options)
end
```
## Development