watir-screenshot-stitch attempts to compensate for the lack of full page screenshot functionality in Selenium Webdriver.
It does so in three ways:
- Directly employing geckodriver's new full page screenshot functionality (only on Firefox).
- Screenshot stitching, paging down a given URL by the size of the viewport, capturing screenshots and adjoining them.
- Employing a bundled
html2canvas
script against the page to generate a png from a
canvaselement.
Add this line to your application's Gemfile:
gem 'watir-screenshot-stitch'watir-screenshot-stitch relies on MiniMagick (and thus ImageMagick). You might need to review that gem's requirements and installation before proceeding.
watir-screenshot-stitch is optimized for and tested on following browsers:
- Chrome 65+
- Firefox 58+
- Safari 11.1
- IE 11/10/9/8
Your Watir / Selenium-Webdriver / webdriver / Browser stack must be correctly configured. If you can find a good guide for installing and maintaining all parts of this stack, you're a better Googler than me.
As warned in version 0.6.6 and beyond, the Watir::Screenshot class will have access to the browser in watir-screenshot-stitch version 0.7.0 and beyond, and it will not need to be passed to the public methods. Previous implementations will break.
To adapt, change your function calls like so:
| <= 0.6.5 | >= 0.6.6 && <= 0.6.11 | >= 0.7.0 |
|---|---|---|
| `save_stitch(path, browser, opts)` | `save_stitch(path, nil, opts)` or `save_stitch(path, browser, opts)` | `save_stitch(path, opts)` |
| `base64_canvas(browser)` | `base64_canvas(browser)` or `base64_canvas` | `base64_canvas` |
watir-screenshot-stitch can employ a special function of geckodriver >= 0.24.0 while driving Firefox. This
require 'watir-screenshot-stitch'
b = Watir::Browser.new :firefox
b.goto "https://github.com/mozilla/geckodriver/issues/570"
b.base64_geckodriverwill return a base64 encoded image blob of the given site.
In can be saved as a PNG by doing:
png = b.screenshot.base64_geckodriver
path = "/my/path/image.png"
File.open(path, 'wb') { |f| f.write(Base64.decode64(png)) }This is the option with the fewest complications, and should be used if possible.
If using the webdrivers gem, watir-screenshot-stitch will attempt to use the geckodriver included there, since that's likely to be the driver employed by watir. If not, it falls back to the the system user's geckodriver.
watir-screenshot-stitch can be used with a typical Watir script. This
require 'watir-screenshot-stitch'
path = "/my/path/image.png"
opts = { :page_height_limit => 5000 }
b = Watir::Browser.new :firefox
b.goto "https://github.com/mozilla/geckodriver/issues/570"
b.screenshot.save_stitch(path, opts)will stitch together and save a full-page screenshot, up to 5000 pixels tall,
to /my/path/image.png.
html2canvas is a JavaScript library watir-screenshot-stitch can employ to try to create a canvas element of the entire page and covert it to a blob. For instance, this
require 'watir-screenshot-stitch'
b = Watir::Browser.new :firefox
b.goto "https://github.com/watir/watir/issues/702"
b.screenshot.base64_canvaswill return a base64 encoded image blob of the given site.
In can be saved as a PNG by doing:
png = b.screenshot.base64_canvas
path = "/my/path/image.png"
File.open(path, 'wb') { |f| f.write(Base64.decode64(png)) }This method of screenshotting is less likely to have issues with stitching the images together, and running out of memory but has limitations with certain element types not being properly displayed. See their documentation for more information.
watir-screenshot-stitch uses CSS selectors to determine whether a resulting screenshot's dimensions will be double the page dimensions when a screenshot is captured, as is the case for macOS 'Retina', and relies on this logic to determine how to stitch together images. This means that moving the browser window while it is be driven by Watir can cause unpredictable results.
A hash of key value pairs.
Should refer to a positive Integer greater than the viewport height.
ImageMagick has a maximum pixel dimension of 65500, and all stitched screenshots will be capped to a maximum height of 65500 regardless of any options to avoid errors.
Use rspec to run the tests, and see the
(contributing)[#Contributing] section below —
all are welcome.
Bug reports and pull requests are welcome on GitHub at https://github.com/samnissen/watir-screenshot-stitch. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.
The gem is available as open source under the terms of the MIT License.
Everyone interacting in the Watir::Screenshot::Stitch project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.