selenium-webdriver 4.0.0.beta1 → 4.0.0.rc1

data/lib/selenium/webdriver/common/driver_extensions/prints_page.rb

@@ -21,8 +21,35 @@ module Selenium
   module WebDriver
     module DriverExtensions
       module PrintsPage
+        #
+        # Save a page as a PDF to the given path
+        #
+        # @example Save Printed Page
+        #   driver.save_print_page('../printed_page.pdf')
+        #
+        # @param [String] path to where the pdf should be saved
+        #
+        # @api public
+        #
+
+        def save_print_page(path, **options)
+          File.open(path, 'wb') do |file|
+            content = Base64.decode64 print_page(options)
+            file << content
+          end
+        end
+
+        #
+        # Return a Base64 encoded Print Page as a string
+        #
+        # @see https://w3c.github.io/webdriver/#print-page
+        #
+        # @api public
+        #
+
         def print_page(**options)
-          options[:page_ranges] &&= Array(options[:page_ranges])
+          options[:pageRanges] = Array(options.delete(:page_ranges)) || []
+          options[:shrinkToFit] = options.delete(:shrink_to_fit) { true }
 
           @bridge.print_page(options)
         end

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

@@ -92,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,
@@ -106,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
 
       #
@@ -268,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  --------------------------------
 
       #
@@ -287,14 +346,13 @@ module Selenium
       #
       alias_method :[], :attribute
 
-      #
-      # for SearchContext and execute_script
       #
       # @api private
+      # @see SearchContext
       #
 
       def ref
-        @id
+        [:element, @id]
       end
 
       #
@@ -330,7 +388,7 @@ module Selenium
       end
 
       def screenshot
-        bridge.element_screenshot(self)
+        bridge.element_screenshot(@id)
       end
     end # Element
   end # WebDriver

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/logger.rb

@@ -108,10 +108,11 @@ module Selenium
       #
       # @param [String] old
       # @param [String, nil] new
-      # @param [Symbol, Array<Sybmol>] id
+      # @param [Symbol, Array<Symbol>] id
+      # @param [String] reference
       # @yield appends additional message to end of provided template
       #
-      def deprecate(old, new = nil, id: [], &block)
+      def deprecate(old, new = nil, id: [], reference: '', &block)
         id = Array(id)
         return if @ignored.include?(:deprecations) || (@ignored & id).any?
 
@@ -123,6 +124,8 @@ module Selenium
                    else
                      ' and will be removed in a future release.'
                    end
+        message << " See explanation for this deprecation: #{reference}." unless reference.empty?
+
         warn message, &block
       end
 

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

@@ -23,16 +23,42 @@ module Selenium
       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].freeze
 
-      def self.set_capabilities
-        (W3C_OPTIONS + self::CAPABILITIES.keys).each do |key|
-          next if method_defined? key
+      class << self
+        attr_reader :driver_path
 
-          define_method key do
-            @options[key]
-          end
+        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 |value|
-            @options[key] = value
+            define_method key do
+              @options[key]
+            end
+
+            define_method "#{key}=" do |value|
+              @options[key] = value
+            end
           end
         end
       end
@@ -68,6 +94,14 @@ module Selenium
         @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
       #
@@ -75,12 +109,11 @@ module Selenium
       def as_json(*)
         options = @options.dup
 
-        w3c_options = options.select { |key, _val| W3C_OPTIONS.include?(key) }
-        options.delete_if { |key, _val| W3C_OPTIONS.include?(key) }
+        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 unless capability_value.nil?
+          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
 
@@ -90,6 +123,13 @@ module Selenium
 
       private
 
+      def process_w3c_options(options)
+        w3c_options = options.select { |key, _val| W3C_OPTIONS.include?(key) }
+        w3c_options[:unhandled_prompt_behavior] &&= w3c_options[:unhandled_prompt_behavior]&.to_s&.tr('_', ' ')
+        options.delete_if { |key, _val| W3C_OPTIONS.include?(key) }
+        w3c_options
+      end
+
       def process_browser_options(_browser_options)
         nil
       end
@@ -100,12 +140,7 @@ module Selenium
 
       def generate_as_json(value, camelize_keys: true)
         if value.is_a?(Hash)
-          value.each_with_object({}) do |(key, val), hash|
-            next if val.respond_to?(:empty?) && val.empty?
-
-            key = convert_json_key(key, camelize: camelize_keys)
-            hash[key] = generate_as_json(val, camelize_keys: camelize?(key))
-          end
+          process_json_hash(value, camelize_keys)
         elsif value.respond_to?(:as_json)
           value.as_json
         elsif value.is_a?(Array)
@@ -117,6 +152,16 @@ module Selenium
         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

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,

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

@@ -93,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

@@ -44,6 +44,7 @@ module Selenium
         def edge(**opts)
           Edge::Service.new(**opts)
         end
+        alias_method :microsoftedge, :edge
 
         def safari(**opts)
           Safari::Service.new(**opts)

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