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

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

Constant Summary collapse

KEY = 
'goog:chromeOptions'.freeze

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(**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, options: options)

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

Parameters:

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



43
44
45
46
47
48
49
50
51
 
# File 'lib/selenium/webdriver/chrome/options.rb', line 43

def initialize(**opts)
  @args = Set.new(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

Instance Attribute Details

#args ⇒ Object (readonly)

Returns the value of attribute args.



22
23
24
 
# File 'lib/selenium/webdriver/chrome/options.rb', line 22

def args
  @args
end

#binary ⇒ Object

Returns the value of attribute binary.



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

def binary
  @binary
end

#emulation ⇒ Object (readonly)

Returns the value of attribute emulation.



22
23
24
 
# File 'lib/selenium/webdriver/chrome/options.rb', line 22

def emulation
  @emulation
end

#encoded_extensions ⇒ Object (readonly)

Returns the value of attribute encoded_extensions.



22
23
24
 
# File 'lib/selenium/webdriver/chrome/options.rb', line 22

def encoded_extensions
  @encoded_extensions
end

#extensions ⇒ Object (readonly)

Returns the value of attribute extensions.



22
23
24
 
# File 'lib/selenium/webdriver/chrome/options.rb', line 22

def extensions
  @extensions
end

#options ⇒ Object (readonly)

Returns the value of attribute options.



22
23
24
 
# File 'lib/selenium/webdriver/chrome/options.rb', line 22

def options
  @options
end

#prefs ⇒ Object (readonly)

Returns the value of attribute prefs.



22
23
24
 
# File 'lib/selenium/webdriver/chrome/options.rb', line 22

def prefs
  @prefs
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:

  • The command-line argument to add



93
94
95
 
# File 'lib/selenium/webdriver/chrome/options.rb', line 93

def add_argument(arg)
  @args << arg
end

#add_emulation(device_name: nil, device_metrics: nil, user_agent: nil) ⇒ Object

Add an emulation device name

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:

  • (defaults to: nil)

    Name of the device or a hash containing width, height, pixelRatio, touch

  • (defaults to: nil)

    Hash containing width, height, pixelRatio, touch

  • (defaults to: nil)

    Full user agent



158
159
160
161
162
 
# File 'lib/selenium/webdriver/chrome/options.rb', line 158

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

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

  • The Base64-encoded string of the .crx file



79
80
81
 
# File 'lib/selenium/webdriver/chrome/options.rb', line 79

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

Raises:

Parameters:

  • The local path to the .crx file



63
64
65
66
67
 
# File 'lib/selenium/webdriver/chrome/options.rb', line 63

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_option(name, value) ⇒ Object

Add a new option not yet handled by bindings.

Examples:

Leave Chrome open when chromedriver is killed

options = Selenium::WebDriver::Chrome::Options.new
options.add_option(:detach, true)

Parameters:

  • Name of the option

  • Value of the option



108
109
110
 
# File 'lib/selenium/webdriver/chrome/options.rb', line 108

def add_option(name, value)
  @options[name] = value
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:

  • Key of the preference

  • Value of the preference



123
124
125
 
# File 'lib/selenium/webdriver/chrome/options.rb', line 123

def add_preference(name, value)
  prefs[name] = value
end

#as_json ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

API:

  • private



168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
 
# File 'lib/selenium/webdriver/chrome/options.rb', line 168

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.to_a if @args.any?
  opts[:extensions] = extensions if extensions.any?
  opts[:mobileEmulation] = @emulation unless @emulation.empty?
  opts[:prefs] = @prefs unless @prefs.empty?

  {KEY => opts}
end

#headless! ⇒ Object

Run Chrome in headless mode.

Examples:

Enable headless mode

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



135
136
137
138
139
140
 
# File 'lib/selenium/webdriver/chrome/options.rb', line 135

def headless!
  add_argument '--headless'

  # https://bugs.chromium.org/p/chromium/issues/detail?id=737678#c1
  add_argument '--disable-gpu' if WebDriver::Platform.windows?
end