selenium-webdriver 3.4.0 → 3.4.1

data/CHANGES

@@ -1,4 +1,38 @@
-3.4.0 (Unreleased)
+3.4.1 (2017-06-13)
+==================
+
+Ruby:
+  * Implemented a new dual-dialect mechanism for communication with drivers
+    (a.k.a. protocol handshake). There shouldn't be any noticeable differences
+    but since this is a significant refactoring of internal APIs, some bugs
+    could slip into the release.
+  * Renamed ElementClickIntercepted to ElementClickInterceptedError.
+  * Renamed ElementNotInteractable to ElementNotInteractableError.
+  * Deprecated W3CCapabilities in favor of Capabilities (it was meant to be private API).
+  * Added a warning when trying to save screenshot without .png extension (thanks @abotalov).
+
+IE:
+  * Added support for both old IEDriver which uses OSS dialect of JSON wire
+    protocol (<= 3.4.0) and new IEDriver which uses W3C dialect (not yet released).
+
+Safari:
+  * Removed runtime dependencies used for old SafariDriver (u.g. websocket).
+
+Chrome:
+  * Added new Chrome::Options class that should be used to customize browser
+    behavior (command line arguments, extensions, preferences, mobile emulation, etc.).
+    The instance of options class can be passed to driver initialization using
+    :options key. Old way of passing these customization directly to driver
+    initialization is deprecated.
+
+Firefox:
+  * Added new Firefox::Options class that should be used to customize browser
+    behavior (command line arguments, profile, preferences, Firefox binary, etc.).
+    The instance of options class can be passed to driver initialization using
+    :options key. Old way of passing these customization directly to driver
+    initialization is deprecated.
+
+3.4.0 (2017-04-21)
 ===================
 
 Edge:

data/Gemfile.lock

@@ -0,0 +1,54 @@
+PATH
+  remote: .
+  specs:
+    selenium-webdriver (3.4.1)
+      childprocess (~> 0.5)
+      rubyzip (~> 1.0)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    addressable (2.5.1)
+      public_suffix (~> 2.0, >= 2.0.2)
+    childprocess (0.7.0)
+      ffi (~> 1.0, >= 1.0.11)
+    crack (0.4.3)
+      safe_yaml (~> 1.0.0)
+    diff-lcs (1.3)
+    ffi (1.9.18)
+    hashdiff (0.3.4)
+    public_suffix (2.0.5)
+    rack (1.6.8)
+    rspec (3.6.0)
+      rspec-core (~> 3.6.0)
+      rspec-expectations (~> 3.6.0)
+      rspec-mocks (~> 3.6.0)
+    rspec-core (3.6.0)
+      rspec-support (~> 3.6.0)
+    rspec-expectations (3.6.0)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.6.0)
+    rspec-mocks (3.6.0)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.6.0)
+    rspec-support (3.6.0)
+    rubyzip (1.2.1)
+    safe_yaml (1.0.4)
+    webmock (2.3.2)
+      addressable (>= 2.3.6)
+      crack (>= 0.3.2)
+      hashdiff
+    yard (0.8.7.6)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  rack (~> 1.0)
+  rspec (~> 3.0)
+  selenium-webdriver!
+  webmock (~> 2.0)
+  yard (~> 0.8.7)
+
+BUNDLED WITH
+   1.15.1

data/lib/selenium/webdriver.rb

@@ -57,19 +57,17 @@ module Selenium
     # @overload for(browser, opts)
     #   @param [:ie, :internet_explorer, :edge, :remote, :chrome, :firefox, :ff, :phantomjs, :safari] browser The browser to
     #     create the driver for
-    #   @param [Hash] opts Options passed to Bridge.new
+    #   @param [Hash] opts Options passed to Driver.new
     #
     # @return [Driver]
     #
-    # @see Selenium::WebDriver::Remote::Bridge
-    # @see Selenium::WebDriver::Remote::W3CBridge
-    # @see Selenium::WebDriver::Firefox::Bridge
-    # @see Selenium::WebDriver::Firefox::W3CBridge
-    # @see Selenium::WebDriver::IE::Bridge
-    # @see Selenium::WebDriver::Edge::Bridge
-    # @see Selenium::WebDriver::Chrome::Bridge
-    # @see Selenium::WebDriver::PhantomJS::Bridge
-    # @see Selenium::WebDriver::Safari::Bridge
+    # @see Selenium::WebDriver::Remote::Driver
+    # @see Selenium::WebDriver::Firefox::Driver
+    # @see Selenium::WebDriver::IE::Driver
+    # @see Selenium::WebDriver::Edge::Driver
+    # @see Selenium::WebDriver::Chrome::Driver
+    # @see Selenium::WebDriver::PhantomJS::Driver
+    # @see Selenium::WebDriver::Safari::Driver
     #
     # @example
     #

data/lib/selenium/webdriver/chrome.rb

@@ -20,8 +20,9 @@
 require 'net/http'
 
 require 'selenium/webdriver/chrome/service'
-require 'selenium/webdriver/chrome/bridge'
+require 'selenium/webdriver/chrome/driver'
 require 'selenium/webdriver/chrome/profile'
+require 'selenium/webdriver/chrome/options'
 
 module Selenium
   module WebDriver

data/lib/selenium/webdriver/chrome/{bridge.rb → driver.rb}

@@ -20,8 +20,16 @@
 module Selenium
   module WebDriver
     module Chrome
+
+      #
+      # Driver implementation for Chrome.
       # @api private
-      class Bridge < Remote::Bridge
+      #
+
+      class Driver < WebDriver::Driver
+        include DriverExtensions::HasWebStorage
+        include DriverExtensions::TakesScreenshot
+
         def initialize(opts = {})
           opts[:desired_capabilities] = create_capabilities(opts)
 
@@ -31,16 +39,12 @@ module Selenium
 
             opts[:driver_opts] ||= {}
             if opts.key? :service_log_path
-              WebDriver.logger.warn <<-DEPRECATE.gsub(/\n +| {2,}/, ' ').freeze
-            [DEPRECATION] `:service_log_path` is deprecated. Use `driver_opts: {log_path: #{opts[:service_log_path]}}`
-              DEPRECATE
+              WebDriver.logger.deprecate ':service_log_path', "driver_opts: {log_path: '#{opts[:service_log_path]}'}"
               opts[:driver_opts][:log_path] = opts.delete :service_log_path
             end
 
             if opts.key? :service_args
-              WebDriver.logger.warn <<-DEPRECATE.gsub(/\n +| {2,}/, ' ').freeze
-            [DEPRECATION] `:service_args` is deprecated. Pass switches using `driver_opts`
-              DEPRECATE
+              WebDriver.logger.deprecate ':service_args', "driver_opts: {args: #{opts[:service_args]}}"
               opts[:driver_opts][:args] = opts.delete(:service_args)
             end
 
@@ -49,22 +53,15 @@ module Selenium
             opts[:url] = @service.uri
           end
 
-          super(opts)
+          listener = opts.delete(:listener)
+          @bridge = Remote::Bridge.handshake(opts)
+          super(@bridge, listener: listener)
         end
 
         def browser
           :chrome
         end
 
-        def driver_extensions
-          [DriverExtensions::TakesScreenshot,
-           DriverExtensions::HasWebStorage]
-        end
-
-        def capabilities
-          @capabilities ||= Remote::Capabilities.chrome
-        end
-
         def quit
           super
         ensure
@@ -75,34 +72,52 @@ module Selenium
 
         def create_capabilities(opts)
           caps = opts.delete(:desired_capabilities) { Remote::Capabilities.chrome }
+          options = opts.delete(:options) { Options.new }
 
-          chrome_options = caps['chromeOptions'] || caps[:chrome_options] || {}
-          chrome_options['binary'] = Chrome.path if Chrome.path
-          args = opts.delete(:args) || opts.delete(:switches) || []
+          args = opts.delete(:args)
+          if args
+            WebDriver.logger.deprecate ':args', 'Selenium::WebDriver::Chrome::Options#add_argument'
+            raise ArgumentError, ':args must be an Array of Strings' unless args.is_a? Array
+            args.each { |arg| options.add_argument(arg.to_s) }
+          end
+
+          profile = opts.delete(:profile)
+          if profile
+            profile = profile.as_json
+
+            if options.args.none? { |arg| arg =~ /user-data-dir/ }
+              options.add_argument("--user-data-dir=#{profile[:directory]}")
+            end
 
-          unless args.is_a? Array
-            raise ArgumentError, ':args must be an Array of Strings'
+            if profile[:extensions]
+              WebDriver.logger.deprecate 'Using Selenium::WebDriver::Chrome::Profile#extensions',
+                                         'Selenium::WebDriver::Chrome::Options#add_extension'
+              profile[:extensions].each do |extension|
+                options.add_encoded_extension(extension)
+              end
+            end
           end
 
-          args.map!(&:to_s)
-          profile = opts.delete(:profile).as_json if opts.key?(:profile)
+          detach = opts.delete(:detach)
+          options.add_option(:detach, true) if detach
 
-          if profile && args.none? { |arg| arg =~ /user-data-dir/ }
-            args << "--user-data-dir=#{profile[:directory]}"
+          prefs = opts.delete(:prefs)
+          if prefs
+            WebDriver.logger.deprecate ':prefs', 'Selenium::WebDriver::Chrome::Options#add_preference'
+            prefs.each do |key, value|
+              options.add_preference(key, value)
+            end
           end
-          chrome_options['args'] = args unless args.empty?
 
-          chrome_options['extensions'] = profile[:extensions] if profile && profile[:extensions]
-          chrome_options['detach'] = true if opts.delete(:detach)
-          chrome_options['prefs'] = opts.delete(:prefs) if opts.key?(:prefs)
+          options = options.as_json
+          caps[:chrome_options] = options unless options.empty?
 
-          caps[:chrome_options] = chrome_options unless chrome_options.empty?
           caps[:proxy] = opts.delete(:proxy) if opts.key?(:proxy)
           caps[:proxy] ||= opts.delete('proxy') if opts.key?('proxy')
 
           caps
         end
-      end # Bridge
+      end # Driver
     end # Chrome
   end # WebDriver
 end # Selenium

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

@@ -0,0 +1,170 @@
+# encoding: utf-8
+#
+# 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
+    module Chrome
+      class Options
+        attr_reader :args, :prefs, :options, :emulation, :extensions, :encoded_extensions
+        attr_accessor :binary
+
+        #
+        # Create a new Options instance.
+        #
+        # @example
+        #   options = Selenium::WebDriver::Chrome::Options.new(args: ['start-maximized', 'user-data-dir=/tmp/temp_profile'])
+        #   driver = Selenium::WebDriver.for(:chrome, options: options)
+        #
+        # @param [Hash] opts the pre-defined options to create the Chrome::Options with
+        # @option opts [Array<String>] :args List of command-line arguments to use when starting Chrome
+        # @option opts [String] :binary Path to the Chrome executable to use
+        # @option opts [Hash] :prefs A hash with each entry consisting of the name of the preference and its value
+        # @option opts [Array<String>] :extensions A list of paths to (.crx) Chrome extensions to install on startup
+        # @option opts [Hash] :options A hash for raw options
+        # @option opts [Hash] :emulation A hash for raw emulation options
+        #
+
+        def initialize(**opts)
+          @args = opts.delete(:args) || []
+          @binary = opts.delete(:binary) || Chrome.path
+          @prefs = opts.delete(:prefs) || {}
+          @extensions = opts.delete(:extensions) || []
+          @options = opts.delete(:options) || {}
+          @emulation = opts.delete(:emulation) || {}
+          @encoded_extensions = []
+        end
+
+        #
+        # Add an extension by local path.
+        #
+        # @example
+        #   options = Selenium::WebDriver::Chrome::Options.new
+        #   options.add_extension('/path/to/extension.crx')
+        #
+        # @param [String] path The local path to the .crx file
+        #
+
+        def add_extension(path)
+          raise Error::WebDriverError, "could not find extension at #{path.inspect}" unless File.file?(path)
+          raise Error::WebDriverError, "file was not an extension #{path.inspect}" unless File.extname(path) == '.crx'
+          @extensions << path
+        end
+
+        #
+        # Add an extension by Base64-encoded string.
+        #
+        # @example
+        #   options = Selenium::WebDriver::Chrome::Options.new
+        #   options.add_encoded_extension(encoded_string)
+        #
+        # @param [String] encoded The Base64-encoded string of the .crx file
+        #
+
+        def add_encoded_extension(encoded)
+          @encoded_extensions << encoded
+        end
+
+        #
+        # Add a command-line argument to use when starting Chrome
+        #
+        # @example Start Chrome maximized
+        #   options = Selenium::WebDriver::Chrome::Options.new
+        #   options.add_argument('start-maximized')
+        #
+        # @param [String] arg The command-line argument to add
+        #
+
+        def add_argument(arg)
+          @args << arg
+        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)
+          @options[name] = value
+        end
+
+        #
+        # Add a preference that is only applied to the user profile in use.
+        #
+        # @example Set the default homepage
+        #   options = Selenium::WebDriver::Chrome::Options.new
+        #   options.add_preference('homepage', 'http://www.seleniumhq.com/')
+        #
+        # @param [String] name Key of the preference
+        # @param [Boolean, String, Integer] value Value of the preference
+        #
+
+        def add_preference(name, value)
+          prefs[name] = value
+        end
+
+        #
+        # Add an emulation device name
+        #
+        # @example Start Chrome in mobile emulation mode by device name
+        #   options = Selenium::WebDriver::Chrome::Options.new
+        #   options.add_emulated_device(device_name: 'iPhone 6')
+        #
+        # @example Start Chrome in mobile emulation mode by device metrics
+        #   options = Selenium::WebDriver::Chrome::Options.new
+        #   options.add_emulated_device(device_metrics: {width: 400, height: 800, pixelRatio: 1, touch: true})
+        #
+        # @param [String] device_name Name of the device or a hash containing width, height, pixelRatio, touch
+        # @param [Hash] device_metrics Hash containing width, height, pixelRatio, touch
+        # @param [String] user_agent Full user agent
+        #
+
+        def add_emulation(device_name: nil, device_metrics: nil, user_agent: nil)
+          @emulation[:deviceName] = device_name if device_name
+          @emulation[:deviceMetrics] = device_metrics if device_metrics
+          @emulation[:userAgent] = user_agent if user_agent
+        end
+
+        #
+        # @api private
+        #
+
+        def as_json(*)
+          extensions = @extensions.map do |crx_path|
+            File.open(crx_path, 'rb') { |crx_file| Base64.strict_encode64 crx_file.read }
+          end
+          extensions.concat(@encoded_extensions)
+
+          opts = @options
+          opts[:binary] = @binary if @binary
+          opts[:args] = @args if @args.any?
+          opts[:extensions] = extensions if extensions.any?
+          opts[:mobileEmulation] = @emulation unless @emulation.empty?
+          opts[:prefs] = @prefs unless @prefs.empty?
+          opts
+        end
+      end # Profile
+    end # Chrome
+  end # WebDriver
+end # Selenium

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

@@ -41,40 +41,24 @@ module Selenium
         #
 
         def for(browser, opts = {})
-          listener = opts.delete(:listener)
-
-          bridge = case browser
-                   when :firefox, :ff
-                     if Remote::W3CCapabilities.w3c?(opts)
-                       if opts[:desired_capabilities].is_a? Remote::Capabilities
-                         opts[:desired_capabilities] = Remote::W3CCapabilities.new(opts[:desired_capabilities].send(:capabilities))
-                       end
-                       Firefox::W3CBridge.new(opts)
-                     else
-                       Firefox::Bridge.new(opts)
-                     end
-                   when :remote
-                     Remote::Bridge.new(opts)
-                   when :ie, :internet_explorer
-                     IE::Bridge.new(opts)
-                   when :chrome
-                     Chrome::Bridge.new(opts)
-                   when :edge
-                     if opts[:desired_capabilities]
-                       opts[:desired_capabilities] = Remote::W3CCapabilities.new(opts[:desired_capabilities].send(:capabilities))
-                     end
-                     Edge::Bridge.new(opts)
-                   when :phantomjs
-                     PhantomJS::Bridge.new(opts)
-                   when :safari
-                     Safari::Bridge.new(opts)
-                   else
-                     raise ArgumentError, "unknown driver: #{browser.inspect}"
-                   end
-
-          bridge = Support::EventFiringBridge.new(bridge, listener) if listener
-
-          new(bridge)
+          case browser
+          when :chrome
+            Chrome::Driver.new(opts)
+          when :internet_explorer, :ie
+            IE::Driver.new(opts)
+          when :safari
+            Safari::Driver.new(opts)
+          when :phantomjs
+            PhantomJS::Driver.new(opts)
+          when :firefox, :ff
+            Firefox::Driver.new(opts)
+          when :edge
+            Edge::Driver.new(opts)
+          when :remote
+            Remote::Driver.new(opts)
+          else
+            raise ArgumentError, "unknown driver: #{browser.inspect}"
+          end
         end
       end
 
@@ -85,12 +69,9 @@ module Selenium
       # @api private
       #
 
-      def initialize(bridge)
+      def initialize(bridge, listener: nil)
         @bridge = bridge
-
-        # TODO: refactor this away
-        return if bridge.driver_extensions.empty?
-        extend(*bridge.driver_extensions)
+        @bridge = Support::EventFiringBridge.new(bridge, listener) if listener
       end
 
       def inspect