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 16
def self.load_selenium
  require 'selenium-webdriver'
  # Fix for selenium-webdriver 3.4.0 which misnamed these
  unless defined?(::Selenium::WebDriver::Error::ElementNotInteractableError)
    ::Selenium::WebDriver::Error.const_set('ElementNotInteractableError', Class.new(::Selenium::WebDriver::Error::WebDriverError))
  end
  unless defined?(::Selenium::WebDriver::Error::ElementClickInterceptedError)
    ::Selenium::WebDriver::Error.const_set('ElementClickInterceptedError', Class.new(::Selenium::WebDriver::Error::WebDriverError))
  end
rescue LoadError => e
  raise e if e.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 54
def initialize(app, **options)
  self.class.load_selenium
  @session = nil
  @app = app
  @browser = nil
  @exit_status = nil
  @frame_handles = {}
  @options = DEFAULT_OPTIONS.merge(options)
end

Public Instance Methods

accept_modal(_type, **options) { || ... } click to toggle source
# File lib/capybara/selenium/driver.rb, line 246
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 30
def browser
  unless @browser
    # if firefox?
    #   options[:desired_capabilities] ||= {}
    #   options[:desired_capabilities][:unexpectedAlertBehaviour] = "ignore"
    # end

    @processed_options = options.reject { |key, _val| SPECIAL_OPTIONS.include?(key) }
    @browser = Selenium::WebDriver.for(options[:browser], @processed_options)

    @w3c = ((defined?(Selenium::WebDriver::Remote::W3CCapabilities) && @browser.capabilities.is_a?(Selenium::WebDriver::Remote::W3CCapabilities)) ||
            (defined?(Selenium::WebDriver::Remote::W3C::Capabilities) && @browser.capabilities.is_a?(Selenium::WebDriver::Remote::W3C::Capabilities)))
    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
  @browser
end
browser_name() click to toggle source

@api private

# File lib/capybara/selenium/driver.rb, line 324
def browser_name
  browser.browser
end
chrome?() click to toggle source

@api private

# File lib/capybara/selenium/driver.rb, line 309
def chrome?
  browser_name == :chrome
end
close_window(handle) click to toggle source
# File lib/capybara/selenium/driver.rb, line 227
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 88
def current_url
  browser.current_url
end
current_window_handle() click to toggle source
# File lib/capybara/selenium/driver.rb, line 198
def current_window_handle
  browser.window_handle
end
dismiss_modal(_type, **options) { || ... } click to toggle source
# File lib/capybara/selenium/driver.rb, line 257
def dismiss_modal(_type, **options)
  yield if block_given?
  modal = find_modal(options)
  message = modal.text
  modal.dismiss
  message
end
edge?() click to toggle source

@api private

# File lib/capybara/selenium/driver.rb, line 314
def edge?
  browser_name == :edge
end
evaluate_async_script(script, *args) click to toggle source
# File lib/capybara/selenium/driver.rb, line 112
def evaluate_async_script(script, *args)
  browser.manage.timeouts.script_timeout = Capybara.default_max_wait_time
  result = browser.execute_async_script(script, *args.map { |arg| arg.is_a?(Capybara::Selenium::Node) ? arg.native : arg })
  unwrap_script_result(result)
end
evaluate_script(script, *args) click to toggle source
# File lib/capybara/selenium/driver.rb, line 107
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 103
def execute_script(script, *args)
  browser.execute_script(script, *args.map { |arg| arg.is_a?(Capybara::Selenium::Node) ? arg.native : arg })
end
find_css(selector) click to toggle source
# File lib/capybara/selenium/driver.rb, line 96
def find_css(selector)
  browser.find_elements(:css, selector).map { |node| Capybara::Selenium::Node.new(self, node) }
end
find_xpath(selector) click to toggle source
# File lib/capybara/selenium/driver.rb, line 92
def find_xpath(selector)
  browser.find_elements(:xpath, selector).map { |node| Capybara::Selenium::Node.new(self, node) }
end
firefox?() click to toggle source

@api private

# File lib/capybara/selenium/driver.rb, line 304
def firefox?
  browser_name == :firefox
end
go_back() click to toggle source
# File lib/capybara/selenium/driver.rb, line 72
def go_back
  browser.navigate.back
end
go_forward() click to toggle source
# File lib/capybara/selenium/driver.rb, line 76
def go_forward
  browser.navigate.forward
end
html() click to toggle source
# File lib/capybara/selenium/driver.rb, line 80
def html
  browser.page_source
end
ie?() click to toggle source

@api private

# File lib/capybara/selenium/driver.rb, line 319
def ie?
  browser_name == :ie
end
invalid_element_errors() click to toggle source
# File lib/capybara/selenium/driver.rb, line 278
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
marionette?() click to toggle source

@api private

# File lib/capybara/selenium/driver.rb, line 299
def marionette?
  firefox? && browser && @w3c
end
maximize_window(handle) click to toggle source
# File lib/capybara/selenium/driver.rb, line 220
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 101
def needs_server?; true; end
no_such_window_error() click to toggle source
# File lib/capybara/selenium/driver.rb, line 294
def no_such_window_error
  Selenium::WebDriver::Error::NoSuchWindowError
end
open_new_window() click to toggle source
# File lib/capybara/selenium/driver.rb, line 238
def open_new_window
  browser.execute_script('window.open();')
end
quit() click to toggle source
# File lib/capybara/selenium/driver.rb, line 265
def quit
  @browser.quit if @browser
rescue Selenium::WebDriver::Error::SessionNotCreatedError, Errno::ECONNREFUSED
  # Browser must have already gone
rescue Selenium::WebDriver::Error::UnknownError => e
  unless silenced_unknown_error_message?(e.message) # Most likely already gone
    # probably already gone but not sure - so warn
    warn "Ignoring Selenium UnknownError during driver quit: #{e.message}"
  end
ensure
  @browser = nil
end
refresh() click to toggle source
# File lib/capybara/selenium/driver.rb, line 68
def refresh
  browser.navigate.refresh
end
reset!() click to toggle source
# File lib/capybara/selenium/driver.rb, line 122
def reset!
  # Use instance variable directly so we avoid starting the browser just to reset the session
  return unless @browser

  if firefox? || chrome?
    switch_to_window(window_handles.first)
    window_handles.slice(1..-1).each { |win| close_window(win) }
  end

  navigated = false
  start_time = Capybara::Helpers.monotonic_time
  begin
    unless navigated
      # Only trigger a navigation if we haven't done it already, otherwise it
      # can trigger an endless series of unload modals
      begin
        @browser.manage.delete_all_cookies
        clear_storage
      rescue Selenium::WebDriver::Error::UnhandledError
        # delete_all_cookies fails when we've previously gone
        # to about:blank, so we rescue this error and do nothing
        # instead.
      end
      @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 (Capybara::Helpers.monotonic_time - start_time) >= 10
      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 current_url != "about:blank"
        begin
          # If navigation has not occurred attempt again and accept alert
          # since FF may have dismissed the alert at first attempt
          @browser.navigate.to("about:blank")
          sleep 0.1 # slight wait for alert
          @browser.switch_to.alert.accept
        rescue modal_error # rubocop:disable Metrics/BlockNesting
          # alert now gone, should mean navigation happened
        end
      end
    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 209
def resize_window_to(handle, width, height)
  within_given_window(handle) do
    # Don't set the size if already set - See https://github.com/mozilla/geckodriver/issues/643
    if marionette? && (window_size(handle) == [width, height])
      {}
    else
      browser.manage.window.resize_to(width, height)
    end
  end
end
save_screenshot(path, **_options) click to toggle source
# File lib/capybara/selenium/driver.rb, line 118
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 180
def switch_to_frame(frame)
  case frame
  when :top
    @frame_handles[browser.window_handle] = []
    browser.switch_to.default_content
  when :parent
    # would love to use browser.switch_to.parent_frame here
    # but it has an issue if the current frame is removed from within it
    @frame_handles[browser.window_handle].pop
    browser.switch_to.default_content
    @frame_handles[browser.window_handle].each { |fh| browser.switch_to.frame(fh) }
  else
    @frame_handles[browser.window_handle] ||= []
    @frame_handles[browser.window_handle] << 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 242
def switch_to_window(handle)
  browser.switch_to.window handle
end
title() click to toggle source
# File lib/capybara/selenium/driver.rb, line 84
def title
  browser.title
end
visit(path) click to toggle source
# File lib/capybara/selenium/driver.rb, line 64
def visit(path)
  browser.navigate.to(path)
end
wait?() click to toggle source
# File lib/capybara/selenium/driver.rb, line 100
def wait?; true; end
window_handles() click to toggle source
# File lib/capybara/selenium/driver.rb, line 234
def window_handles
  browser.window_handles
end
window_size(handle) click to toggle source
# File lib/capybara/selenium/driver.rb, line 202
def window_size(handle)
  within_given_window(handle) do
    size = browser.manage.window.size
    [size.width, size.height]
  end
end

Private Instance Methods

clear_storage() click to toggle source
# File lib/capybara/selenium/driver.rb, line 330
def clear_storage
  if options[: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
  if options[: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
end
find_headless_modal(text: nil, **options) click to toggle source
# File lib/capybara/selenium/driver.rb, line 439
def find_headless_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
      called, alert_text = evaluate_script('window.capybara && window.capybara.current_modal_status()')
      if called
        execute_script('window.capybara && window.capybara.modal_handlers.shift()')
        regexp = text.is_a?(Regexp) ? text : Regexp.escape(text.to_s)
        raise Capybara::ModalNotFound, "Unable to find modal dialog#{" with #{text}" if text}" unless alert_text.match(regexp)
        alert_text
      elsif called.nil?
        # page changed so modal_handler data has gone away
        warn "Can't verify modal text when page change occurs - ignoring" if options[:text]
        ""
      else
        nil
      end
    end
  rescue Selenium::WebDriver::Error::TimeOutError
    raise Capybara::ModalNotFound, "Unable to find modal dialog#{" with #{options[:text]}" if options[:text]}"
  end
end
find_modal(text: nil, **options) click to toggle source
# File lib/capybara/selenium/driver.rb, line 421
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
insert_modal_handlers(accept, response_text) click to toggle source
# File lib/capybara/selenium/driver.rb, line 355
  def insert_modal_handlers(accept, response_text)
    prompt_response = if accept
      if response_text.nil?
        "default_text"
      else
        "'#{response_text.gsub('\\', '\\\\\\').gsub("'", "\\\\'")}'"
      end
    else
      'null'
    end

    script = <<-JS
      if (typeof window.capybara  === 'undefined') {
        window.capybara = {
          modal_handlers: [],
          current_modal_status: function() {
            return [this.modal_handlers[0].called, this.modal_handlers[0].modal_text];
          },
          add_handler: function(handler) {
            this.modal_handlers.unshift(handler);
          },
          remove_handler: function(handler) {
            window.alert = handler.alert;
            window.confirm = handler.confirm;
            window.prompt = handler.prompt;
          },
          handler_called: function(handler, str) {
            handler.called = true;
            handler.modal_text = str;
            this.remove_handler(handler);
          }
        };
      };

      var modal_handler = {
        prompt: window.prompt,
        confirm: window.confirm,
        alert: window.alert,
        called: false
      }
      window.capybara.add_handler(modal_handler);

      window.alert = window.confirm = function(str = "") {
        window.capybara.handler_called(modal_handler, str.toString());
        return #{accept ? 'true' : 'false'};
      }
      window.prompt = function(str = "", default_text = "") {
        window.capybara.handler_called(modal_handler, str.toString());
        return #{prompt_response};
      }
    JS
    execute_script script
  end
modal_error() click to toggle source
silenced_unknown_error_message?(msg) click to toggle source
# File lib/capybara/selenium/driver.rb, line 467
def silenced_unknown_error_message?(msg)
  silenced_unknown_error_messages.any? { |r| msg =~ r }
end
silenced_unknown_error_messages() click to toggle source
# File lib/capybara/selenium/driver.rb, line 471
def silenced_unknown_error_messages
  [/Error communicating with the remote browser/]
end
unwrap_script_result(arg) click to toggle source
# File lib/capybara/selenium/driver.rb, line 475
def unwrap_script_result(arg)
  case arg
  when Array
    arg.map { |e| unwrap_script_result(e) }
  when Hash
    arg.each { |k, v| arg[k] = unwrap_script_result(v) }
  when Selenium::WebDriver::Element
    Capybara::Selenium::Node.new(self, arg)
  else
    arg
  end
end
within_given_window(handle) { || ... } click to toggle source
# File lib/capybara/selenium/driver.rb, line 409
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