capybara-screenshot-diff 1.6.3 → 1.8.3

Sign up to get free protection for your applications and to get access to all the features.
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 +18 -0
  11. data/lib/capybara/screenshot/diff/drivers/vips_driver.rb +61 -102
  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 -208
  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 +15 -19
  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
-