selenium-webdriver 4.1.0 → 4.9.0

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

@@ -0,0 +1,261 @@
+# 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
+    module Chromium
+      class Options < WebDriver::Options
+        attr_accessor :profile, :logging_prefs
+
+        # see: http://chromedriver.chromium.org/capabilities
+        CAPABILITIES = {args: 'args',
+                        binary: 'binary',
+                        local_state: 'localState',
+                        prefs: 'prefs',
+                        detach: 'detach',
+                        debugger_address: 'debuggerAddress',
+                        exclude_switches: 'excludeSwitches',
+                        minidump_path: 'minidumpPath',
+                        emulation: 'mobileEmulation',
+                        perf_logging_prefs: 'perfLoggingPrefs',
+                        window_types: 'windowTypes',
+                        android_package: 'androidPackage',
+                        android_activity: 'androidActivity',
+                        android_device_serial: 'androidDeviceSerial',
+                        android_use_running_app: 'androidUseRunningApp'}.freeze
+
+        # NOTE: special handling of 'extensions' to validate when set instead of when used
+        attr_reader :extensions
+
+        # 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, capabilities: options)
+        #
+        # @param [Profile] profile An instance of a Chrome::Profile Class
+        # @param [Hash] opts the pre-defined options to create the Chrome::Options with
+        # @option opts [Array] encoded_extensions List of extensions that do not need to be Base64 encoded
+        # @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
+        # @option opts [Hash] local_state A hash for the Local State file in the user data folder
+        # @option opts [Boolean] detach whether browser is closed when the driver is sent the quit command
+        # @option opts [String] debugger_address address of a Chrome debugger server to connect to
+        # @option opts [Array<String>] exclude_switches command line switches to exclude
+        # @option opts [String] minidump_path Directory to store Chrome minidumps (linux only)
+        # @option opts [Hash] perf_logging_prefs A hash for performance logging preferences
+        # @option opts [Array<String>] window_types A list of window types to appear in the list of window handles
+        #
+
+        def initialize(profile: nil, **opts)
+          super(**opts)
+
+          @profile = profile
+
+          @options = {args: [],
+                      prefs: {},
+                      emulation: {},
+                      extensions: [],
+                      local_state: {},
+                      exclude_switches: [],
+                      perf_logging_prefs: {},
+                      window_types: []}.merge(@options)
+
+          @logging_prefs = options.delete(:logging_prefs) || {}
+          @encoded_extensions = @options.delete(:encoded_extensions) || []
+          @extensions = []
+          @options.delete(:extensions).each { |ext| validate_extension(ext) }
+        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)
+          validate_extension(path)
+        end
+
+        #
+        # Add an extension by local path.
+        #
+        # @example
+        #   extensions = ['/path/to/extension.crx', '/path/to/other.crx']
+        #   options = Selenium::WebDriver::Chrome::Options.new
+        #   options.extensions = extensions
+        #
+        # @param [Array<String>] extensions A list of paths to (.crx) Chrome extensions to install on startup
+        #
+
+        def extensions=(extensions)
+          extensions.each { |ext| validate_extension(ext) }
+        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)
+          @options[:args] << arg
+        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)
+          @options[:prefs][name] = value
+        end
+
+        #
+        # Run Chrome in headless mode.
+        # Old headless uses a non-production browser and is set with `--headless`
+        # Native headless from v86 - v108 is set with `--headless=chrome`
+        # Native headless from v109+ is set with `--headless=new`
+        #
+        # @example Enable headless mode
+        #   options = Selenium::WebDriver::Chrome::Options.new
+        #   options.headless!
+        #
+
+        def headless!
+          WebDriver.logger.deprecate('`Options#headless!`',
+                                     "`Options#add_argument('--headless=new')`",
+                                     id: :headless)
+          add_argument '--headless'
+        end
+
+        #
+        # Add emulation device information
+        #
+        # see: http://chromedriver.chromium.org/mobile-emulation
+        #
+        # @example Start Chrome in mobile emulation mode by device name
+        #   options = Selenium::WebDriver::Chrome::Options.new
+        #   options.add_emulation(device_name: 'iPhone 6')
+        #
+        # @example Start Chrome in mobile emulation mode by device metrics
+        #   options = Selenium::WebDriver::Chrome::Options.new
+        #   options.add_emulation(device_metrics: {width: 400, height: 800, pixelRatio: 1, touch: true})
+        #
+        # @param [Hash] opts the pre-defined options for adding mobile emulation values
+        # @option opts [String] :device_name A valid device name from the Chrome DevTools Emulation panel
+        # @option opts [Hash] :device_metrics Hash containing width, height, pixelRatio, touch
+        # @option opts [String] :user_agent Full user agent
+        #
+
+        def add_emulation(**opts)
+          @options[:emulation] = opts
+        end
+
+        #
+        # Enables mobile browser use on Android.
+        #
+        # @see https://chromedriver.chromium.org/getting-started/getting-started---android
+        #
+        # @param [String] package The package name of the Chrome or WebView app.
+        # @param [String] serial_number The device serial number on which to launch the Chrome or WebView app.
+        # @param [String] use_running_app When true uses an already-running Chrome or WebView app,
+        #   instead of launching the app with a clear data directory.
+        # @param [String] activity Name of the Activity hosting the WebView (Not available on Chrome Apps).
+        #
+
+        def enable_android(package: 'com.android.chrome', serial_number: nil, use_running_app: nil, activity: nil)
+          @options[:android_package] = package
+          @options[:android_activity] = activity unless activity.nil?
+          @options[:android_device_serial] = serial_number unless serial_number.nil?
+          @options[:android_use_running_app] = use_running_app unless use_running_app.nil?
+        end
+
+        protected
+
+        def process_browser_options(browser_options)
+          enable_logging(browser_options) unless @logging_prefs.empty?
+
+          options = browser_options[self.class::KEY]
+          options['binary'] ||= binary_path if binary_path
+
+          if @profile
+            options['args'] ||= []
+            options['args'] << "--user-data-dir=#{@profile.directory}"
+          end
+
+          return if (@encoded_extensions + @extensions).empty?
+
+          options['extensions'] = @encoded_extensions + @extensions.map { |ext| encode_extension(ext) }
+        end
+
+        def binary_path
+          Chrome.path
+        end
+
+        def encode_extension(path)
+          File.open(path, 'rb') { |crx_file| Base64.strict_encode64 crx_file.read }
+        end
+
+        def validate_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
+
+        def camelize?(key)
+          !%w[localState prefs].include?(key)
+        end
+      end # Options
+    end # Chromium
+  end # WebDriver
+end # Selenium

data/lib/selenium/webdriver/chromium/profile.rb

@@ -0,0 +1,113 @@
+# 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
+    module Chromium
+      #
+      # @private
+      #
+
+      class Profile
+        include ProfileHelper
+
+        def initialize(model = nil)
+          @model = verify_model(model)
+          @extensions = []
+          @encoded_extensions = []
+          @directory = nil
+        end
+
+        def add_extension(path)
+          raise Error::WebDriverError, "could not find extension at #{path.inspect}" unless File.file?(path)
+
+          @extensions << path
+        end
+
+        def add_encoded_extension(encoded)
+          @encoded_extensions << encoded
+        end
+
+        def directory
+          @directory || layout_on_disk
+        end
+
+        #
+        # Set a preference in the profile.
+        #
+        # See https://src.chromium.org/viewvc/chrome/trunk/src/chrome/common/pref_names.cc
+        #
+
+        def []=(key, value)
+          parts = key.split('.')
+          parts[0..-2].inject(prefs) { |a, e| a[e] ||= {} }[parts.last] = value
+        end
+
+        def [](key)
+          parts = key.split('.')
+          parts.inject(prefs) { |a, e| a.fetch(e) }
+        end
+
+        def layout_on_disk
+          @directory = @model ? create_tmp_copy(@model) : Dir.mktmpdir('webdriver-chrome-profile')
+          FileReaper << @directory
+
+          write_prefs_to @directory
+
+          @directory
+        end
+
+        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 = {'directory' => directory || layout_on_disk}
+          opts['extensions'] = extensions if extensions.any?
+          opts
+        end
+
+        private
+
+        def write_prefs_to(dir)
+          prefs_file = prefs_file_for(dir)
+
+          FileUtils.mkdir_p File.dirname(prefs_file)
+          File.open(prefs_file, 'w') { |file| file << JSON.generate(prefs) }
+        end
+
+        def prefs
+          @prefs ||= read_model_prefs
+        end
+
+        def read_model_prefs
+          return {} unless @model
+
+          JSON.parse File.read(prefs_file_for(@model))
+        end
+
+        def prefs_file_for(dir)
+          File.join dir, 'Default', 'Preferences'
+        end
+      end # Profile
+    end # Chromium
+  end # WebDriver
+end # Selenium

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

@@ -0,0 +1,42 @@
+# 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
+    module Chromium
+      class Service < WebDriver::Service
+        protected
+
+        def extract_service_args(driver_opts)
+          driver_args = super
+          driver_opts = driver_opts.dup
+          driver_args << "--log-path=#{driver_opts.delete(:log_path)}" if driver_opts.key?(:log_path)
+          driver_args << "--url-base=#{driver_opts.delete(:url_base)}" if driver_opts.key?(:url_base)
+          driver_args << "--port-server=#{driver_opts.delete(:port_server)}" if driver_opts.key?(:port_server)
+          if driver_opts.key?(:whitelisted_ips)
+            driver_args << "--whitelisted-ips=#{driver_opts.delete(:whitelisted_ips)}"
+          end
+          driver_args << '--verbose' if driver_opts.key?(:verbose)
+          driver_args << '--silent' if driver_opts.key?(:silent)
+          driver_args
+        end
+      end # Service
+    end # Chromium
+  end # WebDriver
+end # Selenium

data/lib/selenium/webdriver/chromium.rb

@@ -0,0 +1,32 @@
+# 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.
+
+require 'net/http'
+
+module Selenium
+  module WebDriver
+    module Chromium
+      autoload :Features, 'selenium/webdriver/chromium/features'
+      autoload :Driver, 'selenium/webdriver/chromium/driver'
+      autoload :Profile, 'selenium/webdriver/chromium/profile'
+      autoload :Options, 'selenium/webdriver/chromium/options'
+      autoload :Service, 'selenium/webdriver/chromium/service'
+    end # Chromium
+  end # WebDriver
+end # Selenium

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

@@ -22,6 +22,7 @@ module Selenium
     class ActionBuilder
       include KeyActions # Actions specific to key inputs
       include PointerActions # Actions specific to pointer inputs
+      include WheelActions # Actions specific to wheel inputs
 
       attr_reader :devices
 
@@ -31,19 +32,23 @@ module Selenium
       # the mouse is moving. Keep in mind that pauses must be added for other devices in order to line up the actions
       # correctly when using asynchronous.
       #
-      # @param [Selenium::WebDriver::Remote::Bridge] bridge the bridge for the current driver instance
-      # @param [Selenium::WebDriver::Interactions::PointerInput] mouse PointerInput for the mouse.
-      # @param [Selenium::WebDriver::Interactions::KeyInput] keyboard KeyInput for the keyboard.
-      # @param [Boolean] async Whether to perform the actions asynchronously per device. Defaults to false for
-      #   backwards compatibility.
+      # @param [Selenium::WebDriver::Remote::Bridge] bridge the bridge for the current driver instance.
+      # @param [Selenium::WebDriver::Interactions::PointerInput] deprecated_mouse PointerInput for the mouse.
+      # @param [Selenium::WebDriver::Interactions::KeyInput] deprecated_keyboard KeyInput for the keyboard.
+      # @param [Boolean] deprecated_async Whether to perform the actions asynchronously per device.
+      #   Defaults to false for backwards compatibility.
+      # @param [Array<Selenium::WebDriver::Interactions::InputDevices>] devices list of valid sources of input.
+      # @param [Boolean] async Whether to perform the actions asynchronously per device.
       # @return [ActionBuilder] A self reference.
       #
 
-      def initialize(bridge, mouse, keyboard, async = false)
-        # For backwards compatibility, automatically include mouse & keyboard
+      def initialize(bridge, devices: [], async: false, duration: 250)
         @bridge = bridge
-        @devices = [mouse, keyboard]
+        @duration = duration
         @async = async
+        @devices = []
+
+        Array(devices).each { |device| add_input(device) }
       end
 
       #
@@ -61,9 +66,7 @@ module Selenium
       #
 
       def add_pointer_input(kind, name)
-        new_input = Interactions.pointer(kind, name: name)
-        add_input(new_input)
-        new_input
+        add_input(Interactions.pointer(kind, name: name))
       end
 
       #
@@ -79,20 +82,39 @@ module Selenium
       #
 
       def add_key_input(name)
-        new_input = Interactions.key(name)
-        add_input(new_input)
-        new_input
+        add_input(Interactions.key(name))
       end
 
       #
-      # Retrieves the input device for the given name
+      # Adds a WheelInput device
+      #
+      # @example Add a wheel input device
+      #
+      #    builder = device.action
+      #    builder.add_wheel_input('wheel2')
+      #
+      # @param [String] name name for the device
+      # @return [Interactions::WheelInput] The wheel input added
+      #
+
+      def add_wheel_input(name)
+        add_input(Interactions.wheel(name))
+      end
+
+      #
+      # Retrieves the input device for the given name or type
       #
       # @param [String] name name of the input device
-      # @return [Selenium::WebDriver::Interactions::InputDevice] input device with given name
+      # @param [String] type name of the input device
+      # @return [Selenium::WebDriver::Interactions::InputDevice] input device with given name or type
       #
 
-      def get_device(name)
-        @devices.find { |device| device.name == name.to_s }
+      def device(name: nil, type: nil)
+        input = @devices.find { |device| (device.name == name.to_s || name.nil?) && (device.type == type || type.nil?) }
+
+        raise(ArgumentError, "Can not find device: #{name}") if name && input.nil?
+
+        input
       end
 
       #
@@ -115,6 +137,16 @@ module Selenium
         @devices.select { |device| device.type == Interactions::KEY }
       end
 
+      #
+      # Retrieves the current WheelInput device
+      #
+      # @return [Selenium::WebDriver::Interactions::InputDevice] current WheelInput devices
+      #
+
+      def wheel_inputs
+        @devices.select { |device| device.type == Interactions::WHEEL }
+      end
+
       #
       # Creates a pause for the given device of the given duration. If no duration is given, the pause will only wait
       # for all actions to complete in that tick.
@@ -131,7 +163,8 @@ module Selenium
       # @return [ActionBuilder] A self reference.
       #
 
-      def pause(device, duration = nil)
+      def pause(device: nil, duration: 0)
+        device ||= pointer_input
         device.create_pause(duration)
         self
       end
@@ -152,7 +185,11 @@ module Selenium
       # @return [ActionBuilder] A self reference.
       #
 
-      def pauses(device, number, duration = nil)
+      def pauses(device: nil, number: nil, duration: 0)
+        number ||= 2
+        device ||= pointer_input
+        duration ||= 0
+
         number.times { device.create_pause(duration) }
         self
       end
@@ -162,7 +199,7 @@ module Selenium
       #
 
       def perform
-        @bridge.send_actions @devices.map(&:encode).compact
+        @bridge.send_actions @devices.filter_map(&:encode)
         clear_all_actions
         nil
       end
@@ -202,11 +239,24 @@ module Selenium
       #
 
       def add_input(device)
+        device = Interactions.send(device) if device.is_a?(Symbol) && Interactions.respond_to?(device)
+
+        raise TypeError, "#{device.inspect} is not a valid InputDevice" unless device.is_a?(Interactions::InputDevice)
+
         unless @async
           max_device = @devices.max { |a, b| a.actions.length <=> b.actions.length }
-          pauses(device, max_device.actions.length)
+          pauses(device: device, number: max_device.actions.length) if max_device
         end
         @devices << device
+        device
+      end
+
+      def deprecate_method(device = nil, duration = nil, number = nil, method: :pause)
+        return unless device || number || duration
+
+        WebDriver.logger.deprecate "ActionBuilder##{method} with ordered parameters",
+                                   ':device, :duration, :number keywords',
+                                   id: method
       end
     end # ActionBuilder
   end # WebDriver