Class: Appium::Driver

Inherits:
Object
  • Object
show all
Extended by:
Forwardable
Defined in:
lib/appium_lib/driver.rb

Constant Summary collapse

CORE_BRIDGE_METHODS =

Methods forwarded to the underlying Appium::Core::Base::Driver instance (exposed via ‘#driver`). Previously these were wired up implicitly by `extend ::Appium::Core::Device` through a static compatibility list in `ruby_lib_core` (see appium/ruby_lib_core#97). Defining them here lets `ruby_lib_core` eventually drop that list.

%i[
  take_element_screenshot save_viewport_screenshot
  lock device_locked? unlock
  hide_keyboard is_keyboard_shown
  ime_activate ime_available_engines ime_active_engine ime_activated ime_deactivate
  get_settings update_settings
  within_context current_context available_contexts set_context
  push_file pull_file pull_folder
  keyevent press_keycode long_press_keycode
  match_images_features find_image_occurrence get_images_similarity compare_images
  app_strings background_app
  install_app remove_app app_installed? activate_app terminate_app
  app_state
  stop_recording_screen stop_and_save_recording_screen
  shake device_time
  execute_cdp
].freeze

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(opts = {}, global_driver = false) ⇒ Driver

Creates a new driver. The driver is defined as global scope by default. We can avoid defining global driver.

Examples:


require 'rubygems'
require 'appium_lib'

# platformName takes a string or a symbol.
# Start iOS driver with global scope
opts = {
         caps: {
           platformName: :ios,
           app: '/path/to/MyiOS.app'
         },
         appium_lib: {
           server_url: 'http://127.0.0.1:4723'
           wait_timeout: 30
         }
       }
appium_driver = Appium::Driver.new(opts, true)
appium_driver.start_driver

# Start Android driver with global scope
opts = {
         caps: {
           platformName: :android,
           app: '/path/to/my.apk'
         },
         appium_lib: {
           wait_timeout: 30,
           wait_interval: 1
         }
       }
appium_driver = Appium::Driver.new(opts, true)
appium_driver.start_driver

# Start iOS driver without global scope
opts = {
         caps: {
           platformName: :ios,
           app: '/path/to/MyiOS.app'
         },
         appium_lib: {
           wait_timeout: 30
         }
       }
appium_driver = Appium::Driver.new(opts, false)
appium_driver.start_driver

# Start iOS driver without global scope
opts = {
         caps: {
           platformName: :ios,
           app: '/path/to/MyiOS.app'
         },
         appium_lib: {
           wait_timeout: 30
         },
         global_driver: false
       }
appium_driver = Appium::Driver.new(opts)
appium_driver.start_driver

Parameters:

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

    A hash containing various options.

  • global_driver (Bool) (defaults to: false) —

    A bool require global driver before initialize.

Raises:



200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
 
# File 'lib/appium_lib/driver.rb', line 200

def initialize(opts = {}, global_driver = false)
  # Capybara can't put `global_driver` as the 2nd argument.
  global_driver = opts.delete :global_driver if global_driver.nil?

  $driver&.driver_quit if global_driver

  raise ArgumentError, 'opts must be a hash' unless opts.is_a? Hash

  @core = ::Appium::Core.for(opts)
  extend ::Appium::Core::Device

  opts = Appium.symbolize_keys opts
  appium_lib_opts = opts[:appium_lib] || {}

  @caps = @core.caps
  @custom_url = @core.custom_url
  @default_wait = @core.default_wait || 0
  @appium_port = @core.port
  @appium_wait_timeout = @core.wait_timeout
  @appium_wait_interval = @core.wait_interval
  @listener = @core.listener
  @appium_device = @core.device
  @automation_name = @core.automation_name

  # Arrange the app capability. This must be after @core = ::Appium::Core.for(opts)
  set_app_path(opts)

  # enable debug patch
  @appium_debug = appium_lib_opts.fetch :debug, !!defined?(Pry) # rubocop:disable Style/DoubleNegation
  set_sauce_related_values(appium_lib_opts)

  # Extend Common methods
  extend Appium::Common
  extend Appium::Device

  # Extend each driver's methods
  extend_for(device: @core.device, automation_name: @core.automation_name)

  # for command

  if @appium_debug
    Appium::Logger.debug opts unless opts.empty?
    Appium::Logger.debug "Debug is: #{@appium_debug}"
    Appium::Logger.debug "Device is: #{@core.device}"
  end

  # Save global reference to last created Appium driver for top level methods.
  $driver = self if global_driver

  self # rubocop:disable Lint/Void # return newly created driver
end

Instance Attribute Details

#appium_debug ⇒ Object (readonly)

Boolean debug mode for the Appium Ruby bindings



126
127
128
 
# File 'lib/appium_lib/driver.rb', line 126

def appium_debug
  @appium_debug
end

#appium_device ⇒ Object (readonly)

Returns the value of attribute appium_device.



116
117
118
 
# File 'lib/appium_lib/driver.rb', line 116

def appium_device
  @appium_device
end

#appium_port ⇒ Object (readonly)

Returns the value of attribute appium_port.



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

def appium_port
  @appium_port
end

#appium_server_status ⇒ Object (readonly)

Appium’s server version



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

def appium_server_status
  @appium_server_status
end

#appium_wait_interval ⇒ Object (readonly)

Returns the value of attribute appium_wait_interval.



121
122
123
 
# File 'lib/appium_lib/driver.rb', line 121

def appium_wait_interval
  @appium_wait_interval
end

#appium_wait_timeout ⇒ Object (readonly)

Returns the value of attribute appium_wait_timeout.



120
121
122
 
# File 'lib/appium_lib/driver.rb', line 120

def appium_wait_timeout
  @appium_wait_timeout
end

#automation_name ⇒ Object (readonly)

Returns the value of attribute automation_name.



117
118
119
 
# File 'lib/appium_lib/driver.rb', line 117

def automation_name
  @automation_name
end

#caps ⇒ Object (readonly)

from Core read www.rubydoc.info/github/appium/ruby_lib_core/Appium/Core/Driver



112
113
114
 
# File 'lib/appium_lib/driver.rb', line 112

def caps
  @caps
end

#core ⇒ Object (readonly)

Instance of Appium::Core::Driver



131
132
133
 
# File 'lib/appium_lib/driver.rb', line 131

def core
  @core
end

#custom_url ⇒ Object (readonly)

Returns the value of attribute custom_url.



113
114
115
 
# File 'lib/appium_lib/driver.rb', line 113

def custom_url
  @custom_url
end

#default_wait ⇒ Object (readonly)

Returns the value of attribute default_wait.



114
115
116
 
# File 'lib/appium_lib/driver.rb', line 114

def default_wait
  @default_wait
end

#driver ⇒ Driver (readonly)

Returns the driver

Returns:



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

def driver
  @driver
end

#global_webdriver_http_sleep ⇒ Object

The amount to sleep in seconds before every webdriver http call.



96
97
98
 
# File 'lib/appium_lib/driver.rb', line 96

def global_webdriver_http_sleep
  @global_webdriver_http_sleep
end

#http_client ⇒ Object (readonly)

Returns the value of attribute http_client.



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

def http_client
  @http_client
end

#listener ⇒ Object (readonly)

Returns the value of attribute listener.



118
119
120
 
# File 'lib/appium_lib/driver.rb', line 118

def listener
  @listener
end

#sauce ⇒ Object (readonly)

SauceLab’s settings



99
100
101
 
# File 'lib/appium_lib/driver.rb', line 99

def sauce
  @sauce
end

#sauce_access_key ⇒ Object (readonly)

Access Key for use on Sauce Labs. Set ‘false` to disable Sauce, even when SAUCE_ACCESS_KEY is in ENV. same as @sauce.access_key



105
106
107
 
# File 'lib/appium_lib/driver.rb', line 105

def sauce_access_key
  @sauce_access_key
end

#sauce_endpoint ⇒ Object (readonly)

Override the Sauce Appium endpoint to allow e.g. TestObject tests same as @sauce.endpoint



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

def sauce_endpoint
  @sauce_endpoint
end

#sauce_username ⇒ Object (readonly)

Username for use on Sauce Labs. Set ‘false` to disable Sauce, even when SAUCE_USERNAME is in ENV. same as @sauce.username



102
103
104
 
# File 'lib/appium_lib/driver.rb', line 102

def sauce_username
  @sauce_username
end

Class Method Details

.absolute_app_path(opts) ⇒ String

Deprecated

Converts app_path to an absolute path.

opts is the full options hash (caps and appium_lib). If server_url is set then the app path is used as is.

if app isn’t set then an error is raised.

Returns:

  • (String) —

    APP_PATH as an absolute path

Raises:



429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
 
# File 'lib/appium_lib/driver.rb', line 429

def self.absolute_app_path(opts)
  raise ArgumentError, 'opts must be a hash' unless opts.is_a? Hash

  caps = opts[:caps] || opts['caps'] || {}
  app_path = get_cap(caps, 'app')
  raise ArgumentError, 'absolute_app_path invoked and app is not set!' if app_path.nil? || app_path.empty?
  # Sauce storage API. http://saucelabs.com/docs/rest#storage
  return app_path if app_path.start_with? 'sauce-storage:'
  return app_path if app_path =~ URI::DEFAULT_PARSER.make_regexp # public URL for Sauce

  ::Appium::Logger.warn('[Deprecation] Converting the path to absolute path will be removed. ' \
                        'Please specify the full path which can be accessible from the appium server')

  absolute_app_path = File.expand_path app_path
  if File.exist? absolute_app_path
    absolute_app_path
  else
    ::Appium::Logger.info("Use #{app_path}")
    app_path
  end
end

.convert_to_symbol(value) ⇒ Object 



72
73
74
75
76
77
78
 
# File 'lib/appium_lib/driver.rb', line 72

def convert_to_symbol(value)
  if value.nil?
    value
  else
    value.to_sym
  end
end

.get_cap(caps, name) ⇒ Object 



81
82
83
84
85
86
87
 
# File 'lib/appium_lib/driver.rb', line 81

def get_cap(caps, name)
  name_with_prefix = "#{::Appium::Core::Base::Bridge::APPIUM_PREFIX}#{name}"
  caps[convert_to_symbol name] ||
    caps[name] ||
    caps[convert_to_symbol name_with_prefix] ||
    caps[name_with_prefix]
end

Instance Method Details

#action ⇒ Selenium::WebDriver::PointerActions

An entry point to chain W3C actions Read www.rubydoc.info/github/appium/ruby_lib_core/Appium/Core/Base/Bridge/W3C#action-instance_method

Examples:


element = find_element(:id, "some id")
action.click(element).perform # The `click` is a part of `PointerActions`

Returns:

  • (Selenium::WebDriver::PointerActions) 


374
375
376
 
# File 'lib/appium_lib/driver.rb', line 374

def action
  @driver&.action
end

#appium_client_version ⇒ Hash

Returns the client’s version info

Examples:


{
    "version" => "9.1.1"
}

Returns:

  • (Hash) 


417
418
419
 
# File 'lib/appium_lib/driver.rb', line 417

def appium_client_version
  { version: ::Appium::VERSION }
end

#appium_server_version ⇒ Hash Also known as: remote_status

Returns the server’s version info

Examples:

{
  "build" => {
      "version" => "0.18.1",
      "revision" => "d242ebcfd92046a974347ccc3a28f0e898595198"
  }
}

Returns:

  • (Hash) 


389
390
391
392
393
394
395
396
 
# File 'lib/appium_lib/driver.rb', line 389

def appium_server_version
  @core.appium_server_version
rescue Selenium::WebDriver::Error::WebDriverError => ex
  raise ::Appium::Core::Error::ServerError unless ex.message.include?('content-type=""')

  # server (TestObject for instance) does not respond to status call
  {}
end

#automation_name_is_espresso? ⇒ Boolean

Return true if automationName is ‘Espresso’

Returns:

  • (Boolean) 


354
355
356
 
# File 'lib/appium_lib/driver.rb', line 354

def automation_name_is_espresso?
  !@core.automation_name.nil? && @core.automation_name == :espresso
end

#automation_name_is_uiautomator2? ⇒ Boolean

Return true if automationName is ‘uiautomator2’

Returns:

  • (Boolean) 


348
349
350
 
# File 'lib/appium_lib/driver.rb', line 348

def automation_name_is_uiautomator2?
  !@core.automation_name.nil? && @core.automation_name == :uiautomator2
end

#automation_name_is_xcuitest? ⇒ Boolean

Return true if automationName is ‘XCUITest’

Returns:

  • (Boolean) 


360
361
362
 
# File 'lib/appium_lib/driver.rb', line 360

def automation_name_is_xcuitest?
  !@core.automation_name.nil? && @core.automation_name == :xcuitest
end

#current_url ⇒ Object

Raises:



748
749
750
751
752
 
# File 'lib/appium_lib/driver.rb', line 748

def current_url
  raise NoDriverInstanceError if @driver.nil?

  @driver.current_url
end

#device_is_android? ⇒ Boolean

Returns:

  • (Boolean) 


334
335
336
 
# File 'lib/appium_lib/driver.rb', line 334

def device_is_android?
  @core.device == :android
end

#device_is_ios? ⇒ Boolean

Returns:

  • (Boolean) 


338
339
340
 
# File 'lib/appium_lib/driver.rb', line 338

def device_is_ios?
  @core.device == :ios
end

#device_is_windows? ⇒ Boolean

Returns:

  • (Boolean) 


342
343
344
 
# File 'lib/appium_lib/driver.rb', line 342

def device_is_windows?
  @core.device == :windows
end

#driver_attributes ⇒ Object

Returns a hash of the driver attributes



316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
 
# File 'lib/appium_lib/driver.rb', line 316

def driver_attributes
  {
    caps:                @core.caps,
    automation_name:     @core.automation_name,
    custom_url:          @core.custom_url,
    default_wait:        @default_wait,
    sauce_username:      @sauce.username,
    sauce_access_key:    @sauce.access_key,
    sauce_endpoint:      @sauce.endpoint,
    port:                @core.port,
    device:              @core.device,
    debug:               @appium_debug,
    listener:            @listener,
    wait_timeout:        @core.wait_timeout,
    wait_interval:       @core.wait_interval
  }
end

#driver_quit ⇒ void Also known as: quit_driver

This method returns an undefined value.

Quits the driver



496
497
498
499
500
501
 
# File 'lib/appium_lib/driver.rb', line 496

def driver_quit
  @driver&.quit
  @driver = nil
rescue Selenium::WebDriver::Error::WebDriverError
  nil
end

#element_screenshot(element, png_save_path) ⇒ File

Takes a png screenshot of particular element’s area

Examples:


el = find_element :accessibility_id, zzz
element_screenshot el, '/tmp/hi.png'

Parameters:

  • element (String) —

    Element take a screenshot

  • png_save_path (String) —

    the full path to save the png

Returns:

  • (File) 


489
490
491
492
 
# File 'lib/appium_lib/driver.rb', line 489

def element_screenshot(element, png_save_path)
  @driver&.take_element_screenshot element, png_save_path
  nil
end

#execute_async_script(script, *args) ⇒ Object

Wrap calling selenium webdrier APIs via ruby_core

Get the window handles of open browser windows

Raises:



677
678
679
680
681
 
# File 'lib/appium_lib/driver.rb', line 677

def execute_async_script(script, *args)
  raise NoDriverInstanceError if @driver.nil?

  @driver.execute_async_script script, *args
end

#execute_driver(script: '', type: 'webdriverio', timeout_ms: nil) ⇒ Appium::Core::Base::Device::ExecuteDriver::Result

Run a set of script against the current session, allowing execution of many commands in one Appium request. Supports WebdriverIO API so far. Please read command API for more details about acceptable scripts and the output.

Examples:

script = <<~SCRIPT
  const status = await driver.status();
  console.warn('warning message');
  return [status];
SCRIPT
r = @@driver.execute_driver(script: script, type: 'webdriverio', timeout: 10_000)
r        #=> An instance of Appium::Core::Base::Device::ExecuteDriver::Result
r.result #=> The `result` key part as the result of the script
r.logs   #=> The `logs` key part as `{'log' => [], 'warn' => [], 'error' => []}`

Parameters:

  • script (String) (defaults to: '') —

    The string consisting of the script itself

  • type (String) (defaults to: 'webdriverio') —

    The name of the script type. Defaults to ‘webdriverio’. Depends on server implementation which type is supported.

  • timeout_ms (Integer) (defaults to: nil) —

    The number of ‘ms` Appium should wait for the script to finish before killing it due to timeout.

Returns:

  • (Appium::Core::Base::Device::ExecuteDriver::Result) —

    The script result parsed by Appium::Core::Base::Device::ExecuteDriver::Result.

Raises:

  • (::Selenium::WebDriver::Error::UnknownError) —

    If something error happens in the script. It has the original message.



711
712
713
714
715
 
# File 'lib/appium_lib/driver.rb', line 711

def execute_driver(script: '', type: 'webdriverio', timeout_ms: nil)
  raise NoDriverInstanceError if @driver.nil?

  @driver.execute_driver(script: script, type: type, timeout_ms: timeout_ms)
end

#execute_script(script, *args) ⇒ Object

The same as @driver.execute_script

Parameters:

  • script (String) —

    The script to execute

  • args (*args) —

    The args to pass to the script

Returns:

  • (Object)

Raises:



667
668
669
670
671
 
# File 'lib/appium_lib/driver.rb', line 667

def execute_script(script, *args)
  raise NoDriverInstanceError if @driver.nil?

  @driver.execute_script script, *args
end

#exists(pre_check = 0, post_check = @default_wait) { ... } ⇒ Boolean

Returns existence of element.

Example:

exists { button(‘sign in’) } ? puts(‘true’) : puts(‘false’)

Parameters:

  • pre_check (Integer) (defaults to: 0) —

    The amount in seconds to set the wait to before checking existence

  • post_check (Integer) (defaults to: @default_wait) —

    The amount in seconds to set the wait to after checking existence

Yields:

  • The block to call

Returns:

  • (Boolean) 


643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
 
# File 'lib/appium_lib/driver.rb', line 643

def exists(pre_check = 0, post_check = @default_wait)
  # do not uset set_wait here.
  # it will cause problems with other methods reading the default_wait of 0
  # which then gets converted to a 1 second wait.
  @driver&.manage&.timeouts&.implicit_wait = pre_check
  # the element exists unless an error is raised.
  exists = true

  begin
    yield # search for element
  rescue StandardError
    exists = false # error means it's not there
  end

  # restore wait
  @driver&.manage&.timeouts&.implicit_wait = post_check if post_check != pre_check

  exists
end

#find_element(*args) ⇒ Element

Calls @driver.find_element

If you call ‘Appium.promote_appium_methods`, you can call `find_element` directly.

Examples:


@driver = Appium::Driver.new(opts, false)
@driver.start_driver
@driver.find_element :accessibility_id, zzz

Parameters:

  • args (*args) —

    The args to use

Returns:

  • (Element)

Raises:



809
810
811
812
813
 
# File 'lib/appium_lib/driver.rb', line 809

def find_element(*args)
  raise NoDriverInstanceError if @driver.nil?

  @driver.find_element(*args)
end

#find_element_by_image(png_img_path) ⇒ ::Appium::Core::ImageElement

Return ImageElement if current view has a partial image

Examples:


@driver.find_element_by_image './test/functional/data/test_element_image.png'

Parameters:

  • png_img_path (String) —

    A path to a partial image you’d like to find

Returns:

  • (::Appium::Core::ImageElement)

Raises:

  • (::Appium::Core::Error::NoSuchElementError|::Appium::Core::Error::CoreError) —

    No such element



826
827
828
829
830
 
# File 'lib/appium_lib/driver.rb', line 826

def find_element_by_image(png_img_path)
  raise NoDriverInstanceError if @driver.nil?

  @driver.find_element_by_image(png_img_path)
end

#find_elements(*args) ⇒ Array<Element>

Calls @driver.find_elements_with_appium

If you call ‘Appium.promote_appium_methods`, you can call `find_elements` directly.

If you call ‘Appium.promote_appium_methods`, you can call `find_elements` directly.

Examples:


@driver = Appium::Driver.new(opts, false)
@driver.start_driver
@driver.find_elements :predicate, yyy

@driver = Appium::Driver.new(opts, false)
@driver.start_driver
@driver.find_elements :predicate, yyy

Parameters:

  • args (*args) —

    The args to use

Returns:

  • (Array<Element>) —

    Array is empty when no elements are found.

Raises:



791
792
793
794
795
 
# File 'lib/appium_lib/driver.rb', line 791

def find_elements(*args)
  raise NoDriverInstanceError if @driver.nil?

  @driver.find_elements(*args)
end

#find_elements_by_image(png_img_paths) ⇒ [::Appium::Core::ImageElement], ::Appium::Core::Error::CoreError

Return ImageElement if current view has partial images

Examples:


@driver.find_elements_by_image ['./test/functional/data/test_element_image.png']

Parameters:

  • png_img_paths ([String]) —

    Paths to a partial image you’d like to find

Returns:

  • ([::Appium::Core::ImageElement])
  • (::Appium::Core::Error::CoreError)

Raises:



843
844
845
846
847
 
# File 'lib/appium_lib/driver.rb', line 843

def find_elements_by_image(png_img_paths)
  raise NoDriverInstanceError if @driver.nil?

  @driver.find_elements_by_image(png_img_paths)
end

#get(url) ⇒ Object

Raises:



742
743
744
745
746
 
# File 'lib/appium_lib/driver.rb', line 742

def get(url)
  raise NoDriverInstanceError if @driver.nil?

  @driver.get(url)
end

#log_event(vendor:, event:) ⇒ nil

Logs a custom event. The event is available via Core::Events#get.

Examples:


log_event vendor: 'appium', event: 'funEvent'

log_event = { vendor: 'appium', event: 'anotherEvent' }
log_events #=> {...., 'appium:funEvent' => [1572957315, 1572960305],
           #          'appium:anotherEvent' => 1572959315}

Parameters:

  • vendor (String) —

    The vendor prefix for the event

  • event (String) —

    The name of event

Returns:

  • (nil)

Raises:

Since:

  • Appium 1.16.0



883
884
885
886
887
 
# File 'lib/appium_lib/driver.rb', line 883

def log_event(vendor:, event:)
  raise NoDriverInstanceError if @driver.nil?

  @driver.logs.event vendor: vendor, event: event
end

#log_event=(log_event) ⇒ Object 



889
890
891
892
893
894
895
896
 
# File 'lib/appium_lib/driver.rb', line 889

def log_event=(log_event)
  raise if @driver.nil?
  unless log_event.is_a?(Hash)
    raise ::Appium::Core::Error::ArgumentError('log_event should be Hash like { vendor: "appium", event: "funEvent"}')
  end

  @driver.logs.event vendor: log_event[:vendor], event: log_event[:event]
end

#log_events(type = nil) ⇒ Hash

Returns events with filtering with ‘type’. Defaults to all available events.

Examples:


log_events #=> {}
log_events #=> {'commands' => [{'cmd' => 123455, ....}], 'startTime' => 1572954894127, }

Parameters:

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

    The type of events to get

Returns:

  • (Hash)

Raises:

Since:

  • Appium 1.16.0



909
910
911
912
913
 
# File 'lib/appium_lib/driver.rb', line 909

def log_events(type = nil)
  raise NoDriverInstanceError if @driver.nil?

  @driver.logs.events(type)
end

#manage ⇒ Object

Raises:



736
737
738
739
740
 
# File 'lib/appium_lib/driver.rb', line 736

def manage
  raise NoDriverInstanceError if @driver.nil?

  @driver.manage
end

#navigate ⇒ Object

Raises:



730
731
732
733
734
 
# File 'lib/appium_lib/driver.rb', line 730

def navigate
  raise NoDriverInstanceError if @driver.nil?

  @driver.navigate
end

#no_wait ⇒ Object

Set implicit wait to zero.



612
613
614
 
# File 'lib/appium_lib/driver.rb', line 612

def no_wait
  @driver&.manage&.timeouts&.implicit_wait = 0
end

#platform_version ⇒ Array<Integer>

Return the platform version as an array of integers

Returns:

  • (Array<Integer>) 


401
402
403
404
405
406
 
# File 'lib/appium_lib/driver.rb', line 401

def platform_version
  return [] if @driver.nil?

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

#restart ⇒ Driver

Restarts the driver

Returns:



462
463
464
465
 
# File 'lib/appium_lib/driver.rb', line 462

def restart
  driver_quit
  start_driver
end

#screenshot(png_save_path) ⇒ File

Takes a png screenshot and saves to the target path.

Examples:


screenshot '/tmp/hi.png'

Parameters:

  • png_save_path (String) —

    the full path to save the png

Returns:

  • (File) 


475
476
477
 
# File 'lib/appium_lib/driver.rb', line 475

def screenshot(png_save_path)
  @driver&.save_screenshot png_save_path
end

#server_url ⇒ String

Get the server url

Returns:

  • (String) —

    the server url



453
454
455
456
457
458
 
# File 'lib/appium_lib/driver.rb', line 453

def server_url
  return @core.custom_url if @core.custom_url
  return @sauce.server_url if @sauce.sauce_server_url?

  "http://127.0.0.1:#{@core.port}"
end

#set_implicit_wait(wait) ⇒ Object

To ignore error for Espresso Driver



601
602
603
604
605
606
607
608
609
 
# File 'lib/appium_lib/driver.rb', line 601

def set_implicit_wait(wait)
  @driver.manage.timeouts.implicit_wait = wait
rescue Selenium::WebDriver::Error::UnknownError => e
  unless e.message.include?('The operation requested is not yet implemented by Espresso driver')
    raise ::Appium::Core::Error::ServerError
  end

  {}
end

#set_location(opts = {}) ⇒ Selenium::WebDriver::Location

Note:

This method does not work on real devices.

Calls @driver.set_location

Parameters:

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

    consisting of:

Options Hash (opts):

  • :latitude (Float) —

    the latitude in degrees (required)

  • :longitude (Float) —

    the longitude in degees (required)

  • :altitude (Float) —

    the altitude, defaulting to 75

Returns:

  • (Selenium::WebDriver::Location) —

    the location constructed by the selenium webdriver

Raises:



858
859
860
861
862
863
864
865
 
# File 'lib/appium_lib/driver.rb', line 858

def set_location(opts = {})
  raise NoDriverInstanceError if @driver.nil?

  latitude = opts.fetch(:latitude)
  longitude = opts.fetch(:longitude)
  altitude = opts.fetch(:altitude, 75)
  @driver.set_location(latitude, longitude, altitude)
end

#set_wait(timeout = nil) ⇒ void

This method returns an undefined value.

Set implicit wait. Default to @default_wait.

Examples:


set_wait 2
set_wait # @default_wait

Parameters:

  • timeout (Integer) (defaults to: nil) —

    the timeout in seconds



626
627
628
629
 
# File 'lib/appium_lib/driver.rb', line 626

def set_wait(timeout = nil)
  timeout = @default_wait if timeout.nil?
  @driver&.manage&.timeouts&.implicit_wait = timeout
end

#start_driver(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

Read www.rubydoc.info/github/appium/ruby_lib_core/Appium/Core/Device to understand more what the driver can call instance methods.

Examples:


require 'rubygems'
require 'appium_lib'

# platformName takes a string or a symbol.
# Start iOS driver
opts = {
         caps: {
           platformName: :ios,
           app: '/path/to/MyiOS.app'
         },
         appium_lib: {
           wait_timeout: 30
         }
       }
appium_driver = Appium::Driver.new(opts) #=> return an Appium::Driver instance
appium_driver.start_driver #=> return an Appium::Core::Base::Driver

Parameters:

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

    a customizable set of options

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



566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
 
# File 'lib/appium_lib/driver.rb', line 566

def start_driver(http_client_ops = { http_client: nil, open_timeout: 999_999, read_timeout: 999_999 })
  if http_client_ops[:http_client].nil?
    http_client = ::Appium::Http::Default.new(open_timeout: http_client_ops[:open_timeout],
                                              read_timeout: http_client_ops[:read_timeout])
  end

  # TODO: do not kill the previous session in the future version.
  if $driver.nil?
    driver_quit
  else
    $driver.driver_quit
  end

  # If automationName is set only in server side, then the following automation_name should be nil before
  # starting driver.
  automation_name = @core.automation_name

  @driver = @core.start_driver(server_url: server_url,
                               http_client_ops: {
                                 http_client: http_client,
                                 open_timeout: 999_999,
                                 read_timeout: 999_999
                               })
  @http_client = @core.http_client

  # if automation_name was nil before start_driver, then re-extend driver specific methods
  # to be able to extend correctly.
  extend_for(device: @core.device, automation_name: @core.automation_name) if automation_name.nil?

  @appium_server_status = appium_server_version

  @driver
end

#switch_to ⇒ TargetLocator

Returns:

  • (TargetLocator)

Raises:

See Also:

  • TargetLocator


762
763
764
765
766
 
# File 'lib/appium_lib/driver.rb', line 762

def switch_to
  raise NoDriverInstanceError if @driver.nil?

  @driver.switch_to
end

#title ⇒ Object

Raises:



754
755
756
757
758
 
# File 'lib/appium_lib/driver.rb', line 754

def title
  raise NoDriverInstanceError if @driver.nil?

  @driver.title
end

#window_handle ⇒ Object

Get the current window handle

Raises:



724
725
726
727
728
 
# File 'lib/appium_lib/driver.rb', line 724

def window_handle
  raise NoDriverInstanceError if @driver.nil?

  @driver.window_handle
end

#window_handles ⇒ Object

Raises:



717
718
719
720
721
 
# File 'lib/appium_lib/driver.rb', line 717

def window_handles
  raise NoDriverInstanceError if @driver.nil?

  @driver.window_handles
end

#window_rect ⇒ Selenium::WebDriver::Rectangle

Get the device window’s rect.

Examples:


size = @driver.window_size
size.width #=> Integer
size.height #=> Integer
size.x #=> Integer
size.y #=> Integer

Returns:

  • (Selenium::WebDriver::Rectangle)

Raises:



531
532
533
534
535
 
# File 'lib/appium_lib/driver.rb', line 531

def window_rect
  raise NoDriverInstanceError if @driver.nil?

  @driver.window_rect
end

#window_size ⇒ Selenium::WebDriver::Dimension

Get the device window’s size.

Examples:


size = @driver.window_size
size.width #=> Integer
size.height #=> Integer

Returns:

  • (Selenium::WebDriver::Dimension)

Raises:



513
514
515
516
517
518
 
# File 'lib/appium_lib/driver.rb', line 513

def window_size
  # maybe exception is expected as no driver created
  raise NoDriverInstanceError if @driver.nil?

  @driver.window_size
end

#x ⇒ void

This method returns an undefined value.

Quit the driver and Pry. quit and exit are reserved by Pry.



918
919
920
921
 
# File 'lib/appium_lib/driver.rb', line 918

def x
  driver_quit
  exit # exit pry
end