Class: Selenium::WebDriver::Chrome::Options

Inherits:
Options
  • Object
show all
Defined in:
lib/selenium/webdriver/chrome/options.rb

Direct Known Subclasses

Edge::Options

Constant Summary collapse

KEY =
'goog:chromeOptions'
BROWSER =
'chrome'
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

Constants inherited from Options

Options::W3C_OPTIONS

Instance Attribute Summary collapse

Attributes inherited from Options

#options

Instance Method Summary collapse

Methods inherited from Options

#==, #add_option, #as_json, chrome, edge, firefox, ie, safari, set_capabilities

Constructor Details

#initialize(profile: nil, **opts) ⇒ Options

Create a new Options instance.

Examples:

options = Selenium::WebDriver::Chrome::Options.new(args: ['start-maximized', 'user-data-dir=/tmp/temp_profile'])
driver = Selenium::WebDriver.for(:chrome, capabilities: options)

Parameters:

  • :profile (Profile)

    An instance of a Chrome::Profile Class

  • :encoded_extensions (Array)

    List of extensions that do not need to be Base64 encoded

  • opts (Hash)

    the pre-defined options to create the Chrome::Options with

Options Hash (**opts):

  • :args (Array<String>)

    List of command-line arguments to use when starting Chrome

  • :binary (String)

    Path to the Chrome executable to use

  • :prefs (Hash)

    A hash with each entry consisting of the name of the preference and its value

  • :extensions (Array<String>)

    A list of paths to (.crx) Chrome extensions to install on startup

  • :options (Hash)

    A hash for raw options

  • :emulation (Hash)

    A hash for raw emulation options

  • :local_state (Hash)

    A hash for the Local State file in the user data folder

  • :detach (Boolean)

    whether browser is closed when the driver is sent the quit command

  • :debugger_address (String)

    address of a Chrome debugger server to connect to

  • :exclude_switches (Array<String>)

    command line switches to exclude

  • :minidump_path (String)

    Directory to store Chrome minidumps (linux only)

  • :perf_logging_prefs (Hash)

    A hash for performance logging preferences

  • :window_types (Array<String>)

    A list of window types to appear in the list of window handles


73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
# 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

Instance Attribute Details

#extensionsObject

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


47
48
49
# File 'lib/selenium/webdriver/chrome/options.rb', line 47

def extensions
  @extensions
end

#logging_prefsObject

Returns the value of attribute logging_prefs.


24
25
26
# File 'lib/selenium/webdriver/chrome/options.rb', line 24

def logging_prefs
  @logging_prefs
end

#profileObject

Returns the value of attribute profile.


24
25
26
# File 'lib/selenium/webdriver/chrome/options.rb', line 24

def profile
  @profile
end

Instance Method Details

#add_argument(arg) ⇒ Object

Add a command-line argument to use when starting Chrome.

Examples:

Start Chrome maximized

options = Selenium::WebDriver::Chrome::Options.new
options.add_argument('start-maximized')

Parameters:

  • arg (String)

    The command-line argument to add


146
147
148
# File 'lib/selenium/webdriver/chrome/options.rb', line 146

def add_argument(arg)
  @options[:args] << arg
end

#add_emulation(**opts) ⇒ Object

Add emulation device information

see: chromedriver.chromium.org/mobile-emulation

Examples:

Start Chrome in mobile emulation mode by device name

options = Selenium::WebDriver::Chrome::Options.new
options.add_emulation(device_name: 'iPhone 6')

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})

Parameters:

  • opts (Hash)

    the pre-defined options for adding mobile emulation values

Options Hash (**opts):

  • :device_name (String)

    A valid device name from the Chrome DevTools Emulation panel

  • :device_metrics (Hash)

    Hash containing width, height, pixelRatio, touch

  • :user_agent (String)

    Full user agent


196
197
198
# File 'lib/selenium/webdriver/chrome/options.rb', line 196

def add_emulation(**opts)
  @options[:emulation] = opts
end

#add_encoded_extension(encoded) ⇒ Object

Add an extension by Base64-encoded string.

Examples:

options = Selenium::WebDriver::Chrome::Options.new
options.add_encoded_extension(encoded_string)

Parameters:

  • encoded (String)

    The Base64-encoded string of the .crx file


132
133
134
# File 'lib/selenium/webdriver/chrome/options.rb', line 132

def add_encoded_extension(encoded)
  @encoded_extensions << encoded
end

#add_extension(path) ⇒ Object

Add an extension by local path.

Examples:

options = Selenium::WebDriver::Chrome::Options.new
options.add_extension('/path/to/extension.crx')

Parameters:

  • path (String)

    The local path to the .crx file


103
104
105
# File 'lib/selenium/webdriver/chrome/options.rb', line 103

def add_extension(path)
  validate_extension(path)
end

#add_preference(name, value) ⇒ Object

Add a preference that is only applied to the user profile in use.

Examples:

Set the default homepage

options = Selenium::WebDriver::Chrome::Options.new
options.add_preference('homepage', 'http://www.seleniumhq.com/')

Parameters:

  • name (String)

    Key of the preference

  • value (Boolean, String, Integer)

    Value of the preference


161
162
163
# 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) ⇒ Object

Enables mobile browser use on Android.

Parameters:

  • package (String) (defaults to: 'com.android.chrome')

    The package name of the Chrome or WebView app.

  • serial_number (String) (defaults to: nil)

    The device serial number on which to launch the Chrome or WebView app.

  • use_running_app (String) (defaults to: nil)

    When true uses an already-running Chrome or WebView app, instead of launching the app with a clear data directory.

  • activity (String) (defaults to: nil)

    Name of the Activity hosting the WebView (Not available on Chrome Apps).

See Also:


212
213
214
215
216
217
# 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

#headless!Object

Run Chrome in headless mode.

Examples:

Enable headless mode

options = Selenium::WebDriver::Chrome::Options.new
options.headless!

173
174
175
# File 'lib/selenium/webdriver/chrome/options.rb', line 173

def headless!
  add_argument '--headless'
end