selenium-webdriver 4.0.0.alpha2 → 4.0.0

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

@@ -30,6 +30,7 @@ module Selenium
         link_text: 'link text',
         name: 'name',
         partial_link_text: 'partial link text',
+        relative: 'relative',
         tag_name: 'tag name',
         xpath: 'xpath'
       }.freeze
@@ -59,7 +60,7 @@ module Selenium
         by = FINDERS[how.to_sym]
         raise ArgumentError, "cannot find element by #{how.inspect}" unless by
 
-        bridge.find_element_by by, what.to_s, ref
+        bridge.find_element_by by, what, ref
       rescue Selenium::WebDriver::Error::TimeoutError
         # Implicit Wait times out in Edge
         raise Selenium::WebDriver::Error::NoSuchElementError
@@ -77,7 +78,7 @@ module Selenium
         by = FINDERS[how.to_sym]
         raise ArgumentError, "cannot find elements by #{how.inspect}" unless by
 
-        bridge.find_elements_by by, what.to_s, ref
+        bridge.find_elements_by by, what, ref
       rescue Selenium::WebDriver::Error::TimeoutError
         # Implicit Wait times out in Edge
         []
@@ -92,7 +93,10 @@ module Selenium
         when 1
           arg = args.first
 
-          raise ArgumentError, "expected #{arg.inspect}:#{arg.class} to respond to #shift" unless arg.respond_to?(:shift)
+          unless arg.respond_to?(:shift)
+            raise ArgumentError,
+                  "expected #{arg.inspect}:#{arg.class} to respond to #shift"
+          end
 
           # this will be a single-entry hash, so use #shift over #first or #[]
           arr = arg.dup.shift

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

@@ -21,36 +21,33 @@ module Selenium
   module WebDriver
     #
     # Base class implementing default behavior of service object,
-    # responsible for starting and stopping driver implementations.
+    # responsible for storing a service manager configuration.
     #
 
     class Service
-      START_TIMEOUT = 20
-      SOCKET_LOCK_TIMEOUT = 45
-      STOP_TIMEOUT = 20
-
       class << self
         attr_reader :driver_path
 
-        def chrome(*args)
-          Chrome::Service.new(*args)
+        def chrome(**opts)
+          Chrome::Service.new(**opts)
         end
 
-        def firefox(*args)
-          Firefox::Service.new(*args)
+        def firefox(**opts)
+          Firefox::Service.new(**opts)
         end
 
-        def ie(*args)
-          IE::Service.new(*args)
+        def ie(**opts)
+          IE::Service.new(**opts)
         end
         alias_method :internet_explorer, :ie
 
-        def edge(*args)
-          Edge::Service.new(*args)
+        def edge(**opts)
+          Edge::Service.new(**opts)
         end
+        alias_method :microsoftedge, :edge
 
-        def safari(*args)
-          Safari::Service.new(*args)
+        def safari(**opts)
+          Safari::Service.new(**opts)
         end
 
         def driver_path=(path)
@@ -60,7 +57,7 @@ module Selenium
       end
 
       attr_accessor :host
-      attr_reader :executable_path
+      attr_reader :executable_path, :port, :extra_args
 
       #
       # End users should use a class method for the desired driver, rather than using this directly.
@@ -82,31 +79,20 @@ module Selenium
         raise Error::WebDriverError, "invalid port: #{@port}" if @port < 1
       end
 
-      def start
-        raise "already started: #{uri.inspect} #{@executable_path.inspect}" if process_running?
-
-        Platform.exit_hook(&method(:stop)) # make sure we don't leave the server running
-
-        socket_lock.locked do
-          find_free_port
-          start_process
-          connect_until_stable
-        end
+      def launch
+        sm = ServiceManager.new(self)
+        sm.start
+        sm
       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
+      def shutdown_supported
+        self.class::SHUTDOWN_SUPPORTED
       end
 
-      def uri
-        @uri ||= URI.parse("http://#{@host}:#{@port}")
+      protected
+
+      def extract_service_args(driver_opts)
+        driver_opts.key?(:args) ? driver_opts.delete(:args) : []
       end
 
       private
@@ -120,82 +106,6 @@ module Selenium
         Platform.assert_executable path
         path
       end
-
-      def build_process(*command)
-        WebDriver.logger.debug("Executing Process #{command}")
-        @process = ChildProcess.build(*command)
-        if WebDriver.logger.debug?
-          @process.io.stdout = @process.io.stderr = WebDriver.logger.io
-        elsif Platform.jruby?
-          # Apparently we need to read the output of drivers on JRuby.
-          @process.io.stdout = @process.io.stderr = File.new(Platform.null_device, 'w')
-        end
-
-        @process
-      end
-
-      def connect_to_server
-        Net::HTTP.start(@host, @port) do |http|
-          http.open_timeout = STOP_TIMEOUT / 2
-          http.read_timeout = STOP_TIMEOUT / 2
-
-          yield http
-        end
-      end
-
-      def find_free_port
-        @port = PortProber.above(@port)
-      end
-
-      def start_process
-        @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&.alive?
-      end
-
-      def process_exited?
-        @process.nil? || @process.exited?
-      end
-
-      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
-        "unable to connect to #{self.class::EXECUTABLE} #{@host}:#{@port}"
-      end
-
-      def socket_lock
-        @socket_lock ||= SocketLock.new(@port - 1, SOCKET_LOCK_TIMEOUT)
-      end
-
-      protected
-
-      def extract_service_args(driver_opts)
-        driver_opts.key?(:args) ? driver_opts.delete(:args) : []
-      end
-
     end # Service
   end # WebDriver
 end # Selenium

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

@@ -0,0 +1,151 @@
+# 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
+# regarding copyright ownership.  The SFC licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
+module Selenium
+  module WebDriver
+    #
+    # Base class implementing default behavior of service_manager object,
+    # responsible for starting and stopping driver implementations.
+    #
+    # @api private
+    #
+    class ServiceManager
+      START_TIMEOUT = 20
+      SOCKET_LOCK_TIMEOUT = 45
+      STOP_TIMEOUT = 20
+
+      #
+      # End users should use a class method for the desired driver, rather than using this directly.
+      #
+      # @api private
+      #
+
+      def initialize(config)
+        @executable_path = config.executable_path
+        @host = Platform.localhost
+        @port = config.port
+        @extra_args = config.extra_args
+        @shutdown_supported = config.shutdown_supported
+
+        raise Error::WebDriverError, "invalid port: #{@port}" if @port < 1
+      end
+
+      def start
+        raise "already started: #{uri.inspect} #{@executable_path.inspect}" if process_running?
+
+        Platform.exit_hook(&method(:stop)) # make sure we don't leave the server running
+
+        socket_lock.locked do
+          find_free_port
+          start_process
+          connect_until_stable
+        end
+      end
+
+      def stop
+        return unless @shutdown_supported
+
+        stop_server
+        @process.poll_for_exit STOP_TIMEOUT
+      rescue ChildProcess::TimeoutError
+        nil # noop
+      ensure
+        stop_process
+      end
+
+      def uri
+        @uri ||= URI.parse("http://#{@host}:#{@port}")
+      end
+
+      private
+
+      def build_process(*command)
+        WebDriver.logger.debug("Executing Process #{command}")
+        @process = ChildProcess.build(*command)
+        if WebDriver.logger.debug?
+          @process.io.stdout = @process.io.stderr = WebDriver.logger.io
+        elsif Platform.jruby?
+          # Apparently we need to read the output of drivers on JRuby.
+          @process.io.stdout = @process.io.stderr = File.new(Platform.null_device, 'w')
+        end
+
+        @process
+      end
+
+      def connect_to_server
+        Net::HTTP.start(@host, @port) do |http|
+          http.open_timeout = STOP_TIMEOUT / 2
+          http.read_timeout = STOP_TIMEOUT / 2
+
+          yield http
+        end
+      end
+
+      def find_free_port
+        @port = PortProber.above(@port)
+      end
+
+      def start_process
+        @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 do |http|
+          headers = WebDriver::Remote::Http::Common::DEFAULT_HEADERS.dup
+          http.get('/shutdown', headers)
+        end
+      end
+
+      def process_running?
+        defined?(@process) && @process&.alive?
+      end
+
+      def process_exited?
+        @process.nil? || @process.exited?
+      end
+
+      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
+        "unable to connect to #{@executable_path} #{@host}:#{@port}"
+      end
+
+      def socket_lock
+        @socket_lock ||= SocketLock.new(@port - 1, SOCKET_LOCK_TIMEOUT)
+      end
+    end # Service
+  end # WebDriver
+end # Selenium

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

@@ -0,0 +1,87 @@
+# 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
+# regarding copyright ownership.  The SFC licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
+module Selenium
+  module WebDriver
+    class ShadowRoot
+      ROOT_KEY = 'shadow-6066-11e4-a52e-4f735466cecf'
+
+      include SearchContext
+
+      #
+      # Creates a new shadow root
+      #
+      # @api private
+      #
+
+      def initialize(bridge, id)
+        @bridge = bridge
+        @id = id
+      end
+
+      def inspect
+        format '#<%<class>s:0x%<hash>x id=%<id>s>', class: self.class, hash: hash * 2, id: @id.inspect
+      end
+
+      def ==(other)
+        other.is_a?(self.class) && ref == other.ref
+      end
+      alias_method :eql?, :==
+
+      def hash
+        @id.hash ^ @bridge.hash
+      end
+
+      #
+      # @api private
+      # @see SearchContext
+      #
+
+      def ref
+        [:shadow_root, @id]
+      end
+
+      #
+      # Convert to a ShadowRoot JSON Object for transmission over the wire.
+      # @see https://github.com/SeleniumHQ/selenium/wiki/JsonWireProtocol#basic-terms-and-concepts
+      #
+      # @api private
+      #
+
+      def to_json(*)
+        JSON.generate as_json
+      end
+
+      #
+      # For Rails 3 - http://jonathanjulian.com/2010/04/rails-to_json-or-as_json/
+      #
+      # @api private
+      #
+
+      def as_json(*)
+        {ROOT_KEY => @id}
+      end
+
+      private
+
+      attr_reader :bridge
+
+    end # ShadowRoot
+  end # WebDriver
+end # Selenium

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

@@ -69,8 +69,8 @@ module Selenium
         ChildProcess.close_on_exec @server
 
         true
-      rescue SocketError, Errno::EADDRINUSE, Errno::EBADF => ex
-        WebDriver.logger.debug("#{self}: #{ex.message}")
+      rescue SocketError, Errno::EADDRINUSE, Errno::EBADF => e
+        WebDriver.logger.debug("#{self}: #{e.message}")
         false
       end
 

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

@@ -0,0 +1,66 @@
+# 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
+# regarding copyright ownership.  The SFC licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
+module Selenium
+  module WebDriver
+    #
+    # @api private
+    #
+    module TakesScreenshot
+      #
+      # Save a PNG screenshot of the viewport to the given path
+      #
+      # @api public
+      #
+
+      def save_screenshot(png_path, full_page: false)
+        extension = File.extname(png_path).downcase
+        if extension != '.png'
+          WebDriver.logger.warn "name used for saved screenshot does not match file type. "\
+                                "It should end with .png extension",
+                                id: :screenshot
+        end
+        File.open(png_path, 'wb') { |f| f << screenshot_as(:png, full_page: full_page) }
+      end
+
+      #
+      # Return a PNG screenshot in the given format as a string
+      #
+      # @param [:base64, :png] format
+      # @param [Boolean] full_page allows taking full page screenshots if supported
+      # @return String screenshot
+      #
+      # @api public
+
+      def screenshot_as(format, full_page: false)
+        case format
+        when :base64
+          full_page ? full_screenshot : screenshot
+        when :png
+          screenshot_as(:base64, full_page: full_page).unpack1('m')
+        else
+          raise Error::UnsupportedOperationError, "unsupported format: #{format.inspect}"
+        end
+      rescue NameError
+        raise Error::UnsupportedOperationError, "Full Page Screenshots are not supported for #{inspect}"
+      end
+
+    end # TakesScreenshot
+  end # WebDriver
+end # Selenium

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

@@ -44,6 +44,34 @@ module Selenium
         @bridge.switch_to_parent_frame
       end
 
+      #
+      # Switch to a new top-level browsing context
+      #
+      # @param type either :tab or :window
+      #
+
+      def new_window(type = :window)
+        unless %i[window tab].include?(type)
+          raise ArgumentError, "Valid types are :tab and :window, received: #{type.inspect}"
+        end
+
+        handle = @bridge.new_window(type)['handle']
+
+        if block_given?
+          execute_and_close = proc do
+            yield(self)
+            begin
+              @bridge.close
+            rescue Error::NoSuchWindowError
+              # window already closed
+            end
+          end
+          window(handle, &execute_and_close)
+        else
+          window(handle)
+        end
+      end
+
       #
       # switch to the given window handle
       #
@@ -57,10 +85,10 @@ module Selenium
       def window(id)
         if block_given?
           original = begin
-                       @bridge.window_handle
-                     rescue Error::NoSuchWindowError
-                       nil
-                     end
+            @bridge.window_handle
+          rescue Error::NoSuchWindowError
+            nil
+          end
 
           unless @bridge.window_handles.include? id
             raise Error::NoSuchWindowError, "The specified identifier '#{id}' is not found in the window handle list"

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

@@ -24,22 +24,49 @@ module Selenium
         @bridge = bridge
       end
 
+      #
+      # Gets the amount of time the driver should wait when searching for elements.
+      #
+
+      def implicit_wait
+        Float(@bridge.timeouts['implicit']) / 1000
+      end
+
       #
       # Set the amount of time the driver should wait when searching for elements.
       #
 
       def implicit_wait=(seconds)
-        @bridge.implicit_wait_timeout = Integer(seconds * 1000)
+        @bridge.timeouts = {'implicit' => Integer(seconds * 1000)}
       end
 
+      #
+      # Gets the amount of time to wait for an asynchronous script to finish
+      # execution before throwing an error.
+      #
+
+      def script
+        Float(@bridge.timeouts['script']) / 1000
+      end
+      alias_method :script_timeout, :script
+
       #
       # Sets the amount of time to wait for an asynchronous script to finish
       # execution before throwing an error. If the timeout is negative, then the
       # script will be allowed to run indefinitely.
       #
 
-      def script_timeout=(seconds)
-        @bridge.script_timeout = Integer(seconds * 1000)
+      def script=(seconds)
+        @bridge.timeouts = {'script' => Integer(seconds * 1000)}
+      end
+      alias_method :script_timeout=, :script=
+
+      #
+      # Gets the amount of time to wait for a page load to complete before throwing an error.
+      #
+
+      def page_load
+        Float(@bridge.timeouts['pageLoad']) / 1000
       end
 
       #
@@ -48,7 +75,7 @@ module Selenium
       #
 
       def page_load=(seconds)
-        @bridge.timeout 'page load', Integer(seconds * 1000)
+        @bridge.timeouts = {'pageLoad' => Integer(seconds * 1000)}
       end
     end # Timeouts
   end # WebDriver

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

@@ -55,7 +55,7 @@ module Selenium
           begin
             result = yield
             return result if result
-          rescue *@ignored => last_error
+          rescue *@ignored => last_error # rubocop:disable Naming/RescuedExceptionsVariableName
             # swallowed
           end
 

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

@@ -19,10 +19,6 @@
 
 module Selenium
   module WebDriver
-    #
-    # @api beta This API may be changed or removed in a future release.
-    #
-
     class Window
       #
       # @api private