class Selenium::WebDriver::Chrome::Options

Constants

BROWSER
CAPABILITIES

see: chromedriver.chromium.org/capabilities

KEY

Attributes

extensions[R]

NOTE: special handling of ‘extensions’ to validate when set instead of when used

logging_prefs[RW]
profile[RW]

Public Class Methods

new(profile: nil, **opts) click to toggle source

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 [Array] :encoded_extensions List of extensions that do not need to be Base64 encoded @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 @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

Calls superclass method Selenium::WebDriver::Options::new
# File lib/selenium/webdriver/chrome/options.rb, line 73
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(&method(:validate_extension))
end

Public Instance Methods

add_argument(arg) click to toggle source

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

# File lib/selenium/webdriver/chrome/options.rb, line 146
def add_argument(arg)
  @options[:args] << arg
end
add_emulation(**opts) click to toggle source

Add emulation device information

see: 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

# File lib/selenium/webdriver/chrome/options.rb, line 196
def add_emulation(**opts)
  @options[:emulation] = opts
end
add_encoded_extension(encoded) click to toggle source

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

# File lib/selenium/webdriver/chrome/options.rb, line 132
def add_encoded_extension(encoded)
  @encoded_extensions << encoded
end
add_extension(path) click to toggle source

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

# File lib/selenium/webdriver/chrome/options.rb, line 103
def add_extension(path)
  validate_extension(path)
end
add_preference(name, value) click to toggle source

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

# File lib/selenium/webdriver/chrome/options.rb, line 161
def add_preference(name, value)
  @options[:prefs][name] = value
end
enable_android(package: 'com.android.chrome', serial_number: nil, use_running_app: nil, activity: nil) click to toggle source

Enables mobile browser use on Android.

@see 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).

# File lib/selenium/webdriver/chrome/options.rb, line 212
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
extensions=(extensions) click to toggle source

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

# File lib/selenium/webdriver/chrome/options.rb, line 118
def extensions=(extensions)
  extensions.each(&method(:validate_extension))
end
headless!() click to toggle source

Run Chrome in headless mode.

@example Enable headless mode

options = Selenium::WebDriver::Chrome::Options.new
options.headless!
# File lib/selenium/webdriver/chrome/options.rb, line 173
def headless!
  add_argument '--headless'
end

Private Instance Methods

binary_path() click to toggle source
# File lib/selenium/webdriver/chrome/options.rb, line 240
def binary_path
  Chrome.path
end
camelize?(key) click to toggle source
# File lib/selenium/webdriver/chrome/options.rb, line 255
def camelize?(key)
  !%w[localState prefs].include?(key)
end
enable_logging(browser_options) click to toggle source
# File lib/selenium/webdriver/chrome/options.rb, line 221
def enable_logging(browser_options)
  browser_options['goog:loggingPrefs'] = @logging_prefs
end
encode_extension(path) click to toggle source
# File lib/selenium/webdriver/chrome/options.rb, line 244
def encode_extension(path)
  File.open(path, 'rb') { |crx_file| Base64.strict_encode64 crx_file.read }
end
process_browser_options(browser_options) click to toggle source
# File lib/selenium/webdriver/chrome/options.rb, line 225
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(&method(:encode_extension))
end
validate_extension(path) click to toggle source
# File lib/selenium/webdriver/chrome/options.rb, line 248
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