selenium-webdriver 3.141.0 → 3.142.3

data/lib/selenium/webdriver/common/logs.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 # Licensed to the Software Freedom Conservancy (SFC) under one
 # or more contributor license agreements.  See the NOTICE file
 # distributed with this work for additional information

data/lib/selenium/webdriver/common/{options.rb → manager.rb}

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 # Licensed to the Software Freedom Conservancy (SFC) under one
 # or more contributor license agreements.  See the NOTICE file
 # distributed with this work for additional information
@@ -17,7 +19,7 @@
 
 module Selenium
   module WebDriver
-    class Options
+    class Manager
       #
       # @api private
       #
@@ -103,6 +105,30 @@ module Selenium
         @logs ||= Logs.new(@bridge)
       end
 
+      #
+      # Create a new top-level browsing context
+      # https://w3c.github.io/webdriver/#new-window
+      # @param type [Symbol] Supports two values: :tab and :window.
+      #  Use :tab if you'd like the new window to share an OS-level window
+      #  with the current browsing context.
+      #  Use :window otherwise
+      # @return [String] The value of the window handle
+      #
+      def new_window(type = :tab)
+        case type
+        when :tab, :window
+          result = @bridge.new_window(type)
+          unless result.key?('handle')
+            raise UnknownError, "the driver did not return a handle. " \
+                                "The returned result: #{result.inspect}"
+          end
+          result['handle']
+        else
+          raise ArgumentError, "invalid argument for type. Got: '#{type.inspect}'. " \
+                               "Try :tab or :window"
+        end
+      end
+
       #
       # @api beta This API may be changed or removed in a future release.
       #

data/lib/selenium/webdriver/common/mouse.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 # Licensed to the Software Freedom Conservancy (SFC) under one
 # or more contributor license agreements.  See the NOTICE file
 # distributed with this work for additional information
@@ -79,6 +81,7 @@ module Selenium
 
       def assert_element(element)
         return if element.is_a? Element
+
         raise TypeError, "expected #{Element}, got #{element.inspect}:#{element.class}"
       end
     end # Mouse

data/lib/selenium/webdriver/common/navigation.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 # Licensed to the Software Freedom Conservancy (SFC) under one
 # or more contributor license agreements.  See the NOTICE file
 # distributed with this work for additional information

data/lib/selenium/webdriver/common/platform.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 # Licensed to the Software Freedom Conservancy (SFC) under one
 # or more contributor license agreements.  See the NOTICE file
 # distributed with this work for additional information
@@ -25,12 +27,11 @@ module Selenium
       module_function
 
       def home
-        # jruby has an issue with ENV['HOME'] on Windows
-        @home ||= jruby? ? ENV_JAVA['user.home'] : ENV['HOME']
+        @home ||= Dir.home
       end
 
       def engine
-        @engine ||= defined?(RUBY_ENGINE) ? RUBY_ENGINE.to_sym : :ruby
+        @engine ||= RUBY_ENGINE.to_sym
       end
 
       def os
@@ -50,8 +51,13 @@ module Selenium
       end
 
       def ci
-        return :travis if ENV['TRAVIS']
-        :jenkins if ENV['JENKINS']
+        if ENV['TRAVIS']
+          :travis
+        elsif ENV['JENKINS']
+          :jenkins
+        elsif ENV['APPVEYOR']
+          :appveyor
+        end
       end
 
       def bitsize
@@ -70,10 +76,6 @@ module Selenium
         engine == :jruby
       end
 
-      def ironruby?
-        engine == :ironruby
-      end
-
       def ruby_version
         RUBY_VERSION
       end
@@ -92,6 +94,7 @@ module Selenium
 
       def wsl?
         return false unless linux?
+
         File.read('/proc/version').include?('Microsoft')
       end
 
@@ -101,30 +104,35 @@ module Selenium
       end
 
       def null_device
-        @null_device ||= if defined?(File::NULL)
-                           File::NULL
-                         else
-                           Platform.windows? ? 'NUL' : '/dev/null'
-                         end
+        File::NULL
       end
 
       def wrap_in_quotes_if_necessary(str)
         windows? && !cygwin? ? %("#{str}") : str
       end
 
-      def cygwin_path(path, opts = {})
+      def cygwin_path(path, **opts)
         flags = []
         opts.each { |k, v| flags << "--#{k}" if v }
 
         `cygpath #{flags.join ' '} "#{path}"`.strip
       end
 
+      def unix_path(path)
+        path.tr(File::ALT_SEPARATOR, File::SEPARATOR)
+      end
+
+      def windows_path(path)
+        path.tr(File::SEPARATOR, File::ALT_SEPARATOR)
+      end
+
       def make_writable(file)
         File.chmod 0o766, file
       end
 
       def assert_file(path)
         return if File.file? path
+
         raise Error::WebDriverError, "not a file: #{path.inspect}"
       end
 
@@ -132,6 +140,7 @@ module Selenium
         assert_file(path)
 
         return if File.executable? path
+
         raise Error::WebDriverError, "not executable: #{path.inspect}"
       end
 
@@ -152,7 +161,7 @@ module Selenium
         binary_names.each do |binary_name|
           paths.each do |path|
             full_path = File.join(path, binary_name)
-            full_path.tr!('\\', '/') if windows?
+            full_path = unix_path(full_path) if windows?
             exe = Dir.glob(full_path).find { |f| File.executable?(f) }
             return exe if exe
           end
@@ -182,6 +191,7 @@ module Selenium
         info = Socket.getaddrinfo 'localhost', 80, Socket::AF_INET, Socket::SOCK_STREAM
 
         return info[0][3] unless info.empty?
+
         raise Error::WebDriverError, "unable to translate 'localhost' for TCP + IPv4"
       end
 
@@ -210,17 +220,3 @@ module Selenium
     end # Platform
   end # WebDriver
 end # Selenium
-
-if $PROGRAM_NAME == __FILE__
-  p engine: Selenium::WebDriver::Platform.engine,
-    os: Selenium::WebDriver::Platform.os,
-    ruby_version: Selenium::WebDriver::Platform.ruby_version,
-    jruby?: Selenium::WebDriver::Platform.jruby?,
-    windows?: Selenium::WebDriver::Platform.windows?,
-    home: Selenium::WebDriver::Platform.home,
-    bitsize: Selenium::WebDriver::Platform.bitsize,
-    localhost: Selenium::WebDriver::Platform.localhost,
-    ip: Selenium::WebDriver::Platform.ip,
-    interfaces: Selenium::WebDriver::Platform.interfaces,
-    null_device: Selenium::WebDriver::Platform.null_device
-end

data/lib/selenium/webdriver/common/port_prober.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 # Licensed to the Software Freedom Conservancy (SFC) under one
 # or more contributor license agreements.  See the NOTICE file
 # distributed with this work for additional information
@@ -23,25 +25,10 @@ module Selenium
         port
       end
 
-      def self.random
-        # TODO: Avoid this
-        #
-        # (a) should pick a port that's guaranteed to be free on all interfaces
-        # (b) should pick a random port outside the ephemeral port range
-        #
-        WebDriver.logger.deprecate 'PortProber.random', 'PortProber.above(port)'
-
-        server = TCPServer.new(Platform.localhost, 0)
-        port   = server.addr[1]
-        server.close
-
-        port
-      end
-
-      IGNORED_ERRORS = [Errno::EADDRNOTAVAIL, Errno::EAFNOSUPPORT]
-      IGNORED_ERRORS << Errno::EBADF if Platform.cygwin?
-      IGNORED_ERRORS << Errno::EACCES if Platform.windows?
-      IGNORED_ERRORS.freeze
+      IGNORED_ERRORS = [Errno::EADDRNOTAVAIL, Errno::EAFNOSUPPORT].tap { |arr|
+        arr << Errno::EBADF if Platform.cygwin?
+        arr << Errno::EACCES if Platform.windows?
+      }.freeze
 
       def self.free?(port)
         Platform.interfaces.each do |host|

data/lib/selenium/webdriver/common/profile_helper.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 # Licensed to the Software Freedom Conservancy (SFC) under one
 # or more contributor license agreements.  See the NOTICE file
 # distributed with this work for additional information

data/lib/selenium/webdriver/common/proxy.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 # Licensed to the Software Freedom Conservancy (SFC) under one
 # or more contributor license agreements.  See the NOTICE file
 # distributed with this work for additional information
@@ -35,7 +37,8 @@ module Selenium
                  auto_detect: 'autodetect',
                  socks: 'socksProxy',
                  socks_username: 'socksUsername',
-                 socks_password: 'socksPassword'}.freeze
+                 socks_password: 'socksPassword',
+                 socks_version: 'socksVersion'}.freeze
 
       ALLOWED.each_key { |t| attr_reader t }
 
@@ -64,6 +67,7 @@ module Selenium
         end
 
         return if not_allowed.empty?
+
         raise ArgumentError, "unknown option#{'s' if not_allowed.size != 1}: #{not_allowed.inspect}"
       end
 
@@ -117,10 +121,13 @@ module Selenium
         @socks_password = value
       end
 
+      def socks_version=(value)
+        self.type = :manual
+        @socks_version = value
+      end
+
       def type=(type)
-        unless TYPES.key? type
-          raise ArgumentError, "invalid proxy type: #{type.inspect}, expected one of #{TYPES.keys.inspect}"
-        end
+        raise ArgumentError, "invalid proxy type: #{type.inspect}, expected one of #{TYPES.keys.inspect}" unless TYPES.key? type
 
         if defined?(@type) && type != @type
           raise ArgumentError, "incompatible proxy type #{type.inspect} (already set to #{@type.inspect})"
@@ -140,7 +147,8 @@ module Selenium
           'autodetect' => auto_detect,
           'socksProxy' => socks,
           'socksUsername' => socks_username,
-          'socksPassword' => socks_password
+          'socksPassword' => socks_password,
+          'socksVersion' => socks_version
         }.delete_if { |_k, v| v.nil? }
 
         json_result if json_result.length > 1

data/lib/selenium/webdriver/common/search_context.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 # Licensed to the Software Freedom Conservancy (SFC) under one
 # or more contributor license agreements.  See the NOTICE file
 # distributed with this work for additional information
@@ -58,7 +60,7 @@ module Selenium
         raise ArgumentError, "cannot find element by #{how.inspect}" unless by
 
         bridge.find_element_by by, what.to_s, ref
-      rescue Selenium::WebDriver::Error::TimeOutError
+      rescue Selenium::WebDriver::Error::TimeoutError
         # Implicit Wait times out in Edge
         raise Selenium::WebDriver::Error::NoSuchElementError
       end
@@ -76,7 +78,7 @@ module Selenium
         raise ArgumentError, "cannot find elements by #{how.inspect}" unless by
 
         bridge.find_elements_by by, what.to_s, ref
-      rescue Selenium::WebDriver::Error::TimeOutError
+      rescue Selenium::WebDriver::Error::TimeoutError
         # Implicit Wait times out in Edge
         []
       end
@@ -90,15 +92,11 @@ module Selenium
         when 1
           arg = args.first
 
-          unless arg.respond_to?(:shift)
-            raise ArgumentError, "expected #{arg.inspect}:#{arg.class} to respond to #shift"
-          end
+          raise ArgumentError, "expected #{arg.inspect}:#{arg.class} to respond to #shift" unless arg.respond_to?(:shift)
 
           # this will be a single-entry hash, so use #shift over #first or #[]
           arr = arg.dup.shift
-          unless arr.size == 2
-            raise ArgumentError, "expected #{arr.inspect} to have 2 elements"
-          end
+          raise ArgumentError, "expected #{arr.inspect} to have 2 elements" unless arr.size == 2
 
           arr
         else

data/lib/selenium/webdriver/common/service.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 # Licensed to the Software Freedom Conservancy (SFC) under one
 # or more contributor license agreements.  See the NOTICE file
 # distributed with this work for additional information
@@ -21,50 +23,87 @@ module Selenium
     # Base class implementing default behavior of service object,
     # responsible for starting and stopping driver implementations.
     #
-    # Subclasses must implement the following private methods:
-    #   * #start_process
-    #   * #stop_server
-    #   * #cannot_connect_error_text
-    #
-    # @api private
-    #
 
     class Service
-      START_TIMEOUT       = 20
+      START_TIMEOUT = 20
       SOCKET_LOCK_TIMEOUT = 45
-      STOP_TIMEOUT        = 20
+      STOP_TIMEOUT = 20
 
+      @default_port = nil
+      @driver_path = nil
       @executable = nil
       @missing_text = nil
 
       class << self
-        attr_reader :executable, :missing_text
+        attr_reader :default_port, :driver_path, :executable, :missing_text, :shutdown_supported
+
+        def chrome(**opts)
+          Chrome::Service.new(**opts)
+        end
+
+        def firefox(**opts)
+          binary_path = Firefox::Binary.path
+          args = opts.delete(:args)
+          case args
+          when Hash
+            args[:binary] ||= binary_path
+            opts[:args] = args
+          when Array
+            opts[:args] = ["--binary=#{binary_path}"]
+            opts[:args] += args
+          else
+            opts[:args] = ["--binary=#{binary_path}"]
+          end
+
+          Firefox::Service.new(**opts)
+        end
+
+        def ie(**opts)
+          IE::Service.new(**opts)
+        end
+        alias_method :internet_explorer, :ie
+
+        def edge(**opts)
+          Edge::Service.new(**opts)
+        end
+
+        def safari(**opts)
+          Safari::Service.new(**opts)
+        end
+
+        def driver_path=(path)
+          Platform.assert_executable path if path.is_a?(String)
+          @driver_path = path
+        end
       end
 
       attr_accessor :host
+      attr_reader :executable_path
 
-      def initialize(executable_path, port, driver_opts)
-        @executable_path = binary_path(executable_path)
-        @host            = Platform.localhost
-        @port            = Integer(port)
-        @extra_args      = extract_service_args(driver_opts)
+      #
+      # End users should use a class method for the desired driver, rather than using this directly.
+      #
+      # @api private
+      #
 
-        raise Error::WebDriverError, "invalid port: #{@port}" if @port < 1
-      end
+      def initialize(path: nil, port: nil, args: nil)
+        path ||= self.class.driver_path
+        port ||= self.class.default_port
+        args ||= []
 
-      def binary_path(path)
-        path = Platform.find_binary(self.class.executable) if path.nil?
-        raise Error::WebDriverError, self.class.missing_text unless path
-        Platform.assert_executable path
-        path
+        @executable_path = binary_path(path)
+        @host = Platform.localhost
+        @port = Integer(port)
+
+        @extra_args = args.is_a?(Hash) ? extract_service_args(args) : args
+
+        raise Error::WebDriverError, "invalid port: #{@port}" if @port < 1
       end
 
       def start
-        if process_running?
-          raise "already started: #{uri.inspect} #{@executable_path.inspect}"
-        end
+        raise "already started: #{uri.inspect} #{@executable_path.inspect}" if process_running?
 
-        Platform.exit_hook { stop } # make sure we don't leave the server running
+        Platform.exit_hook(&method(:stop)) # make sure we don't leave the server running
 
         socket_lock.locked do
           find_free_port
@@ -74,9 +113,12 @@ module Selenium
       end
 
       def stop
+        return unless self.class.shutdown_supported
+
         stop_server
         @process.poll_for_exit STOP_TIMEOUT
       rescue ChildProcess::TimeoutError
+        nil # noop
       ensure
         stop_process
       end
@@ -87,6 +129,16 @@ module Selenium
 
       private
 
+      def binary_path(path = nil)
+        path = path.call if path.is_a?(Proc)
+        path ||= Platform.find_binary(self.class.executable)
+
+        raise Error::WebDriverError, self.class.missing_text unless path
+
+        Platform.assert_executable path
+        path
+      end
+
       def build_process(*command)
         WebDriver.logger.debug("Executing Process #{command}")
         @process = ChildProcess.build(*command)
@@ -114,22 +166,27 @@ module Selenium
       end
 
       def start_process
-        raise NotImplementedError, 'subclass responsibility'
+        @process = build_process(@executable_path, "--port=#{@port}", *@extra_args)
+        # Note: this is a bug only in Windows 7
+        @process.leader = true unless Platform.windows?
+        @process.start
       end
 
       def stop_process
         return if process_exited?
+
         @process.stop STOP_TIMEOUT
         @process.io.stdout.close if Platform.jruby? && !WebDriver.logger.debug?
       end
 
       def stop_server
         return if process_exited?
+
         connect_to_server { |http| http.get('/shutdown') }
       end
 
       def process_running?
-        defined?(@process) && @process && @process.alive?
+        defined?(@process) && @process&.alive?
       end
 
       def process_exited?
@@ -139,11 +196,12 @@ module Selenium
       def connect_until_stable
         socket_poller = SocketPoller.new @host, @port, START_TIMEOUT
         return if socket_poller.connected?
+
         raise Error::WebDriverError, cannot_connect_error_text
       end
 
       def cannot_connect_error_text
-        raise NotImplementedError, 'subclass responsibility'
+        "unable to connect to #{self.class.executable} #{@host}:#{@port}"
       end
 
       def socket_lock