Class: Appium::Core::Driver

Inherits:
Object
  • Object
show all
Includes:
Waitable
Defined in:
lib/appium_lib_core/driver.rb

Constant Summary collapse

DEFAULT_IMPLICIT_WAIT = 
0
DEFAULT_APPIUM_PORT = 
4723

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Methods included from Waitable

#wait, #wait_true

Constructor Details

#initialize(opts = {}) ⇒ Driver

Returns a new instance of Driver.



290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
 
# File 'lib/appium_lib_core/driver.rb', line 290

def initialize(opts = {})
  @delegate_target = self # for testing purpose
  @automation_name = nil # initialise before 'set_automation_name'

  opts = Appium.symbolize_keys opts
  validate_keys(opts)

  @custom_url = opts.delete :url
  @caps = get_caps(opts)

  set_appium_lib_specific_values(get_appium_lib_opts(opts))
  set_app_path
  set_appium_device
  set_automation_name

  extend_for(device: @device, automation_name: @automation_name)

  self # rubocop:disable Lint/Void
end

Instance Attribute Details

#automation_name ⇒ Hash (readonly)

Automation name sent to appium server or received by server.
If automation_name is nil, it is not set both client side and server side.

Returns:

  • (Hash) 


124
125
126
 
# File 'lib/appium_lib_core/driver.rb', line 124

def automation_name
  @automation_name
end

#caps ⇒ Core::Base::Capabilities (readonly)

Selenium webdriver capabilities

Returns:



104
105
106
 
# File 'lib/appium_lib_core/driver.rb', line 104

def caps
  @caps
end

#custom_url ⇒ String (readonly)

Custom URL for the selenium server. If set this attribute, ruby_lib_core try to handshake to the custom url.
Defaults to false. Then try to connect to http://127.0.0.1:#{port}/wd/hub.

Returns:

  • (String) 


129
130
131
 
# File 'lib/appium_lib_core/driver.rb', line 129

def custom_url
  @custom_url
end

#default_wait ⇒ Integer (readonly)

Default wait time for elements to appear in Appium server side. Defaults to DEFAULT_IMPLICIT_WAIT.
Provide { appium_lib: { wait: 30 } } to Appium::Core.for

Returns:

  • (Integer) 


141
142
143
 
# File 'lib/appium_lib_core/driver.rb', line 141

def default_wait
  @default_wait
end

#device ⇒ Symbol (readonly)

Device type to request from the appium server

Returns:

  • (Symbol) —

    :android and :ios, for example



119
120
121
 
# File 'lib/appium_lib_core/driver.rb', line 119

def device
  @device
end

#direct_connect ⇒ Bool (readonly)

[Experimental feature]
Enable an experimental feature updating Http client endpoint following below keys by Appium/Selenium server.
This works with Base::Http::Default.

If your Selenium/Appium server decorates the new session capabilities response with the following keys:

  • directConnectProtocol

  • directConnectHost

  • directConnectPort

  • directConnectPath

Ignore them if this parameter is false. Defaults to true.

Returns:

  • (Bool) 


183
184
185
 
# File 'lib/appium_lib_core/driver.rb', line 183

def direct_connect
  @direct_connect
end

#driver ⇒ Appium::Core::Base::Driver (readonly)

Returns:



168
169
170
 
# File 'lib/appium_lib_core/driver.rb', line 168

def driver
  @driver
end

#enable_idempotency_header ⇒ Bool (readonly)

Return if adding ‘x-idempotency-key’ header is enabled for each new session request. Following commands should not have the key. The key is unique for each http client instance. Defaults to true github.com/appium/appium-base-driver/pull/400

Returns:

  • (Bool) 


115
116
117
 
# File 'lib/appium_lib_core/driver.rb', line 115

def enable_idempotency_header
  @enable_idempotency_header
end

#export_session ⇒ Boolean (readonly)

Export session id to textfile in /tmp for 3rd party tools. False by default.

Returns:

  • (Boolean) 


133
134
135
 
# File 'lib/appium_lib_core/driver.rb', line 133

def export_session
  @export_session
end

#export_session_path ⇒ String (readonly)

Returns By default, session id is exported in ‘/tmp/appium_lib_session’.

Returns:

  • (String) —

    By default, session id is exported in ‘/tmp/appium_lib_session’



135
136
137
 
# File 'lib/appium_lib_core/driver.rb', line 135

def export_session_path
  @export_session_path
end

#http_client ⇒ Appium::Core::Base::Http::Default (readonly)

Return http client called in start_driver()

Returns:



108
109
110
 
# File 'lib/appium_lib_core/driver.rb', line 108

def http_client
  @http_client
end

#listener ⇒ Object (readonly)

instance of AbstractEventListener for logging support Nil by default



165
166
167
 
# File 'lib/appium_lib_core/driver.rb', line 165

def listener
  @listener
end

#port ⇒ Integer (readonly)

Appium’s server port. 4723 is by default. Defaults to DEFAULT_APPIUM_PORT.
Provide { appium_lib: { port: 8080 } } to Appium::Core.for. :custom_url is prior than :port if :custom_url is set.

Returns:

  • (Integer) 


148
149
150
 
# File 'lib/appium_lib_core/driver.rb', line 148

def port
  @port
end

#wait_interval ⇒ Integer (readonly)

Return a time to wait interval. 0.5 seconds is by default Wait::DEFAULT_INTERVAL.
Wait interval time for Base::Wait, wait and wait_true.
Provide { appium_lib: { wait_interval: 0.1 } } to Appium::Core.for.

Returns:

  • (Integer) 


161
162
163
 
# File 'lib/appium_lib_core/driver.rb', line 161

def wait_interval
  @wait_interval
end

#wait_timeout ⇒ Integer (readonly)

Return a time wait timeout. 30 seconds is by default Wait::DEFAULT_TIMEOUT.
Wait time for Base::Wait, wait and wait_true.
Provide { appium_lib: { wait_timeout: 20 } } to Appium::Core.for.

Returns:

  • (Integer) 


155
156
157
 
# File 'lib/appium_lib_core/driver.rb', line 155

def wait_timeout
  @wait_timeout
end

Class Method Details

.for(opts = {}) ⇒ Driver

Creates a new driver and extend particular methods

Examples:


# format 1
@core = Appium::Core.for caps: {...}, appium_lib: {...}
# format 2. 'capabilities:' or 'desired_capabilities:' is also available instead of 'caps:'.
@core = Appium::Core.for url: "http://127.0.0.1:8080/wd/hub", capabilities: {...}, appium_lib: {...}
# format 3. 'appium_lib: {...}' can be blank
@core = Appium::Core.for url: "http://127.0.0.1:8080/wd/hub", desired_capabilities: {...}

require 'rubygems'
require 'appium_lib_core'

# Start iOS driver
opts = {
         caps: {
           platformName: :ios,
           platformVersion: '11.0',
           deviceName: 'iPhone Simulator',
           automationName: 'XCUITest',
           app: '/path/to/MyiOS.app'
         },
         appium_lib: {
           export_session: false,
           port: 8080,
           wait: 0,
           wait_timeout: 20,
           wait_interval: 0.3,
           listener: nil,
         }
       }
@core = Appium::Core.for(opts) # create a core driver with 'opts' and extend methods into 'self'
@core.start_driver # Connect to 'http://127.0.0.1:8080/wd/hub' because of 'port: 8080'

# Start iOS driver with .zip file over HTTP
#  'desired_capabilities:' or 'capabilities:' is also available instead of 'caps:'. Either is fine.
opts = {
         capabilities: {
           platformName: :ios,
           platformVersion: '11.0',
           deviceName: 'iPhone Simulator',
           automationName: 'XCUITest',
           app: 'http://example.com/path/to/MyiOS.app.zip'
         },
         appium_lib: {
           server_url: 'http://custom-host:8080/wd/hub.com',
           export_session: false,
           wait: 0,
           wait_timeout: 20,
           wait_interval: 0.3,
           listener: nil,
         }
       }
@core = Appium::Core.for(opts)
@core.start_driver # Connect to 'http://custom-host:8080/wd/hub.com'

# Start iOS driver as another format. 'url' is available like below
opts = {
         url: "http://custom-host:8080/wd/hub.com",
         desired_capabilities: {
           platformName: :ios,
           platformVersion: '11.0',
           deviceName: 'iPhone Simulator',
           automationName: 'XCUITest',
           app: '/path/to/MyiOS.app'
         },
         appium_lib: {
           export_session: false,
           wait: 0,
           wait_timeout: 20,
           wait_interval: 0.3,
           listener: nil,
         }
       }
@core = Appium::Core.for(opts) # create a core driver with 'opts' and extend methods into 'self'
@core.start_driver # start driver with 'url'. Connect to 'http://custom-host:8080/wd/hub.com'

Parameters:

  • opts (Hash) (defaults to: {}) —

    A options include capabilities for the Appium Server and for the client.

Options Hash (opts):

  • :caps (Hash) —

    Appium capabilities.

  • :capabilities (Hash) —

    The same as :caps. This param is for compatibility with Selenium WebDriver format

  • :desired_capabilities (Hash) —

    The same as :caps. This param is for compatibility with Selenium WebDriver format

  • :appium_lib (Appium::Core::Options) —

    Capabilities affect only ruby client

  • :url (String) —

    The same as :custom_url in :appium_lib. This param is for compatibility with Selenium WebDriver format

Returns:



275
276
277
 
# File 'lib/appium_lib_core/driver.rb', line 275

def self.for(opts = {})
  new(opts)
end

Instance Method Details

#appium_server_version ⇒ Hash

Returns the server’s version info. This method calls driver.remote_status internally

Returns blank hash in a case driver.remote_status got an error such as Selenium Grid. It returns 500 error against ‘remote_status’.

Examples:


@core.appium_server_version
  {
      "build" => {
          "version" => "1.9.2",
          "git-sha" => "fd7c7fd19d3896719616cd970229d73e63b5271a",
          "built" => "2018-11-08 12:24:02 +0900"
      }
  }

@core.appium_server_version #=> {}

Returns:

  • (Hash) 


462
463
464
465
466
467
468
469
470
 
# File 'lib/appium_lib_core/driver.rb', line 462

def appium_server_version
  return {} if @driver.nil?

  @driver.remote_status
rescue StandardError
  # Ignore error case in a case the target appium server
  # does not support `/status` API.
  {}
end

#platform_version ⇒ Array<Integer>

Return the platform version as an array of integers

Examples:


@core.platform_version #=> [10,1,1]

Returns:

  • (Array<Integer>) 


479
480
481
482
 
# File 'lib/appium_lib_core/driver.rb', line 479

def platform_version
  p_version = @driver.capabilities['platformVersion'] || @driver.session_capabilities['platformVersion']
  p_version.split('.').map(&:to_i)
end

#quit_driver ⇒ void

This method returns an undefined value.

Quits the driver

Examples:


@core.quit_driver


434
435
436
437
438
 
# File 'lib/appium_lib_core/driver.rb', line 434

def quit_driver
  @driver.quit
rescue # rubocop:disable Style/RescueStandardError
  nil
end

#screenshot(png_save_path) ⇒ File

Takes a png screenshot and saves to the target path.

Examples:


@core.screenshot '/tmp/hi.png' #=> nil
# same as '@driver.save_screenshot png_save_path'

Parameters:

  • png_save_path (String) —

    the full path to save the png

Returns:

  • (File) 


494
495
496
497
 
# File 'lib/appium_lib_core/driver.rb', line 494

def screenshot(png_save_path)
  ::Appium::Logger.warn '[DEPRECATION] screenshot will be removed. Please use driver.save_screenshot instead.'
  @driver.save_screenshot png_save_path
end

#start_driver(server_url: nil, http_client_ops: { http_client: nil, open_timeout: 999_999, read_timeout: 999_999 }) ⇒ Selenium::WebDriver

Creates a new global driver and quits the old one if it exists. You can customise http_client as the following

Examples:


require 'rubygems'
require 'appium_lib_core'

# platformName takes a string or a symbol.

# Start iOS driver
opts = {
         caps: {
           platformName: :ios,
           platformVersion: '11.0',
           deviceName: 'iPhone Simulator',
           automationName: 'XCUITest',
           app: '/path/to/MyiOS.app'
         },
         appium_lib: {
           wait: 20,
           wait_timeout: 20,
           wait_interval: 0.3,
         }
       }

@core = Appium::Core.for(opts) # create a core driver with 'opts' and extend methods into 'self'
@driver = @core.start_driver server_url: "http://127.0.0.1:8000/wd/hub"

# Attach custom HTTP client
@driver = @core.start_driver server_url: "http://127.0.0.1:8000/wd/hub",
                             http_client_ops: { http_client: Your:Http:Client.new,
                                                open_timeout: 1_000,
                                                read_timeout: 1_000 }

Parameters:

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

    Custom server url to send to requests. Default is “127.0.0.1:4723/wd/hub”.

  • http_client_ops (Hash) (defaults to: { http_client: nil, open_timeout: 999_999, read_timeout: 999_999 }) —

    Options for http client

Options Hash (http_client_ops:):

  • :http_client (Hash) —

    Custom HTTP Client

  • :open_timeout (Hash) —

    Custom open timeout for http client.

  • :read_timeout (Hash) —

    Custom read timeout for http client.

Returns:

  • (Selenium::WebDriver) —

    the new global driver



353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
 
# File 'lib/appium_lib_core/driver.rb', line 353

def start_driver(server_url: nil,
                 http_client_ops: { http_client: nil, open_timeout: 999_999, read_timeout: 999_999 })
  @custom_url ||= server_url || "http://127.0.0.1:#{@port}/wd/hub"

  @http_client = get_http_client http_client: http_client_ops.delete(:http_client),
                                 open_timeout: http_client_ops.delete(:open_timeout),
                                 read_timeout: http_client_ops.delete(:read_timeout)

  if @enable_idempotency_header
    if @http_client.instance_variable_defined? :@additional_headers
      @http_client.additional_headers[Appium::Core::Base::Http::RequestHeaders::KEYS[:idempotency]] = SecureRandom.uuid
    else
      ::Appium::Logger.warn 'No additional_headers attribute in this http client instance'
    end
  end

  begin
    # included https://github.com/SeleniumHQ/selenium/blob/43f8b3f66e7e01124eff6a5805269ee441f65707/rb/lib/selenium/webdriver/remote/driver.rb#L29
    @driver = ::Appium::Core::Base::Driver.new(http_client: @http_client,
                                               desired_capabilities: @caps,
                                               url: @custom_url,
                                               listener: @listener)

    if @direct_connect
      d_c = DirectConnections.new(@driver.capabilities)
      @driver.update_sending_request_to(protocol: d_c.protocol, host: d_c.host, port: d_c.port, path: d_c.path)
    end

    # export session
    write_session_id(@driver.session_id, @export_session_path) if @export_session
  rescue Errno::ECONNREFUSED
    raise "ERROR: Unable to connect to Appium. Is the server running on #{@custom_url}?"
  end

  if @http_client.instance_variable_defined? :@additional_headers
    # We only need the key for a new session request. Should remove it for other following commands.
    @http_client.additional_headers.delete Appium::Core::Base::Http::RequestHeaders::KEYS[:idempotency]
  end

  # If "automationName" is set only server side, this method set "automationName" attribute into @automation_name.
  # Since @automation_name is set only client side before start_driver is called.
  set_automation_name_if_nil

  set_implicit_wait_by_default(@default_wait)

  @driver
end