Scree augments the capabilities of Capybara and Selenium to ease the transition from capybara-webkit. It attempts to re-implement and extend functionality from capybara-webkit that falls into one of three categories:
- Is not well-implemented
- Will never be implemented
- Involves clunky workarounds
- Just has a different API
This gem provides the following:
Capybara::Selenium::Node#trigger(won't be implemented)Capybara::Selenium::Driver:#response_headers(won't be implemented)#status_code(won't be implemented)#console_messages(clunky workaround)#error_messages(clunky workaround)#cookies(Different API/helpers)#set_cookie(Different API/helpers)#header(clunky workaround)
Scree::RspecMatchers(Convenience)
Add this line to your application's Gemfile:
gem 'scree'And then execute:
$ bundle
Or install it yourself as:
$ gem install scree
This gem largely uses module prepending to extend the functionality of Capybara, thus essentially building it into their DSL. If you're unfamiliar with Module#prepend, see this excellent StackOverflow answer by Jörg W Mittag for a good explanation.
Because of this, these methods can be used just like any of their built-in siblings:
## Methods on elements
find('a.home-link').trigger('click')
## Methods on session
with_user_agent('test-user-agent') do
visit '/user-agent-example'
page.driver.user_agent # == 'test-user-agent'
end
console_messages # array of log events
error_messages # array of log events of type 'error'
set_cookie('raw_cookie_string') # Wrapper for page.driver.manage.add_cookie, parses cookie if string (as capybara-webkit uses)
cookies # Wapper for page.driver.manage.all_cookies
clear_cookies # Wrapper for page.driver.manage.delete_all_cookies
header('X-TEST-HEADER', 'test') # Sets extra header for next request/navigate _from this page_ (doesn't work with #visit)
## Methods on driver
page.driver.status_code # HTTP status code of most-recent request
page.driver.response_headers # Headers of most-recent request
page.driver.blocked_urls = ['https://example.com'] # Raises NotImplementedError
page.driver.extra_http_headers = { 'X-TEST-HEADER' => 'test' } # Sets extra header for next request/navigate _from this page_ (doesn't work with #visit)
page.driver.user_agent = 'test-user-agent' # Is set indefinitely, INCLUDING SUBSEQUENT SPECS; USE WITH CARE
page.driver.user_agent # == 'test-user-agent'To use the matchers, just add it to your spec_helper, as such:
require 'scree/rspec_matchers'
RSpec.configure do |config|
# ...
config.include Scree::RspecMatchers
# ...
endRight now, some parts of the implementation are fairly inefficient. Specifically:
These are in a different format than in capybara-webkit. The decision to do so was made in the interest of allowing developers to receive more nuanced data.
We enable all of the Chrome DevTool domains. This may have significant effects on memory usage and run-time, due to the large-scale logging of requests.
This was done pending a more developer-friendly way of enabling these, since inconsistent states can cause very buggy behavior and a frustrating experience.
We capture all events from the beginning of chromedriver's execution until the test suite is finished. This is never cleared out, nor expired. Larger test suites could potentially log huge amounts of data resulting in runaway memory usage. To work around this, we recommend you batch your test suite into smaller groups.
This was done to persist important data (such as error logs) across multiple page loads. Clearing this cache on each page load (unless a relevant option is set) would be more in-line with other Selenium/chromedriver behavior, but has not yet been implemented.
This does not currently work at all. The straightforward way to do this via the DevTools protocol just causes Chrome to hang indefinitely whenever the browser makes a matching request, which is worse than useless in this context.
To fix this, we'll need to implement fairly robust request interception/modification, which has proven difficult and error-prone.
After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.
To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in 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.
Bug reports and pull requests are welcome on GitHub at https://github.com/joinhandshake/scree. 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 Scree project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.