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

Inherits:
Selenium::WebDriver::Common::Options show all
Defined in:
lib/selenium/webdriver/chrome/options.rb

Constant Summary collapse

KEY = 
'goog:chromeOptions'

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)

Parameters:

  • 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


45
46
47
48
49
50
51
52
53
54
55
 
# File 'lib/selenium/webdriver/chrome/options.rb', line 45

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) || {}
  @detach = opts.delete(:detach)
  @profile = opts.delete(:profile)
  @encoded_extensions = []
end

Instance Attribute Details

#args ⇒ Object (readonly)

Returns the value of attribute args


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

def args
  @args
end

#binary ⇒ Object

Returns the value of attribute binary


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

def binary
  @binary
end

#detach ⇒ Object

Returns the value of attribute detach


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

def detach
  @detach
end

#emulation ⇒ Object (readonly)

Returns the value of attribute emulation


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

def emulation
  @emulation
end

#encoded_extensions ⇒ Object (readonly)

Returns the value of attribute encoded_extensions


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

def encoded_extensions
  @encoded_extensions
end

#extensions ⇒ Object (readonly)

Returns the value of attribute extensions


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

def extensions
  @extensions
end

#options ⇒ Object (readonly)

Returns the value of attribute options


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

def options
  @options
end

#prefs ⇒ Object (readonly)

Returns the value of attribute prefs


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

def prefs
  @prefs
end

#profile ⇒ Object

Returns the value of attribute profile


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

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


98
99
100
 
# File 'lib/selenium/webdriver/chrome/options.rb', line 98

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:

  • device_name (String) (defaults to: nil) —

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

  • device_metrics (Hash) (defaults to: nil) —

    Hash containing width, height, pixelRatio, touch

  • user_agent (String) (defaults to: nil) —

    Full user agent


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

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:

  • encoded (String) —

    The Base64-encoded string of the .crx file


84
85
86
 
# File 'lib/selenium/webdriver/chrome/options.rb', line 84

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

Raises:


67
68
69
70
71
72
 
# File 'lib/selenium/webdriver/chrome/options.rb', line 67

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 (String, Symbol) —

    Name of the option

  • value (Boolean, String, Integer) —

    Value of the option


113
114
115
 
# File 'lib/selenium/webdriver/chrome/options.rb', line 113

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:

  • name (String) —

    Key of the preference

  • value (Boolean, String, Integer) —

    Value of the preference


128
129
130
 
# File 'lib/selenium/webdriver/chrome/options.rb', line 128

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. 


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

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)
  add_argument("--user-data-dir=#{@profile[:directory]}") if @profile

  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?
  opts[:detach] = @detach if !@detach.nil? && @detach != false

  {KEY => generate_as_json(opts)}
end

#headless! ⇒ Object

Run Chrome in headless mode.

Examples:

Enable headless mode

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

140
141
142
 
# File 'lib/selenium/webdriver/chrome/options.rb', line 140

def headless!
  add_argument '--headless'
end