class Capybara::Selenium::Driver

Constants

DEFAULT_OPTIONS
SPECIAL_OPTIONS

Attributes

app[R]
options[R]

Public Class Methods

load_selenium() click to toggle source
# File lib/capybara/selenium/driver.rb, line 15
def self.load_selenium
  require 'selenium-webdriver'
  warn "Warning: You're using an unsupported version of selenium-webdriver, please upgrade." if Gem.loaded_specs['selenium-webdriver'].version < Gem::Version.new('3.5.0')
rescue LoadError => err
  raise err if err.message !~ /selenium-webdriver/
  raise LoadError, "Capybara's selenium driver is unable to load `selenium-webdriver`, please install the gem and add `gem 'selenium-webdriver'` to your Gemfile if you are using bundler."
end
new(app, **options) click to toggle source
# File lib/capybara/selenium/driver.rb, line 34
def initialize(app, **options)
  self.class.load_selenium
  @app = app
  @browser = nil
  @exit_status = nil
  @frame_handles = Hash.new { |hash, handle| hash[handle] = [] }
  @options = DEFAULT_OPTIONS.merge(options)
  @node_class = ::Capybara::Selenium::Node
end

Public Instance Methods

accept_modal(_type, **options) { || ... } click to toggle source
# File lib/capybara/selenium/driver.rb, line 204
def accept_modal(_type, **options)
  yield if block_given?
  modal = find_modal(options)

  modal.send_keys options[:with] if options[:with]

  message = modal.text
  modal.accept
  message
end
browser() click to toggle source
# File lib/capybara/selenium/driver.rb, line 23
def browser
  @browser ||= begin
    processed_options = options.reject { |key, _val| SPECIAL_OPTIONS.include?(key) }
    Selenium::WebDriver.for(options[:browser], processed_options).tap do |driver|
      specialize_driver(driver)
      setup_exit_handler
    end
  end
  @browser
end
close_window(handle) click to toggle source
# File lib/capybara/selenium/driver.rb, line 185
def close_window(handle)
  raise ArgumentError, 'Not allowed to close the primary window' if handle == window_handles.first
  within_given_window(handle) do
    browser.close
  end
end
current_url() click to toggle source
# File lib/capybara/selenium/driver.rb, line 68
def current_url
  browser.current_url
end
current_window_handle() click to toggle source
# File lib/capybara/selenium/driver.rb, line 155
def current_window_handle
  browser.window_handle
end
dismiss_modal(_type, **options) { || ... } click to toggle source
# File lib/capybara/selenium/driver.rb, line 215
def dismiss_modal(_type, **options)
  yield if block_given?
  modal = find_modal(options)
  message = modal.text
  modal.dismiss
  message
end
evaluate_async_script(script, *args) click to toggle source
# File lib/capybara/selenium/driver.rb, line 92
def evaluate_async_script(script, *args)
  browser.manage.timeouts.script_timeout = Capybara.default_max_wait_time
  result = browser.execute_async_script(script, *native_args(args))
  unwrap_script_result(result)
end
evaluate_script(script, *args) click to toggle source
# File lib/capybara/selenium/driver.rb, line 87
def evaluate_script(script, *args)
  result = execute_script("return #{script}", *args)
  unwrap_script_result(result)
end
execute_script(script, *args) click to toggle source
# File lib/capybara/selenium/driver.rb, line 83
def execute_script(script, *args)
  browser.execute_script(script, *native_args(args))
end
find_css(selector) click to toggle source
# File lib/capybara/selenium/driver.rb, line 76
def find_css(selector)
  browser.find_elements(:css, selector).map(&method(:build_node))
end
find_xpath(selector) click to toggle source
# File lib/capybara/selenium/driver.rb, line 72
def find_xpath(selector)
  browser.find_elements(:xpath, selector).map(&method(:build_node))
end
fullscreen_window(handle) click to toggle source
# File lib/capybara/selenium/driver.rb, line 179
def fullscreen_window(handle)
  within_given_window(handle) do
    browser.manage.window.full_screen
  end
end
go_back() click to toggle source
# File lib/capybara/selenium/driver.rb, line 52
def go_back
  browser.navigate.back
end
go_forward() click to toggle source
# File lib/capybara/selenium/driver.rb, line 56
def go_forward
  browser.navigate.forward
end
html() click to toggle source
# File lib/capybara/selenium/driver.rb, line 60
def html
  browser.page_source
end
invalid_element_errors() click to toggle source
# File lib/capybara/selenium/driver.rb, line 236
def invalid_element_errors
  [
    ::Selenium::WebDriver::Error::StaleElementReferenceError,
    ::Selenium::WebDriver::Error::UnhandledError,
    ::Selenium::WebDriver::Error::ElementNotVisibleError,
    ::Selenium::WebDriver::Error::InvalidSelectorError, # Work around a race condition that can occur with chromedriver and #go_back/#go_forward
    ::Selenium::WebDriver::Error::ElementNotInteractableError,
    ::Selenium::WebDriver::Error::ElementClickInterceptedError,
    ::Selenium::WebDriver::Error::InvalidElementStateError,
    ::Selenium::WebDriver::Error::ElementNotSelectableError,
    ::Selenium::WebDriver::Error::ElementNotSelectableError,
    ::Selenium::WebDriver::Error::NoSuchElementError, # IE
    ::Selenium::WebDriver::Error::InvalidArgumentError # IE
  ]
end
maximize_window(handle) click to toggle source
# File lib/capybara/selenium/driver.rb, line 172
def maximize_window(handle)
  within_given_window(handle) do
    browser.manage.window.maximize
  end
  sleep 0.1 # work around for https://code.google.com/p/selenium/issues/detail?id=7405
end
needs_server?() click to toggle source
# File lib/capybara/selenium/driver.rb, line 81
def needs_server?; true; end
no_such_window_error() click to toggle source
# File lib/capybara/selenium/driver.rb, line 252
def no_such_window_error
  Selenium::WebDriver::Error::NoSuchWindowError
end
open_new_window() click to toggle source
# File lib/capybara/selenium/driver.rb, line 196
def open_new_window
  browser.execute_script('window.open();')
end
quit() click to toggle source
# File lib/capybara/selenium/driver.rb, line 223
def quit
  @browser&.quit
rescue Selenium::WebDriver::Error::SessionNotCreatedError, Errno::ECONNREFUSED # rubocop:disable Lint/HandleExceptions
  # Browser must have already gone
rescue Selenium::WebDriver::Error::UnknownError => err
  unless silenced_unknown_error_message?(err.message) # Most likely already gone
    # probably already gone but not sure - so warn
    warn "Ignoring Selenium UnknownError during driver quit: #{err.message}"
  end
ensure
  @browser = nil
end
refresh() click to toggle source
# File lib/capybara/selenium/driver.rb, line 48
def refresh
  browser.navigate.refresh
end
reset!() click to toggle source
# File lib/capybara/selenium/driver.rb, line 102
def reset!
  # Use instance variable directly so we avoid starting the browser just to reset the session
  return unless @browser

  navigated = false
  timer = Capybara::Helpers.timer(expire_in: 10)
  begin
    unless navigated
      # Only trigger a navigation if we haven't done it already, otherwise it
      # can trigger an endless series of unload modals
      clear_browser_state
      @browser.navigate.to('about:blank')
    end
    navigated = true

    # Ensure the page is empty and trigger an UnhandledAlertError for any modals that appear during unload
    until find_xpath('/html/body/*').empty?
      raise Capybara::ExpectationNotMet, 'Timed out waiting for Selenium session reset' if timer.expired?
      sleep 0.05
    end
  rescue Selenium::WebDriver::Error::UnhandledAlertError, Selenium::WebDriver::Error::UnexpectedAlertOpenError
    # This error is thrown if an unhandled alert is on the page
    # Firefox appears to automatically dismiss this alert, chrome does not
    # We'll try to accept it
    begin
      @browser.switch_to.alert.accept
      sleep 0.25 # allow time for the modal to be handled
    rescue modal_error
      # The alert is now gone.
      # If navigation has not occurred attempt again and accept alert
      # since FF may have dismissed the alert at first attempt.
      navigate_with_accept('about:blank') if current_url != 'about:blank'
    end
    # try cleaning up the browser again
    retry
  end
end
resize_window_to(handle, width, height) click to toggle source
# File lib/capybara/selenium/driver.rb, line 166
def resize_window_to(handle, width, height)
  within_given_window(handle) do
    browser.manage.window.resize_to(width, height)
  end
end
save_screenshot(path, **_options) click to toggle source
# File lib/capybara/selenium/driver.rb, line 98
def save_screenshot(path, **_options)
  browser.save_screenshot(path)
end
switch_to_frame(frame) click to toggle source
# File lib/capybara/selenium/driver.rb, line 140
def switch_to_frame(frame)
  handles = @frame_handles[current_window_handle]
  case frame
  when :top
    handles.clear
    browser.switch_to.default_content
  when :parent
    handles.pop
    browser.switch_to.parent_frame
  else
    handles << frame.native
    browser.switch_to.frame(frame.native)
  end
end
switch_to_window(handle) click to toggle source
# File lib/capybara/selenium/driver.rb, line 200
def switch_to_window(handle)
  browser.switch_to.window handle
end
title() click to toggle source
# File lib/capybara/selenium/driver.rb, line 64
def title
  browser.title
end
visit(path) click to toggle source
# File lib/capybara/selenium/driver.rb, line 44
def visit(path)
  browser.navigate.to(path)
end
wait?() click to toggle source
# File lib/capybara/selenium/driver.rb, line 80
def wait?; true; end
window_handles() click to toggle source
# File lib/capybara/selenium/driver.rb, line 192
def window_handles
  browser.window_handles
end
window_size(handle) click to toggle source
# File lib/capybara/selenium/driver.rb, line 159
def window_size(handle)
  within_given_window(handle) do
    size = browser.manage.window.size
    [size.width, size.height]
  end
end

Private Instance Methods

build_node(native_node) click to toggle source
# File lib/capybara/selenium/driver.rb, line 355
def build_node(native_node)
  ::Capybara::Selenium::Node.new(self, native_node)
end
clear_browser_state() click to toggle source
# File lib/capybara/selenium/driver.rb, line 262
def clear_browser_state
  @browser.manage.delete_all_cookies
  clear_storage
rescue Selenium::WebDriver::Error::UnhandledError # rubocop:disable Lint/HandleExceptions
  # delete_all_cookies fails when we've previously gone
  # to about:blank, so we rescue this error and do nothing
  # instead.
end
clear_local_storage() click to toggle source
# File lib/capybara/selenium/driver.rb, line 284
def clear_local_storage
  if @browser.respond_to? :local_storage
    @browser.local_storage.clear
  else
    warn 'localStorage clear requested but is not available for this driver'
  end
end
clear_session_storage() click to toggle source
# File lib/capybara/selenium/driver.rb, line 276
def clear_session_storage
  if @browser.respond_to? :session_storage
    @browser.session_storage.clear
  else
    warn 'sessionStorage clear requested but is not available for this driver'
  end
end
clear_storage() click to toggle source
# File lib/capybara/selenium/driver.rb, line 271
def clear_storage
  clear_session_storage if options[:clear_session_storage]
  clear_local_storage if options[:clear_local_storage]
end
find_modal(text: nil, **options) click to toggle source
# File lib/capybara/selenium/driver.rb, line 316
def find_modal(text: nil, **options)
  # Selenium has its own built in wait (2 seconds)for a modal to show up, so this wait is really the minimum time
  # Actual wait time may be longer than specified
  wait = Selenium::WebDriver::Wait.new(
    timeout: options.fetch(:wait, session_options.default_max_wait_time) || 0,
    ignore: modal_error
  )
  begin
    wait.until do
      alert = @browser.switch_to.alert
      regexp = text.is_a?(Regexp) ? text : Regexp.escape(text.to_s)
      alert.text.match(regexp) ? alert : nil
    end
  rescue Selenium::WebDriver::Error::TimeOutError
    raise Capybara::ModalNotFound, "Unable to find modal dialog#{" with #{text}" if text}"
  end
end
modal_error() click to toggle source
native_args(args) click to toggle source
# File lib/capybara/selenium/driver.rb, line 258
def native_args(args)
  args.map { |arg| arg.is_a?(Capybara::Selenium::Node) ? arg.native : arg }
end
navigate_with_accept(url) click to toggle source
setup_exit_handler() click to toggle source
# File lib/capybara/selenium/driver.rb, line 369
def setup_exit_handler
  main = Process.pid
  at_exit do
    # Store the exit status of the test run since it goes away after calling the at_exit proc...
    @exit_status = $ERROR_INFO.status if $ERROR_INFO.is_a?(SystemExit)
    quit if Process.pid == main
    exit @exit_status if @exit_status # Force exit with stored status
  end
end
silenced_unknown_error_message?(msg) click to toggle source
# File lib/capybara/selenium/driver.rb, line 334
def silenced_unknown_error_message?(msg)
  silenced_unknown_error_messages.any? { |regex| msg =~ regex }
end
silenced_unknown_error_messages() click to toggle source
# File lib/capybara/selenium/driver.rb, line 338
def silenced_unknown_error_messages
  [/Error communicating with the remote browser/]
end
specialize_driver(sel_driver) click to toggle source
# File lib/capybara/selenium/driver.rb, line 359
def specialize_driver(sel_driver)
  case sel_driver.browser
  when :chrome
    extend ChromeDriver
  when :firefox
    require 'capybara/selenium/patches/pause_duration_fix' if sel_driver.capabilities['moz:geckodriverVersion']&.start_with?('0.22.')
    extend MarionetteDriver if sel_driver.capabilities.is_a?(::Selenium::WebDriver::Remote::W3C::Capabilities)
  end
end
unwrap_script_result(arg) click to toggle source
# File lib/capybara/selenium/driver.rb, line 342
def unwrap_script_result(arg)
  case arg
  when Array
    arg.map { |arr| unwrap_script_result(arr) }
  when Hash
    arg.each { |key, value| arg[key] = unwrap_script_result(value) }
  when Selenium::WebDriver::Element
    build_node(arg)
  else
    arg
  end
end
within_given_window(handle) { || ... } click to toggle source
# File lib/capybara/selenium/driver.rb, line 304
def within_given_window(handle)
  original_handle = current_window_handle
  if handle == original_handle
    yield
  else
    switch_to_window(handle)
    result = yield
    switch_to_window(original_handle)
    result
  end
end