[rb] deprecate :desired_capabilities and :options in driver initializ…

…ation in favor of :capabilities (SeleniumHQ#7832)

Co-authored-by: David Burns <david.burns@theautomatedtester.co.uk>

rb/lib/selenium/webdriver/chrome/options.rb

@@ -24,6 +24,7 @@ class Options < WebDriver::Options
         attr_accessor :profile
 
         KEY = 'goog:chromeOptions'
+        BROWSER = 'chrome'
 
         # see: http://chromedriver.chromium.org/capabilities
         CAPABILITIES = {args: 'args',
@@ -179,30 +180,23 @@ def add_emulation(**opts)
           @options[:emulation] = opts
         end
 
-        #
-        # @api private
-        #
-
-        def as_json(*)
-          options = super
-
-          if @profile
-            options['args'] ||= []
-            options['args'] << "--user-data-dir=#{@profile[:directory]}"
-          end
+        private
 
+        def process_browser_options(browser_options)
+          options = browser_options[KEY]
           options['binary'] ||= binary_path if binary_path
-          extensions = options['extensions'] || []
-          encoded_extensions = options.delete(:encoded_extensions) || []
+          (options['args'] || []) << "--user-data-dir=#{@profile[:directory]}" if @profile
+          merge_extensions(options)
+        end
 
-          options['extensions'] = extensions.map(&method(:encode_extension)) + encoded_extensions
-          options.delete('extensions') if options['extensions'].empty?
+        def merge_extensions(browser_options)
+          extensions = browser_options['extensions'] || []
+          encoded_extensions = browser_options.delete(:encoded_extensions) || []
 
-          {KEY => generate_as_json(options)}
+          browser_options['extensions'] = extensions.map(&method(:encode_extension)) + encoded_extensions
+          browser_options.delete('extensions') if browser_options['extensions'].empty?
         end
 
-        private
-
         def binary_path
           Chrome.path
         end

rb/lib/selenium/webdriver/common/driver.rb

@@ -296,9 +296,41 @@ def ref; end
 
       def create_bridge(**opts)
         opts[:url] ||= service_url(opts)
+        caps = opts.delete(:capabilities)
+        # Note: This is deprecated
+        cap_array = caps.is_a?(Hash) ? [caps] : Array(caps)
+
+        desired_capabilities = opts.delete(:desired_capabilities)
+        if desired_capabilities
+          WebDriver.logger.deprecate(':desired_capabilities as a parameter for driver initialization',
+                                     ':capabilities with an Array value of capabilities/options if necessary',
+                                     id: :desired_capabilities)
+          desired_capabilities = Remote::Capabilities.new(desired_capabilities) if desired_capabilities.is_a?(Hash)
+          cap_array << desired_capabilities
+        end
 
-        desired_capabilities = opts.delete(:desired_capabilities) || Remote::Capabilities.send(browser || :new)
         options = opts.delete(:options)
+        if options
+          WebDriver.logger.deprecate(':options as a parameter for driver initialization',
+                                     ':capabilities with an Array of value capabilities/options if necessary',
+                                     id: :browser_options)
+          cap_array << options
+        end
+
+        capabilities = cap_array.map { |cap|
+          if cap.is_a? Symbol
+            cap = Remote::Capabilities.send(cap)
+          elsif cap.is_a? Hash
+            WebDriver.logger.deprecate("passing a Hash value to :capabilities",
+                                       'Capabilities instance initialized with the Hash, or build values with Options class',
+                                       id: :capabilities_hash)
+            cap = Remote::Capabilities.new(cap)
+          elsif !cap.respond_to? :as_json
+            msg = ":capabilities parameter only accepts objects responding to #as_json which #{cap.class} does not"
+            raise ArgumentError, msg
+          end
+          cap&.as_json
+        }.inject(:merge) || Remote::Capabilities.send(browser || :new)
 
         bridge = Remote::Bridge.new(http_client: opts.delete(:http_client), url: opts.delete(:url))
         raise ArgumentError, "Unable to create a driver with parameters: #{opts}" unless opts.empty?
@@ -309,7 +341,7 @@ def create_bridge(**opts)
           bridge.extend Object.const_get("#{namespacing[0, namespacing.length - 1].join('::')}::Bridge")
         end
 
-        bridge.create_session(desired_capabilities, options)
+        bridge.create_session(capabilities)
         bridge
       end
 

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

@@ -20,6 +20,19 @@
 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].freeze
+
+      W3C_OPTIONS.each do |key|
+        define_method key do
+          @options[key]
+        end
+
+        define_method "#{key}=" do |value|
+          @options[key] = value
+        end
+      end
+
       attr_accessor :options
 
       def initialize(options: nil, **opts)
@@ -31,6 +44,7 @@ def initialize(options: nil, **opts)
                    else
                      opts
                    end
+        @options[:browser_name] = self.class::BROWSER
       end
 
       #
@@ -55,11 +69,17 @@ def add_option(name, value)
       def as_json(*)
         options = @options.dup
 
-        opts = self.class::CAPABILITIES.each_with_object({}) do |(capability_alias, capability_name), hash|
+        w3c_options = options.select { |key, _val| W3C_OPTIONS.include?(key) }
+        options.delete_if { |key, _val| W3C_OPTIONS.include?(key) }
+
+        self.class::CAPABILITIES.each do |capability_alias, capability_name|
           capability_value = options.delete(capability_alias)
-          hash[capability_name] = capability_value unless capability_value.nil?
+          options[capability_name] = capability_value unless capability_value.nil?
         end
-        opts.merge(options)
+        browser_options = defined?(self.class::KEY) ? {self.class::KEY => options} : options
+
+        process_browser_options(browser_options) if private_methods(false).include?(:process_browser_options)
+        generate_as_json(w3c_options.merge(browser_options))
       end
 
       private

rb/lib/selenium/webdriver/edge_chrome/options.rb

@@ -23,6 +23,8 @@ module Selenium
   module WebDriver
     module EdgeChrome
       class Options < Selenium::WebDriver::Chrome::Options
+        BROWSER = 'MSEdge'
+
         private
 
         def binary_path

rb/lib/selenium/webdriver/edge_html/options.rb

@@ -25,6 +25,7 @@ class Options < WebDriver::Options
         CAPABILITIES = {in_private: 'ms:inPrivate',
                         extension_paths: 'ms:extensionPaths',
                         start_page: 'ms:startPage'}.freeze
+        BROWSER = 'MicrosoftEdge'
 
         CAPABILITIES.each_key do |key|
           define_method key do
@@ -72,14 +73,6 @@ def add_extension_path(path)
           @options[:extension_paths] << path
         end
 
-        #
-        # @api private
-        #
-
-        def as_json(*)
-          generate_as_json(super)
-        end
-
         private
 
         def validate_extension(path)

rb/lib/selenium/webdriver/firefox/options.rb

@@ -29,6 +29,7 @@ class Options < WebDriver::Options
                         profile: 'profile',
                         log: 'log',
                         prefs: 'prefs'}.freeze
+        BROWSER = 'firefox'
 
         CAPABILITIES.each_key do |key|
           define_method key do
@@ -134,19 +135,13 @@ def log_level=(level)
           @options[:log] = {level: level}
         end
 
-        #
-        # @api private
-        #
+        private
 
-        def as_json(*)
-          options = super
+        def process_browser_options(browser_options)
+          options = browser_options[KEY]
           options['binary'] ||= Firefox.path if Firefox.path
-
-          {KEY => generate_as_json(options)}
         end
 
-        private
-
         def process_profile(profile)
           @options[:profile] = if profile.nil?
                                  nil

rb/lib/selenium/webdriver/ie/options.rb

@@ -41,6 +41,7 @@ class Options < WebDriver::Options
           use_per_process_proxy: 'ie.usePerProcessProxy',
           validate_cookie_document_type: 'ie.validateCookieDocumentType'
         }.freeze
+        BROWSER = 'internet_explorer'
 
         CAPABILITIES.each_key do |key|
           define_method key do
@@ -102,15 +103,11 @@ def add_argument(arg)
           @args << arg
         end
 
-        #
-        # @api private
-        #
+        private
 
-        def as_json(*)
-          options = super
+        def process_browser_options(browser_options)
+          options = browser_options[KEY]
           options['ie.browserCommandLineSwitches'] = @args.to_a.join(' ') if @args.any?
-
-          {KEY => generate_as_json(options)}
         end
       end # Options
     end # IE

rb/lib/selenium/webdriver/remote/bridge.rb

@@ -48,8 +48,8 @@ def initialize(http_client: nil, url:)
         # Creates session.
         #
 
-        def create_session(desired_capabilities, options = nil)
-          response = execute(:new_session, {}, merged_capabilities(desired_capabilities, options))
+        def create_session(capabilities)
+          response = execute(:new_session, {}, {capabilities: {firstMatch: [capabilities]}})
 
           @session_id = response['sessionId']
           capabilities = response['capabilities']
@@ -571,16 +571,6 @@ def commands(command)
           COMMANDS[command]
         end
 
-        def merged_capabilities(capabilities, options = nil)
-          capabilities.merge!(options.as_json) if options
-
-          {
-            capabilities: {
-              firstMatch: [capabilities]
-            }
-          }
-        end
-
         def unwrap_script_result(arg)
           case arg
           when Array

rb/lib/selenium/webdriver/safari/options.rb

@@ -26,6 +26,7 @@ class Options < WebDriver::Options
         # @see https://developer.apple.com/documentation/webkit/about_webdriver_for_safari
         CAPABILITIES = {automatic_inspection: 'safari:automaticInspection',
                         automatic_profiling: 'safari:automaticProfiling'}.freeze
+        BROWSER = 'safari'
 
         CAPABILITIES.each_key do |key|
           define_method key do
@@ -52,14 +53,6 @@ class Options < WebDriver::Options
         def initialize(**opts)
           super
         end
-
-        #
-        # @api private
-        #
-
-        def as_json(*)
-          generate_as_json(super)
-        end
       end # Options
     end # Safari
   end # WebDriver