selenium-webdriver 4.0.0.alpha2 → 4.0.0

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

@@ -23,6 +23,7 @@ module Selenium
       ELEMENT_KEY = 'element-6066-11e4-a52e-4f735466cecf'
 
       include SearchContext
+      include TakesScreenshot
 
       #
       # Creates a new Element
@@ -91,13 +92,18 @@ module Selenium
       end
 
       #
-      # Get the value of a the given attribute of the element. Will return the current value, even if
-      # this has been modified after the page has been loaded. More exactly, this method will return
-      # the value of the given attribute, unless that attribute is not present, in which case the
-      # value of the property with the same name is returned. If neither value is set, nil is
-      # returned. The "style" attribute is converted as best can be to a text representation with a
-      # trailing semi-colon. The following are deemed to be "boolean" attributes, and will
-      # return either "true" or "false":
+      # This method attempts to provide the most likely desired current value for the attribute
+      # of the element, even when that desired value is actually a JavaScript property.
+      # It is implemented with a custom JavaScript atom. To obtain the exact value of the attribute or property,
+      # use #dom_attribute or #property methods respectively.
+      #
+      # More exactly, this method will return the value of the property with the given name,
+      # if it exists. If it does not, then the value of the attribute with the given name is returned.
+      # If neither exists, null is returned.
+      #
+      # The "style" attribute is converted as best can be to a text representation with a trailing semi-colon.
+      #
+      # The following are deemed to be "boolean" attributes, and will return either "true" or "false":
       #
       # async, autofocus, autoplay, checked, compact, complete, controls, declare, defaultchecked,
       # defaultselected, defer, disabled, draggable, ended, formnovalidate, hidden, indeterminate,
@@ -105,29 +111,73 @@ module Selenium
       # nowrap, open, paused, pubdate, readonly, required, reversed, scoped, seamless, seeking,
       # selected, spellcheck, truespeed, willvalidate
       #
-      # Finally, the following commonly mis-capitalized attribute/property names are evaluated as
-      # expected:
+      # Finally, the following commonly mis-capitalized attribute/property names are evaluated as expected:
       #
-      # class, readonly
+      # When the value of "class" is requested, the "className" property is returned.
+      # When the value of "readonly" is requested, the "readOnly" property is returned.
       #
       # @param [String] name attribute name
       # @return [String, nil] attribute value
       #
+      # @see #dom_attribute
+      # @see #property
+      #
 
       def attribute(name)
         bridge.element_attribute self, name
       end
 
       #
-      # Get the value of a the given property with the same name of the element. If the value is not
-      # set, nil is returned.
+      # Gets the value of a declared HTML attribute of this element.
+      #
+      # As opposed to the #attribute method, this method
+      # only returns attributes declared in the element's HTML markup.
+      #
+      # If the attribute is not set, nil is returned.
+      #
+      # @param [String] name attribute name
+      # @return [String, nil] attribute value
+      #
+      # @see #attribute
+      # @see #property
+      #
+
+      def dom_attribute(name)
+        bridge.element_dom_attribute @id, name
+      end
+
+      #
+      # Gets the value of a JavaScript property of this element
+      # This will return the current value,
+      # even if this has been modified after the page has been loaded.
+      # If the value is not set, nil is returned.
       #
       # @param [String] name property name
       # @return [String, nil] property value
       #
 
       def property(name)
-        bridge.element_property self, name
+        bridge.element_property @id, name
+      end
+
+      #
+      # Gets the computed WAI-ARIA role of element
+      #
+      # @return [String]
+      #
+
+      def aria_role
+        bridge.element_aria_role @id
+      end
+
+      #
+      # Gets the computed WAI-ARIA label of element.
+      #
+      # @return [String]
+      #
+
+      def accessible_name
+        bridge.element_aria_label @id
       end
 
       #
@@ -267,6 +317,16 @@ module Selenium
         bridge.element_size @id
       end
 
+      #
+      # Returns the shadow root of an element.
+      #
+      # @return [WebDriver::ShadowRoot]
+      #
+
+      def shadow_root
+        bridge.shadow_root @id
+      end
+
       #-------------------------------- sugar  --------------------------------
 
       #
@@ -286,14 +346,13 @@ module Selenium
       #
       alias_method :[], :attribute
 
-      #
-      # for SearchContext and execute_script
       #
       # @api private
+      # @see SearchContext
       #
 
       def ref
-        @id
+        [:element, @id]
       end
 
       #
@@ -327,6 +386,10 @@ module Selenium
 
         tn == 'option' || (tn == 'input' && %w[radio checkbox].include?(type))
       end
+
+      def screenshot
+        bridge.element_screenshot(@id)
+      end
     end # Element
   end # WebDriver
 end # Selenium

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

@@ -61,6 +61,12 @@ module Selenium
 
       class StaleElementReferenceError < WebDriverError; end
 
+      #
+      # A command failed because the referenced shadow root is no longer attached to the DOM.
+      #
+
+      class DetachedShadowRootError < WebDriverError; end
+
       #
       # The target element is in an invalid state, rendering it impossible to interact with, for
       # example if you click a disabled element.
@@ -93,6 +99,12 @@ module Selenium
 
       class NoSuchWindowError < WebDriverError; end
 
+      #
+      # The element does not have a shadow root.
+      #
+
+      class NoSuchShadowRootError < WebDriverError; end
+
       #
       # An illegal attempt was made to set a cookie under a different domain than the current page.
       #

data/lib/selenium/webdriver/common/interactions/interaction.rb

@@ -26,7 +26,10 @@ module Selenium
         attr_reader :source
 
         def initialize(source)
-          raise TypeError, "#{source.type} is not a valid input type" unless Interactions::SOURCE_TYPES.include? source.type
+          unless Interactions::SOURCE_TYPES.include? source.type
+            raise TypeError,
+                  "#{source.type} is not a valid input type"
+          end
 
           @source = source
         end

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

@@ -30,14 +30,14 @@ module Selenium
 
       def as_json(*)
         {
-          'level' => level,
           'timestamp' => timestamp,
+          'level' => level,
           'message' => message
         }
       end
 
       def to_s
-        "#{level} #{time}: #{message}"
+        "#{time} #{level}: #{message}"
       end
 
       def time

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

@@ -40,13 +40,17 @@ module Selenium
                      :close,
                      :debug, :debug?,
                      :info, :info?,
-                     :warn, :warn?,
+                     :warn?,
                      :error, :error?,
                      :fatal, :fatal?,
                      :level, :level=
 
-      def initialize
-        @logger = create_logger($stdout)
+      #
+      # @param [String] progname Allow child projects to use Selenium's Logger pattern
+      #
+      def initialize(progname = 'Selenium')
+        @logger = create_logger(progname)
+        @ignored = []
       end
 
       #
@@ -73,28 +77,63 @@ module Selenium
         @logger.instance_variable_get(:@logdev).dev
       end
 
+      #
+      # Will not log the provided ID.
+      #
+      # @param [Array, Symbol] id
+      #
+      def ignore(id)
+        Array(id).each { |ignore| @ignored << ignore }
+      end
+
+      #
+      # Overrides default #warn to skip ignored messages by provided id
+      #
+      # @param [String] message
+      # @param [Symbol, Array<Sybmol>] id
+      # @yield see #deprecate
+      #
+      def warn(message, id: [])
+        id = Array(id)
+        return if (@ignored & id).any?
+
+        msg = id.empty? ? message : "[#{id.map(&:inspect).join(', ')}] #{message} "
+        msg += " #{yield}" if block_given?
+
+        @logger.warn { msg }
+      end
+
       #
       # Marks code as deprecated with/without replacement.
       #
       # @param [String] old
       # @param [String, nil] new
+      # @param [Symbol, Array<Symbol>] id
+      # @param [String] reference
+      # @yield appends additional message to end of provided template
       #
-      def deprecate(old, new = nil)
-        message = +"[DEPRECATION] #{old} is deprecated"
+      def deprecate(old, new = nil, id: [], reference: '', &block)
+        id = Array(id)
+        return if @ignored.include?(:deprecations) || (@ignored & id).any?
+
+        ids = id.empty? ? '' : "[#{id.map(&:inspect).join(', ')}] "
+
+        message = +"[DEPRECATION] #{ids}#{old} is deprecated"
         message << if new
                      ". Use #{new} instead."
                    else
-                     ' and will be removed in the next releases.'
+                     ' and will be removed in a future release.'
                    end
+        message << " See explanation for this deprecation: #{reference}." unless reference.empty?
 
-        warn message
+        warn message, &block
       end
 
       private
 
-      def create_logger(output)
-        logger = ::Logger.new(output)
-        logger.progname = 'Selenium'
+      def create_logger(name)
+        logger = ::Logger.new($stdout)
+        logger.progname = name
         logger.level = default_level
         logger.formatter = proc do |severity, time, progname, msg|
           "#{time.strftime('%F %T')} #{severity} #{progname} #{msg}\n"
@@ -104,11 +143,7 @@ module Selenium
       end
 
       def default_level
-        if $DEBUG || ENV.key?('DEBUG')
-          :debug
-        else
-          :warn
-        end
+        $DEBUG || ENV.key?('DEBUG') ? :debug : :warn
       end
     end # Logger
   end # WebDriver

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

@@ -36,6 +36,7 @@ module Selenium
       # @option opts [String] :value A value
       # @option opts [String] :path ('/') A path
       # @option opts [String] :secure (false) A boolean
+      # @option opts [String] :same_site (Strict or Lax) currently supported only in chrome 80+ versions
       # @option opts [Time,DateTime,Numeric,nil] :expires (nil) Expiry date, either as a Time, DateTime, or seconds since epoch.
       #
       # @raise [ArgumentError] if :name or :value is not specified
@@ -45,9 +46,15 @@ module Selenium
         raise ArgumentError, 'name is required' unless opts[:name]
         raise ArgumentError, 'value is required' unless opts[:value]
 
-        opts[:path] ||= '/'
+        # NOTE: This is required because of https://bugs.chromium.org/p/chromedriver/issues/detail?id=3732
         opts[:secure] ||= false
 
+        same_site = opts.delete(:same_site)
+        opts[:sameSite] = same_site if same_site
+
+        http_only = opts.delete(:http_only)
+        opts[:httpOnly] = http_only if http_only
+
         obj = opts.delete(:expires)
         opts[:expiry] = seconds_from(obj).to_i if obj
 
@@ -97,24 +104,19 @@ module Selenium
         @timeouts ||= Timeouts.new(@bridge)
       end
 
-      #
-      # @api beta This API may be changed or removed in a future release.
-      #
-
       def logs
+        WebDriver.logger.deprecate('Manager#logs', 'Chrome::Driver#logs')
         @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)
+        WebDriver.logger.deprecate('Manager#new_window', 'TargetLocator#new_window', id: :new_window) do
+          'e.g., `driver.switch_to.new_window(:tab)`'
+        end
         case type
         when :tab, :window
           result = @bridge.new_window(type)
@@ -129,10 +131,6 @@ module Selenium
         end
       end
 
-      #
-      # @api beta This API may be changed or removed in a future release.
-      #
-
       def window
         @window ||= Window.new(@bridge)
       end
@@ -169,6 +167,8 @@ module Selenium
           path: cookie['path'],
           domain: cookie['domain'] && strip_port(cookie['domain']),
           expires: cookie['expiry'] && datetime_at(cookie['expiry']),
+          same_site: cookie['sameSite'],
+          http_only: cookie['httpOnly'],
           secure: cookie['secure']
         }
       end

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

@@ -0,0 +1,186 @@
+# 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 Options
+      W3C_OPTIONS = %i[browser_name browser_version platform_name accept_insecure_certs page_load_strategy proxy
+                       set_window_rect timeouts unhandled_prompt_behavior strict_file_interactability
+                       web_socket_url].freeze
+
+      class << self
+        attr_reader :driver_path
+
+        def chrome(**opts)
+          Chrome::Options.new(**opts)
+        end
+
+        def firefox(**opts)
+          Firefox::Options.new(**opts)
+        end
+
+        def ie(**opts)
+          IE::Options.new(**opts)
+        end
+        alias_method :internet_explorer, :ie
+
+        def edge(**opts)
+          Edge::Options.new(**opts)
+        end
+        alias_method :microsoftedge, :edge
+
+        def safari(**opts)
+          Safari::Options.new(**opts)
+        end
+
+        def set_capabilities
+          (W3C_OPTIONS + self::CAPABILITIES.keys).each do |key|
+            next if method_defined? key
+
+            define_method key do
+              @options[key]
+            end
+
+            define_method "#{key}=" do |value|
+              @options[key] = value
+            end
+          end
+        end
+      end
+
+      attr_accessor :options
+
+      def initialize(options: nil, **opts)
+        self.class.set_capabilities
+
+        @options = if options
+                     WebDriver.logger.deprecate(":options as keyword for initializing #{self.class}",
+                                                "custom values directly in #new constructor",
+                                                id: :options_options)
+                     opts.merge(options)
+                   else
+                     opts
+                   end
+        @options[:browser_name] = self.class::BROWSER
+      end
+
+      #
+      # Add a new option not yet handled by bindings.
+      #
+      # @example Leave Chrome open when chromedriver is killed
+      #   options = Selenium::WebDriver::Chrome::Options.new
+      #   options.add_option(:detach, true)
+      #
+      # @param [String, Symbol] name Name of the option
+      # @param [Boolean, String, Integer] value Value of the option
+      #
+
+      def add_option(name, value = nil)
+        @options[name.keys.first] = name.values.first if value.nil? && name.is_a?(Hash)
+        @options[name] = value
+      end
+
+      def ==(other)
+        return false unless other.is_a? self.class
+
+        as_json == other.as_json
+      end
+
+      alias_method :eql?, :==
+
+      #
+      # @api private
+      #
+
+      def as_json(*)
+        options = @options.dup
+
+        w3c_options = process_w3c_options(options)
+
+        self.class::CAPABILITIES.each do |capability_alias, capability_name|
+          capability_value = options.delete(capability_alias)
+          options[capability_name] = capability_value if !capability_value.nil? && !options.key?(capability_name)
+        end
+        browser_options = defined?(self.class::KEY) ? {self.class::KEY => options} : options
+
+        process_browser_options(browser_options)
+        generate_as_json(w3c_options.merge(browser_options))
+      end
+
+      private
+
+      def w3c?(key)
+        W3C_OPTIONS.include?(key) || key.to_s.include?(':')
+      end
+
+      def process_w3c_options(options)
+        w3c_options = options.select { |key, _val| w3c?(key) }
+        w3c_options[:unhandled_prompt_behavior] &&= w3c_options[:unhandled_prompt_behavior]&.to_s&.tr('_', ' ')
+        options.delete_if { |key, _val| w3c?(key) }
+        w3c_options
+      end
+
+      def process_browser_options(_browser_options)
+        nil
+      end
+
+      def camelize?(_key)
+        true
+      end
+
+      def generate_as_json(value, camelize_keys: true)
+        if value.is_a?(Hash)
+          process_json_hash(value, camelize_keys)
+        elsif value.respond_to?(:as_json)
+          value.as_json
+        elsif value.is_a?(Array)
+          value.map { |val| generate_as_json(val, camelize_keys: camelize_keys) }
+        elsif value.is_a?(Symbol)
+          value.to_s
+        else
+          value
+        end
+      end
+
+      def process_json_hash(value, camelize_keys)
+        value.each_with_object({}) do |(key, val), hash|
+          next if val.respond_to?(:empty?) && val.empty?
+
+          camelize = camelize_keys ? camelize?(key) : false
+          key = convert_json_key(key, camelize: camelize)
+          hash[key] = generate_as_json(val, camelize_keys: camelize)
+        end
+      end
+
+      def convert_json_key(key, camelize: true)
+        key = key.to_s if key.is_a?(Symbol)
+        key = camel_case(key) if camelize
+        return key if key.is_a?(String)
+
+        raise TypeError, "expected String or Symbol, got #{key.inspect}:#{key.class}"
+      end
+
+      def camel_case(str)
+        str.gsub(/_([a-z])/) { Regexp.last_match(1).upcase }
+      end
+    end
+
+    # Options
+  end # WebDriver
+end # Selenium

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

@@ -57,6 +57,8 @@ module Selenium
           :jenkins
         elsif ENV['APPVEYOR']
           :appveyor
+        elsif ENV['GITHUB_ACTIONS']
+          :github
         end
       end
 
@@ -95,7 +97,10 @@ module Selenium
       def wsl?
         return false unless linux?
 
-        File.read('/proc/version').include?('Microsoft')
+        File.read('/proc/version').downcase.include?('microsoft')
+      rescue Errno::EACCES
+        # the file cannot be accessed on Linux on DeX
+        false
       end
 
       def cygwin?

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

@@ -32,12 +32,10 @@ module Selenium
 
       def self.free?(port)
         Platform.interfaces.each do |host|
-          begin
-            TCPServer.new(host, port).close
-          rescue *IGNORED_ERRORS => ex
-            WebDriver.logger.debug("port prober could not bind to #{host}:#{port} (#{ex.message})")
-            # ignored - some machines appear unable to bind to some of their interfaces
-          end
+          TCPServer.new(host, port).close
+        rescue *IGNORED_ERRORS => e
+          WebDriver.logger.debug("port prober could not bind to #{host}:#{port} (#{e.message})")
+          # ignored - some machines appear unable to bind to some of their interfaces
         end
 
         true

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

@@ -31,8 +31,16 @@ module Selenium
         base.extend ClassMethods
       end
 
+      def self.decoded(json)
+        JSON.parse(json).fetch('zip')
+      end
+
+      def encoded
+        Zipper.zip(layout_on_disk)
+      end
+
       def as_json(*)
-        {"zip" => Zipper.zip(layout_on_disk)}
+        {"zip" => encoded}
       end
 
       def to_json(*)
@@ -63,7 +71,7 @@ module Selenium
 
       module ClassMethods
         def from_json(json)
-          data = JSON.parse(json).fetch('zip')
+          data = decoded(json)
 
           # can't use Tempfile here since it doesn't support File::BINARY mode on 1.8
           # can't use Dir.mktmpdir(&blk) because of http://jira.codehaus.org/browse/JRUBY-4082

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

@@ -127,7 +127,10 @@ module Selenium
       end
 
       def type=(type)
-        raise ArgumentError, "invalid proxy type: #{type.inspect}, expected one of #{TYPES.keys.inspect}" unless TYPES.key? type
+        unless TYPES.key? type
+          raise ArgumentError,
+                "invalid proxy type: #{type.inspect}, expected one of #{TYPES.keys.inspect}"
+        end
 
         if defined?(@type) && type != @type
           raise ArgumentError, "incompatible proxy type #{type.inspect} (already set to #{@type.inspect})"
@@ -138,10 +141,10 @@ module Selenium
 
       def as_json(*)
         json_result = {
-          'proxyType' => TYPES[type],
+          'proxyType' => TYPES[type].downcase,
           'ftpProxy' => ftp,
           'httpProxy' => http,
-          'noProxy' => no_proxy,
+          'noProxy' => no_proxy.is_a?(String) ? no_proxy.split(', ') : no_proxy,
           'proxyAutoconfigUrl' => pac,
           'sslProxy' => ssl,
           'autodetect' => auto_detect,