capybara-screenshot-diff 1.6.2 → 1.8.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (58) hide show
  1. checksums.yaml +4 -4
  2. data/Rakefile +29 -0
  3. data/capybara-screenshot-diff.gemspec +6 -3
  4. data/gems.rb +8 -2
  5. data/lib/capybara/screenshot/diff/browser_helpers.rb +102 -0
  6. data/lib/capybara/screenshot/diff/cucumber.rb +11 -0
  7. data/lib/capybara/screenshot/diff/difference.rb +63 -0
  8. data/lib/capybara/screenshot/diff/drivers/base_driver.rb +42 -0
  9. data/lib/capybara/screenshot/diff/drivers/chunky_png_driver.rb +193 -252
  10. data/lib/capybara/screenshot/diff/drivers/utils.rb +25 -0
  11. data/lib/capybara/screenshot/diff/drivers/vips_driver.rb +65 -100
  12. data/lib/capybara/screenshot/diff/drivers.rb +16 -0
  13. data/lib/capybara/screenshot/diff/image_compare.rb +138 -154
  14. data/lib/capybara/screenshot/diff/os.rb +1 -1
  15. data/lib/capybara/screenshot/diff/region.rb +86 -0
  16. data/lib/capybara/screenshot/diff/screenshot_matcher.rb +128 -0
  17. data/lib/capybara/screenshot/diff/screenshoter.rb +136 -0
  18. data/lib/capybara/screenshot/diff/stabilization.rb +0 -210
  19. data/lib/capybara/screenshot/diff/stable_screenshoter.rb +106 -0
  20. data/lib/capybara/screenshot/diff/test_methods.rb +57 -63
  21. data/lib/capybara/screenshot/diff/vcs.rb +48 -21
  22. data/lib/capybara/screenshot/diff/version.rb +1 -1
  23. data/lib/capybara/screenshot/diff.rb +38 -35
  24. data/sig/capybara/screenshot/diff/diff.rbs +28 -0
  25. data/sig/capybara/screenshot/diff/difference.rbs +33 -0
  26. data/sig/capybara/screenshot/diff/drivers/base_driver.rbs +63 -0
  27. data/sig/capybara/screenshot/diff/drivers/browser_helpers.rbs +36 -0
  28. data/sig/capybara/screenshot/diff/drivers/chunky_png_driver.rbs +89 -0
  29. data/sig/capybara/screenshot/diff/drivers/utils.rbs +13 -0
  30. data/sig/capybara/screenshot/diff/drivers/vips_driver.rbs +25 -0
  31. data/sig/capybara/screenshot/diff/image_compare.rbs +93 -0
  32. data/sig/capybara/screenshot/diff/os.rbs +11 -0
  33. data/sig/capybara/screenshot/diff/region.rbs +43 -0
  34. data/sig/capybara/screenshot/diff/screenshot_matcher.rbs +60 -0
  35. data/sig/capybara/screenshot/diff/screenshoter.rbs +48 -0
  36. data/sig/capybara/screenshot/diff/stable_screenshoter.rbs +29 -0
  37. data/sig/capybara/screenshot/diff/test_methods.rbs +39 -0
  38. data/sig/capybara/screenshot/diff/vcs.rbs +17 -0
  39. metadata +30 -25
  40. data/.gitattributes +0 -4
  41. data/.github/workflows/lint.yml +0 -25
  42. data/.github/workflows/test.yml +0 -120
  43. data/.gitignore +0 -12
  44. data/.standard.yml +0 -12
  45. data/CONTRIBUTING.md +0 -22
  46. data/Dockerfile +0 -60
  47. data/README.md +0 -555
  48. data/bin/bundle +0 -114
  49. data/bin/console +0 -15
  50. data/bin/install-vips +0 -11
  51. data/bin/rake +0 -27
  52. data/bin/setup +0 -8
  53. data/bin/standardrb +0 -29
  54. data/gemfiles/rails52.gemfile +0 -6
  55. data/gemfiles/rails60_gems.rb +0 -8
  56. data/gemfiles/rails61_gems.rb +0 -7
  57. data/gemfiles/rails70_gems.rb +0 -7
  58. data/tmp/.keep +0 -0
data/Dockerfile DELETED
@@ -1,60 +0,0 @@
1
- # Usage:
2
- #
3
- # $ docker build . -t csd
4
- # $ docker run -v $(pwd):/app -ti csd rake test
5
-
6
- ARG RUBY_VERSION=2.7.2
7
-
8
- FROM circleci/ruby:2.7.2-node-browsers
9
-
10
- RUN \
11
- # Install dependencies
12
- sudo apt-get update && \
13
- DEBIAN_FRONTEND=noninteractive sudo apt-get install -y \
14
- automake \
15
- build-essential \
16
- curl \
17
- fftw3-dev \
18
- gettext \
19
- gobject-introspection \
20
- gtk-doc-tools \
21
- libexif-dev \
22
- libfftw3-dev \
23
- libgif-dev \
24
- libglib2.0-dev \
25
- libgsf-1-dev \
26
- libgtk2.0-dev \
27
- libmagickwand-dev \
28
- libmatio-dev \
29
- libopenexr-dev \
30
- libopenslide-dev \
31
- liborc-0.4-dev \
32
- libpango1.0-dev \
33
- libpoppler-glib-dev \
34
- librsvg2-dev \
35
- libtiff5-dev \
36
- libwebp-dev \
37
- libxml2-dev \
38
- swig
39
-
40
-
41
- WORKDIR /app
42
- RUN sudo chmod a+w -R /app
43
-
44
- ADD ./bin/install-vips /app/bin/
45
- RUN sudo /app/bin/install-vips
46
-
47
- ADD ./lib/capybara/screenshot/diff/version.rb /app/lib/capybara/screenshot/diff/
48
- ADD ./capybara-screenshot-diff.gemspec /app/
49
- ADD ./gems.rb /app/
50
-
51
- RUN bundle install
52
-
53
- RUN \
54
- # Clean up
55
- sudo apt-get remove -y curl automake build-essential && \
56
- sudo apt-get autoremove -y && \
57
- sudo apt-get autoclean && \
58
- sudo apt-get clean && \
59
- sudo rm -rf /var/lib/apt/lists/* /tmp/* /var/tmp/*
60
-
data/README.md DELETED
@@ -1,555 +0,0 @@
1
- [![Build Status](https://travis-ci.org/donv/capybara-screenshot-diff.svg?branch=master)](https://travis-ci.org/donv/capybara-screenshot-diff)
2
-
3
- # Capybara::Screenshot::Diff
4
-
5
- Ever wondered what your project looked like two years ago? To answer that, you
6
- start taking screen shots during your tests. Capybara provides the
7
- `save_screenshot` method for this. Very good.
8
-
9
- Ever introduced a graphical change unintended? Never want it to happen again?
10
- Then this gem is for you! Use this gem to detect changes in your pages by
11
- taking screen shots and comparing them to the previous revision.
12
-
13
- ## Installation
14
-
15
- Add these lines to your application's Gemfile:
16
-
17
- ```ruby
18
- gem 'capybara-screenshot-diff'
19
- gem 'oily_png', platform: :ruby
20
- ```
21
-
22
- And then execute:
23
-
24
- $ bundle
25
-
26
- Or install it yourself as:
27
-
28
- $ gem install capybara-screenshot-diff
29
-
30
- ### Requirements
31
-
32
- * [for :vips driver] libvips 8.9 or later, see the [libvips install instructions](https://libvips.github.io/libvips/install.html)
33
-
34
- ## Usage
35
-
36
- ### Minitest
37
-
38
- In your test class, include the `Capybara::Screenshot::Diff` module:
39
-
40
- ```ruby
41
- class ApplicationSystemTestCase < ActionDispatch::SystemTestCase
42
- include Capybara::Screenshot::Diff
43
- ...
44
- end
45
- ```
46
-
47
- ### rspec
48
-
49
- ```ruby
50
- describe 'Permissions admin', :type => :feature, :js => true do
51
-
52
- include Capybara::Screenshot::Diff
53
-
54
- it 'works with permissions' do
55
- visit('/')
56
- screenshot 'home_page'
57
- end
58
-
59
- end
60
- ```
61
- But it's better to include it within your *_helper.rb file so that it can used anywhere in your feature specs.
62
- ```ruby
63
- # spec/feature_helper.rb
64
- require 'capybara/screenshot/diff'
65
-
66
- RSpec.configure do |config|
67
- config.include Capybara::Screenshot::Diff::TestMethods
68
- end
69
- ```
70
-
71
- ### Taking screenshots
72
-
73
- Add `screenshot '<my_feature>'` to your tests. The screenshot will be saved in
74
- the `doc/screenshots` directory.
75
-
76
- Change your existing `save_screenshot` calls to `screenshot`
77
-
78
- ```ruby
79
- test 'my useful feature' do
80
- visit '/'
81
- screenshot 'welcome_index'
82
- click_button 'Useful feature'
83
- screenshot 'feature_index'
84
- click_button 'Perform action'
85
- screenshot 'action_performed'
86
- end
87
- ```
88
-
89
- This will produce a sequence of images like this
90
-
91
- ```
92
- doc
93
- screenshots
94
- action_performed
95
- feature_index
96
- welcome_index
97
- ```
98
-
99
- To store the screen shot history, add the `doc/screenshots` directory to your
100
- version control system (git, svn, etc).
101
-
102
- Screen shots are compared to the previously COMMITTED version of the same screen shot.
103
-
104
- ### Screenshot groups
105
-
106
- Commonly it is useful to group screenshots around a feature, and record them as
107
- a sequence. To do this, add a `screenshot_group` call to the start of your
108
- test.
109
-
110
- ```ruby
111
- test 'my useful feature' do
112
- screenshot_group 'useful_feature'
113
- visit '/'
114
- screenshot 'welcome_index'
115
- click_button 'Useful feature'
116
- screenshot 'feature_index'
117
- click_button 'Perform action'
118
- screenshot 'action_performed'
119
- end
120
- ```
121
-
122
- This will produce a sequence of images like this
123
-
124
- ```
125
- doc
126
- screenshots
127
- useful_feature
128
- 00-welcome_index
129
- 01-feature_index
130
- 02-action_performed
131
- ```
132
-
133
- **All files in the screenshot group directory will be deleted when
134
- `screenshot_group` is called.**
135
-
136
-
137
- #### Screenshot sections
138
-
139
- You can introduce another level above the screenshot group called a
140
- `screenshot_section`. The section name is inserted just before the group name
141
- in the save path. If called in the setup of the test, all screenshots in
142
- that test will get the same prefix:
143
-
144
- ```ruby
145
- setup do
146
- screenshot_section 'my_feature'
147
- end
148
-
149
- test 'my subfeature' do
150
- screenshot_group 'subfeature'
151
- visit '/feature'
152
- click_button 'Interesting button'
153
- screenshot 'subfeature_index'
154
- click_button 'Perform action'
155
- screenshot 'action_performed'
156
- end
157
- ```
158
-
159
- This will produce a sequence of images like this
160
-
161
- ```
162
- doc
163
- screenshots
164
- my_feature
165
- subfeature
166
- 00-subfeature_index
167
- 01-action_performed
168
- ```
169
-
170
-
171
- #### Setting `screenshot_section` and/or `screenshot_group` for all tests
172
-
173
- Setting the `screenshot_section` and/or `screenshot_group` for all tests can be
174
- done in the super class setup:
175
-
176
- ```ruby
177
- class ApplicationSystemTestCase < ActionDispatch::SystemTestCase
178
- setup do
179
- screenshot_section class_name.underscore.sub(/(_feature|_system)?_test$/, '')
180
- screenshot_group name[5..-1]
181
- end
182
- end
183
- ```
184
-
185
- `screenshot_section` and/or `screenshot_group` can still be overridden in each
186
- test.
187
-
188
-
189
-
190
- ### Capturing one area instead of the whole page
191
-
192
- ```ruby
193
- test 'the cool' do
194
- visit '/feature'
195
- screenshot 'cool_element', crop: bounds('#my_element')
196
- end
197
-
198
- private
199
-
200
- def bounds(selector)
201
- element = evaluate_script("document.querySelector('#{selector}').getBoundingClientRect()")
202
- [element['left'], element['top'], element['right'], element['bottom']]
203
- end
204
- ```
205
-
206
-
207
- ### Multiple Capybara drivers
208
-
209
- Often it is useful to test your app using different browsers. To avoid the
210
- screenshots for different Capybara drivers to overwrite each other, set
211
-
212
- ```ruby
213
- Capybara::Screenshot.add_driver_path = true
214
- ```
215
-
216
- The example above will then save your screenshots like this
217
- (for poltergeist and selenium):
218
-
219
- ```
220
- doc
221
- screenshots
222
- poltergeist
223
- useful_feature
224
- 00-welcome_index
225
- 01-feature_index
226
- 02-action_performed
227
- selenium
228
- useful_feature
229
- 00-welcome_index
230
- 01-feature_index
231
- 02-action_performed
232
- ```
233
-
234
- ### Multiple OSs
235
-
236
- If you run your tests on multiple operating systems, you will most likely find
237
- the screen shots differ. To avoid the screenshots for different OSs to
238
- overwrite each other, set
239
-
240
- ```ruby
241
- Capybara::Screenshot.add_os_path = true
242
- ```
243
-
244
- The example above will then save your screenshots like this
245
- (for Linux and Windows):
246
-
247
- ```
248
- doc
249
- screenshots
250
- linux
251
- useful_feature
252
- 00-welcome_index
253
- 01-feature_index
254
- 02-action_performed
255
- windows
256
- useful_feature
257
- 00-welcome_index
258
- 01-feature_index
259
- 02-action_performed
260
- ```
261
-
262
- If you combine this config with the `add_driver_path` config, the driver will be
263
- put in front of the OS name.
264
-
265
- ### Screen size
266
-
267
- You can specify the desired screen size using
268
-
269
- ```ruby
270
- Capybara::Screenshot.window_size = [1024, 768]
271
- ```
272
-
273
- This will force the screen shots to the given size, and skip taking screen shots
274
- unless the desired window size can be achieved.
275
-
276
- ### Disabling screen shots
277
-
278
- If you want to skip taking screen shots, set
279
-
280
- ```ruby
281
- Capybara::Screenshot.enabled = false
282
- ```
283
-
284
- You can of course set this by an environment variable
285
-
286
- ```ruby
287
- Capybara::Screenshot.enabled = ENV['TAKE_SCREENSHOTS']
288
- ```
289
-
290
- ### Disabling diff
291
-
292
- If you want to skip the assertion for change in the screen shot, set
293
-
294
- ```ruby
295
- Capybara::Screenshot::Diff.enabled = false
296
- ```
297
-
298
- Using an environment variable
299
-
300
- ```ruby
301
- Capybara::Screenshot::Diff.enabled = ENV['COMPARE_SCREENSHOTS']
302
- ```
303
-
304
- ### Screen shot save path
305
-
306
- By default, `Capybara::Screenshot::Diff` saves screenshots to a
307
- `doc/screenshots` folder, relative to either `Rails.root` (if you're in Rails),
308
- or your current directory otherwise.
309
-
310
- If you want to change where screenshots are saved to, then there are two
311
- configuration options that that are relevant.
312
-
313
- The most likely one you'll want to modify is ...
314
-
315
- ```ruby
316
- Capybara::Screenshot.save_path = "other/path"
317
- ```
318
-
319
- The `save_path` option is relative to `Capybara::Screenshot.root`.
320
-
321
- `Capybara::Screenshot.root` defaults to either `Rails.root` (if you're in
322
- Rails) or your current directory. You can change it to something entirely
323
- different if necessary, such as when using an alternative web framework.
324
-
325
- ```ruby
326
- Capybara::Screenshot.root = Hanami.root
327
- ```
328
-
329
- ### Screen shot stability
330
-
331
- To ensure that animations are finished before saving a screen shot, you can add
332
- a stability time limit. If the stability time limit is set, a second screen
333
- shot will be taken and compared to the first. This is repeated until two
334
- subsequent screen shots are identical.
335
-
336
- ```ruby
337
- Capybara::Screenshot.stability_time_limit = 0.1
338
- ```
339
-
340
- This can be overridden on a single screenshot:
341
-
342
- ```ruby
343
- test 'stability_time_limit' do
344
- visit '/'
345
- screenshot 'index', stability_time_limit: 0.5
346
- end
347
- ```
348
-
349
- ### Maximum wait limit
350
-
351
- When the `stability_time_limit` is set, but no stable screenshot can be taken, a timeout occurs.
352
- The timeout occurs after `Capybara.default_max_wait_time`, but can be overridden by an option.
353
-
354
- ```ruby
355
- test 'max wait time' do
356
- visit '/'
357
- screenshot 'index', wait: 20.seconds
358
- end
359
- ```
360
-
361
- ### Hiding the caret for active input elements
362
-
363
- In Chrome the screenshot includes the blinking input cursor. This can make it impossible to get a
364
- stable screenshot. To get around this you can set the `hide caret` option:
365
-
366
- ```ruby
367
- Capybara::Screenshot.hide_caret = true
368
- ```
369
-
370
- This will make the cursor (caret) transparent (invisible), so the blinking does not delay the screen shot.
371
-
372
-
373
-
374
- ### Removing focus from the active element
375
-
376
- Another way to avoid the cursor blinking is to set the `blur_active_element` option:
377
-
378
- ```ruby
379
- Capybara::Screenshot.blur_active_element = true
380
- ```
381
-
382
- This will remove the focus from the active element, removing the blinking cursor.
383
-
384
-
385
-
386
- ### Allowed color distance
387
-
388
- Sometimes you want to allow small differences in the images. For example, Chrome renders the same
389
- page slightly differently sometimes. You can set set the color difference threshold for the
390
- comparison using the `color_distance_limit` option to the `screenshot` method:
391
-
392
- ```ruby
393
- test 'color threshold' do
394
- visit '/'
395
- screenshot 'index', color_distance_limit: 30
396
- end
397
- ```
398
-
399
- The difference is calculated as the eucledian distance. You can also set this globally:
400
-
401
- ```ruby
402
- Capybara::Screenshot::Diff.color_distance_limit = 42
403
- ```
404
-
405
-
406
- ### Allowed shift distance
407
-
408
- Sometimes you want to allow small movements in the images. For example, jquer-tablesorter
409
- renders the same table slightly differently sometimes. You can set set the shift distance
410
- threshold for the comparison using the `shift_distance_limit` option to the `screenshot`
411
- method:
412
-
413
- ```ruby
414
- test 'color threshold' do
415
- visit '/'
416
- screenshot 'index', shift_distance_limit: 2
417
- end
418
- ```
419
-
420
- The difference is calculated as maximum distance in either the X or the Y axis.
421
- You can also set this globally:
422
-
423
- ```ruby
424
- Capybara::Screenshot::Diff.shift_distance_limit = 1
425
- ```
426
-
427
- **Note:** For each increase in `shift_distance_limit` more pixels are searched for a matching color value, and
428
- this will impact performance **severely** if a match cannot be found.
429
-
430
- If `shift_distance_limit` is `nil` shift distance is not measured. If `shift_distance_limit` is set,
431
- even to `0`, shift distabnce is measured and reported on image differences.
432
-
433
- ### Allowed difference size
434
-
435
- You can set set a threshold for the differing area size for the comparison
436
- using the `area_size_limit` option to the `screenshot` method:
437
-
438
- ```ruby
439
- test 'area threshold' do
440
- visit '/'
441
- screenshot 'index', area_size_limit: 17
442
- end
443
- ```
444
-
445
- The difference is calculated as `width * height`. You can also set this globally:
446
-
447
- ```ruby
448
- Capybara::Screenshot::Diff.area_size_limit = 42
449
- ```
450
-
451
-
452
- ### Skipping an area
453
-
454
- Sometimes you have expected change that you want to ignore.
455
- You can use the `skip_area` option to the `screenshot` method to ignore an area:
456
-
457
- ```ruby
458
- test 'unstable area' do
459
- visit '/'
460
- screenshot 'index', skip_area: [17, 6, 27, 16]
461
- end
462
- ```
463
-
464
- The arguments are [x1, y1, x2, y2] for the area you want to ignore. You can also set this globally:
465
-
466
- ```ruby
467
- Capybara::Screenshot::Diff.skip_area = [0, 0, 64, 48]
468
- ```
469
-
470
- If you need to ignore multiple areas, you can supply an array of arrays:
471
-
472
- ```ruby
473
- screenshot 'index', skip_area: [[0, 0, 64, 48], [17, 6, 27, 16]]
474
- ```
475
-
476
- ### Available Image Processing Drivers
477
-
478
- There are several image processing supported by this gem.
479
- There are several options to setup active driver: `:auto`, `:chunky_png` and `:vips`.
480
-
481
- * `:auto` - will try to load `:vips` if there is gem `ruby-vips`, in other cases will load `:chunky_png`
482
- * `:chunky_png` and `:vips` will load correspondent driver
483
-
484
- ### Enable VIPS image processing
485
-
486
- [Vips](https://www.rubydoc.info/gems/ruby-vips/Vips/Image) driver provides a faster comparison,
487
- and could be enabled by adding `ruby-vips` to `Gemfile`.
488
-
489
- If need to setup explicitly Vips driver, there are several ways to do this:
490
-
491
- * Globally: `Capybara::Screenshot::Diff.driver = :vips`
492
- * Per screenshot option: `screenshot 'index', driver: :vips`
493
-
494
- With enabled VIPS there are new alternatives to process differences, which easier to find and support.
495
- For example, `shift_distance_limit` is very heavy operation. Instead better to use `median_filter_window_size`.
496
-
497
- #### Tolerance level (vips only)
498
-
499
- You can set a “tolerance” anywhere from 0% to 100%. This is the amount of change that's allowable.
500
- If the screenshot has changed by more than that amount, it'll flag it as a failure.
501
-
502
- This is alternative to "Allowed difference size", only the difference that area calculates including valid pixels.
503
- But "tolerance" compares only different pixels.
504
-
505
- You can use the `tolerance` option to the `screenshot` method to set level:
506
-
507
- ```ruby
508
- test 'unstable area' do
509
- visit '/'
510
- screenshot 'index', tolerance: 0.3
511
- end
512
- ```
513
-
514
- You can also set this globally:
515
-
516
- ```ruby
517
- Capybara::Screenshot::Diff.tolerance = 0.3
518
- ```
519
-
520
- #### Median filter size (vips only)
521
-
522
- This is an alternative to "Allowed shift distance", but much faster.
523
- You can find more about this strategy on [Median Filter](https://en.wikipedia.org/wiki/Median_filter).
524
- Think about this like smoothing of the image, before comparison.
525
-
526
- You can use the `median_filter_window_size` option to the `screenshot` method to set level:
527
-
528
- ```ruby
529
- test 'unstable area' do
530
- visit '/'
531
- screenshot 'index', median_filter_window_size: 2
532
- end
533
- ```
534
-
535
- ## Development
536
-
537
- After checking out the repo, run `bin/setup` to install dependencies.
538
- Then, run `rake test` to run the tests.
539
- You can also run `bin/console` for an interactive prompt that will allow you to experiment.
540
-
541
- To install this gem onto your local machine, run `bundle exec rake install`.
542
-
543
- To release a new version, update the version number in `lib/capybara/screenshot/diff/version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
544
-
545
- ## Contributing
546
-
547
- Bug reports and pull requests are welcome on GitHub at https://github.com/donv/capybara-screenshot-diff.
548
- This project is intended to be a safe, welcoming space for collaboration,
549
- and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
550
-
551
-
552
- ## License
553
-
554
- The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).
555
-