Class: Appium::Core::Base::Driver

Inherits:
Selenium::WebDriver::Driver
  • Object
show all
Includes:
HasLocation, HasNetworkConnection, HasRemoteStatus, Rotatable, SearchContext, TakesScreenshot, Waitable, Selenium::WebDriver::DriverExtensions::HasSessionId, Selenium::WebDriver::DriverExtensions::HasWebStorage, Selenium::WebDriver::DriverExtensions::UploadsFiles
Defined in:
lib/appium_lib_core/common/base/driver.rb

Constant Summary collapse

AVAILABLE_METHODS = 
[
  :get, :head, :post, :put, :delete,
  :connect, :options, :trace, :patch
].freeze

Constants included from SearchContext

SearchContext::FINDERS

Constants included from Rotatable

Rotatable::ORIENTATIONS

Instance Attribute Summary collapse

Instance Method Summary collapse

Methods included from Waitable

#wait_until, #wait_until_true

Methods included from HasNetworkConnection

#network_connection_type, #network_connection_type=

Methods included from HasLocation

#location, #location=, #set_location

Methods included from HasRemoteStatus

#remote_status

Methods included from TakesScreenshot

#element_screenshot_as, #save_element_screenshot, #save_screenshot, #save_viewport_screenshot, #screenshot_as

Methods included from SearchContext

#find_element, #find_elements

Methods included from Rotatable

#orientation, #rotation=

Constructor Details

#initialize(bridge: nil, listener: nil, **opts) ⇒ Driver

override



48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
 
# File 'lib/appium_lib_core/common/base/driver.rb', line 48

def initialize(bridge: nil, listener: nil, **opts) # rubocop:disable Lint/MissingSuper
  original_opts = opts.dup

  # For ::Appium::Core::Waitable
  @wait_timeout = opts.delete(:wait_timeout)
  @wait_interval = opts.delete(:wait_interval)

  # Selenium WebDriver attributes
  @devtools = nil
  @bidi = nil

  # in the selenium webdriver as well
  bridge ||= create_bridge(**opts)
  add_extensions(bridge.browser)
  @bridge = listener ? ::Appium::Support::EventFiringBridge.new(bridge, listener, **original_opts) : bridge
end

Instance Attribute Details

#bridge ⇒ Object (readonly)

Private API. Do not use this for general use. Used by flutter driver to get bridge for creating a new element



45
46
47
 
# File 'lib/appium_lib_core/common/base/driver.rb', line 45

def bridge
  @bridge
end

Instance Method Details

#activate_app(app_id) ⇒ Hash

Activate(Launch) the specified app.

Examples:


@driver.activate_app("io.appium.bundle") #=> {}

Returns:

  • (Hash) 


743
744
745
746
 
# File 'lib/appium_lib_core/common/base/driver.rb', line 743

def activate_app(app_id)
  # TODO: use mobile command in the background?
  @bridge.activate_app(app_id)
end

#add_command(method:, url:, name:, &block) ⇒ Object

Define a new custom method to the driver so that you can define your own method for drivers/plugins in Appium 2.0. Appium 2.0 and its custom drivers/plugins allow you to define custom commands that are not part of W3C spec.

Examples:


@driver.add_command(
  method: :get,
  url: 'session/:session_id/path/to/custom/url',
  name: :test_command
)
# Send a GET request to 'session/<session id>/path/to/custom/url'
@driver.test_command

@driver.add_command(
  method: :post,
  url: 'session/:session_id/path/to/custom/url',
  name: :test_command
) do
  def test_command(argument)
    execute(:test_command, {}, { dummy: argument })
  end
end
# Send a POST request to 'session/<session id>/path/to/custom/url'
# with body "{ dummy: 1 }" as JSON object. "1" is the argument.
# ':session_id' in the given 'url' is replaced with current 'session id'.
@driver.test_command(1)

@driver.add_command(
  method: :post,
  url: 'session/:session_id/element/:id/custom/action',
  name: :test_action_command
) do
  def test_action_command(element_id, action)
    execute(:test_action_command, {id: element_id}, { dummy_action: action })
  end
end
# Send a POST request to 'session/<session id>/element/<element id>/custom/action'
# with body "{ dummy_action: #{action} }" as JSON object. "action" is the seconds argument.
# ':session_id' in the given url is replaced with current 'session id'.
# ':id' in the given url is replaced with the given 'element_id'.
e = @driver.find_element :accessibility_id, 'an element'
@driver.test_action_command(e.id, 'action')

Parameters:

  • method (Symbol) —

    HTTP request method as www.w3.org/TR/webdriver/#endpoints

  • url (string) —

    The url to URL template as www.w3.org/TR/webdriver/#endpoints. :session_id is the placeholder of ‘session id’. Other place holders can be specified with : prefix like :id. Then, the :id will be replaced with a given value as the seconds argument of execute

  • name (Symbol) —

    The name of method that is called as the driver instance method.

  • block (Proc) —

    The block to involve as the method. Please define a method that has the same name with arguments you want. The method must has execute method. tHe execute is calls the url with the given parameters. The first argument should be name as symbol. The second argument should be hash. If keys in the hash matches : prefix string in the given url, the matched string in the given url will be values in the hash. The third argument should be hash. The hash will be the request body. Please read examples below for more details.

Raises:

  • (ArgumentError) —

    If the given method is invalid value.



189
190
191
192
193
194
195
196
197
198
 
# File 'lib/appium_lib_core/common/base/driver.rb', line 189

def add_command(method:, url:, name:, &block)
  unless AVAILABLE_METHODS.include? method
    raise ::Appium::Core::Error::ArgumentError, "Available method is either #{AVAILABLE_METHODS}"
  end

  # TODO: Remove this logger before Appium 2.0 release
  ::Appium::Logger.info '[Experimental] this method is experimental for Appium 2.0. This interface may change.'

  @bridge.add_command method: method, url: url, name: name, &block
end

#app_installed?(app_id) ⇒ Boolean

Check whether the specified app is installed on the device

Examples:


@driver.app_installed?("io.appium.bundle")

Returns:

  • (Boolean) 


731
732
733
734
 
# File 'lib/appium_lib_core/common/base/driver.rb', line 731

def app_installed?(app_id)
  # TODO: use mobile command in the background?
  @bridge.app_installed?(app_id)
end

#app_state(app_id) ⇒ AppState::STATUS Also known as: query_app_state

Get the status of an existing application on the device. State:

:not_installed : The current application state cannot be determined/is unknown
:not_running : The application is not running
:running_in_background_suspended : The application is running in the background and is suspended
:running_in_background : The application is running in the background and is not suspended
:running_in_foreground : The application is running in the foreground

For more details: developer.apple.com/documentation/xctest/xcuiapplicationstate

Examples:


@driver.app_state("io.appium.bundle") #=> :not_running
# Compatibility for other clients
@driver.query_app_state("io.appium.bundle") #=> :not_running

Parameters:

  • app_id (String) —

    A target app’s bundle id

Returns:

  • (AppState::STATUS) —

    A number of the state



784
785
786
787
 
# File 'lib/appium_lib_core/common/base/driver.rb', line 784

def app_state(app_id)
  # TODO: use mobile command in the background?
  @bridge.app_state(app_id)
end

#app_strings(language = nil) ⇒ Hash

Deprecated.

Use ‘mobile: getAppStrings’ extension instead.

Return the hash of all localization strings.

Examples:


@driver.app_strings #=> "TransitionsTitle"=>"Transitions", "WebTitle"=>"Web"

Returns:

  • (Hash) 


651
652
653
654
 
# File 'lib/appium_lib_core/common/base/driver.rb', line 651

def app_strings(language = nil)
  ::Appium::Logger.warn "[DEPRECATION] Please use 'mobile: getAppStrings' extension instead"
  @bridge.app_strings(language)
end

#available_contexts ⇒ Array<String>

Returns All usable contexts, as an array of strings.

Examples:


@driver.available_contexts

Returns:

  • (Array<String>) —

    All usable contexts, as an array of strings.



465
466
467
 
# File 'lib/appium_lib_core/common/base/driver.rb', line 465

def available_contexts
  @bridge.available_contexts
end

#back ⇒ String

Get the device window’s size.

Examples:

@driver.back # back to the previous view

Returns:

  • (String) 


934
935
936
 
# File 'lib/appium_lib_core/common/base/driver.rb', line 934

def back
  navigate.back
end

#background_app(duration = 0) ⇒ String

Deprecated.

Use ‘mobile: backgroundApp’ extension instead.

Backgrounds the app for a set number of seconds. This is a blocking application

Examples:


@driver.background_app
@driver.background_app(5)
@driver.background_app(-1) #=> the app never come back. https://github.com/appium/appium/issues/7741

Parameters:

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

    How many seconds to background the app for.

Returns:

  • (String) 


668
669
670
 
# File 'lib/appium_lib_core/common/base/driver.rb', line 668

def background_app(duration = 0)
  @bridge.background_app(duration)
end

#close_app ⇒ Object

Deprecated.

Will be removed, or use ‘windows: closeApp’ extension instead for Windows.

Close an app on device

Examples:


@driver.close_app


624
625
626
 
# File 'lib/appium_lib_core/common/base/driver.rb', line 624

def close_app
  @bridge.close_app
end

#compare_images(mode: :matchFeatures, first_image:, second_image:, options: nil) ⇒ Object 



1086
1087
1088
 
# File 'lib/appium_lib_core/common/base/driver.rb', line 1086

def compare_images(mode: :matchFeatures, first_image:, second_image:, options: nil)
  @bridge.compare_images(mode: mode, first_image: first_image, second_image: second_image, options: options)
end

#context=(context = nil) ⇒ Object Also known as: set_context

Change the context to the given context.

Examples:


@driver.set_context "NATIVE_APP"
@driver.context = "NATIVE_APP"

Parameters:

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

    The context to change to



477
478
479
 
# File 'lib/appium_lib_core/common/base/driver.rb', line 477

def context=(context = nil)
  @bridge.set_context(context)
end

#convert_to_element(id) ⇒ ::Appium::Core::Element

Convert vanilla element response to ::Appium::Core::Element

Examples:

response = {"element-6066-11e4-a52e-4f735466cecf"=>"xxxx", "ELEMENT"=>"xxxx"}
ele = @driver.convert_to_element(response) #=> ::Appium::Core::Element
ele.rect #=> Can get the rect of the element

Parameters:

  • id (Hash) —

    The id which can get as a response from server

Returns:



1179
1180
1181
 
# File 'lib/appium_lib_core/common/base/driver.rb', line 1179

def convert_to_element(id)
  @bridge.convert_to_element id
end

#current_context ⇒ String

Returns The context currently being used.

Examples:


@driver.current_context

Returns:

  • (String) —

    The context currently being used.



455
456
457
 
# File 'lib/appium_lib_core/common/base/driver.rb', line 455

def current_context
  @bridge.current_context
end

#device_time(format = nil) ⇒ String

Deprecated.

Use ‘mobile: getDeviceTime’ extension instead.

Get the time on the device

Examples:


@driver.device_time #=> "2018-06-12T11:13:31+02:00"
@driver.device_time "YYYY-MM-DD" #=> "2018-06-12"

Parameters:

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

    The set of format specifiers. Read momentjs.com/docs/ to get the full list of supported datetime format specifiers. The default format is YYYY-MM-DDTHH:mm:ssZ, which complies to ISO-8601

Returns:

  • (String) —

    Formatted datetime string or the raw command output if formatting fails



850
851
852
853
 
# File 'lib/appium_lib_core/common/base/driver.rb', line 850

def device_time(format = nil)
  ::Appium::Logger.warn "[DEPRECATION] Please use 'mobile: getDeviceTime' extension instead"
  @bridge.device_time(format)
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:

Raises:

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

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

Since:

  • Appium 1.14.0



1165
1166
1167
 
# File 'lib/appium_lib_core/common/base/driver.rb', line 1165

def execute_driver(script: '', type: 'webdriverio', timeout_ms: nil)
  @bridge.execute_driver(script: script, type: type, timeout_ms: timeout_ms)
end

#find_element_by_image(img_path) ⇒ ::Appium::Core::Element

Return an element if current view has a partial image. The logic depends on template matching by OpenCV. image-comparison

You can handle settings for the comparision following below. device-settings

Examples:


@@driver.update_settings({ fixImageFindScreenshotDims: false, fixImageTemplateSize: true,
                           autoUpdateImageElementPosition: true })
e = @@driver.find_element_by_image './test/functional/data/test_element_image.png'

Parameters:

  • img_path (String) —

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

Returns:

Since:

  • Appium 1.8.2



1107
1108
1109
1110
 
# File 'lib/appium_lib_core/common/base/driver.rb', line 1107

def find_element_by_image(img_path)
  template = Base64.strict_encode64 File.read img_path
  find_element :image, template
end

#find_elements_by_image(img_path) ⇒ Array<::Appium::Core::Element>

Return elements if current view has a partial image. The logic depends on template matching by OpenCV. image-comparison

You can handle settings for the comparision following below. device-settings

Examples:


@@driver.update_settings({ fixImageFindScreenshotDims: false, fixImageTemplateSize: true,
                           autoUpdateImageElementPosition: true })
e = @@driver.find_elements_by_image ['./test/functional/data/test_element_image.png']
e == [] # if the 'e' is empty

Parameters:

  • img_path (String) —

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

Returns:

Since:

  • Appium 1.8.2



1130
1131
1132
1133
 
# File 'lib/appium_lib_core/common/base/driver.rb', line 1130

def find_elements_by_image(img_path)
  template = Base64.strict_encode64 File.read img_path
  find_elements :image, template
end

#find_image_occurrence(full_image:, partial_image:, visualize: false, threshold: nil, multiple: nil, match_neighbour_threshold: nil) ⇒ Object 



1072
1073
1074
1075
1076
1077
1078
1079
1080
 
# File 'lib/appium_lib_core/common/base/driver.rb', line 1072

def find_image_occurrence(full_image:, partial_image:, visualize: false, threshold: nil,
                          multiple: nil, match_neighbour_threshold: nil)
  @bridge.find_image_occurrence(full_image: full_image,
                                partial_image: partial_image,
                                visualize: visualize,
                                threshold: threshold,
                                multiple: multiple,
                                match_neighbour_threshold: match_neighbour_threshold)
end

#get_images_similarity(first_image:, second_image:, visualize: false) ⇒ Object 



1082
1083
1084
 
# File 'lib/appium_lib_core/common/base/driver.rb', line 1082

def get_images_similarity(first_image:, second_image:, visualize: false)
  @bridge.get_images_similarity(first_image: first_image, second_image: second_image, visualize: visualize)
end

#get_settings ⇒ Object

Get appium Settings for current test session. Alias of @driver.settings.get

Examples:


@driver.get_settings
@driver.settings.get


320
321
322
 
# File 'lib/appium_lib_core/common/base/driver.rb', line 320

def get_settings
  settings.get
end

#get_timeouts ⇒ Hash

For W3C. Get the timeout related settings on the server side.

Examples:

@driver.get_timeouts

Returns:

  • (Hash) 


958
959
960
 
# File 'lib/appium_lib_core/common/base/driver.rb', line 958

def get_timeouts
  @bridge.get_timeouts
end

#hide_keyboard(close_key = nil, strategy = nil) ⇒ Object

Deprecated.

Use ‘mobile: hideKeyboard’ extension instead.

Hide the onscreen keyboard

Examples:


@driver.hide_keyboard # Close a keyboard with the 'Done' button
@driver.hide_keyboard('Finished') # Close a keyboard with the 'Finished' button
@driver.hide_keyboard(nil, :tapOutside) # Close a keyboard with tapping out side of keyboard

Parameters:

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

    The name of the key which closes the keyboard. Defaults to ‘Done’ for iOS(except for XCUITest).

  • strategy (Symbol) (defaults to: nil) —

    The symbol of the strategy which closes the keyboard. XCUITest ignore this argument. Default for iOS is :pressKey. Default for Android is :tapOutside.



282
283
284
285
 
# File 'lib/appium_lib_core/common/base/driver.rb', line 282

def hide_keyboard(close_key = nil, strategy = nil)
  ::Appium::Logger.warn "[DEPRECATION] Please use 'mobile: hideKeyboard' extension instead"
  @bridge.hide_keyboard close_key, strategy
end

#ime ⇒ Appium::Core::Base::Driver::DeviceIME

Deprecated.

Use ‘mobile: shell’ extension instead.

Returns an instance of DeviceIME

Examples:


@driver.ime.activate engine: 'com.android.inputmethod.latin/.LatinIME'
@driver.ime.available_engines #=> Get the list of IME installed in the target device
@driver.ime.active_engine #=> Get the current active IME such as 'com.android.inputmethod.latin/.LatinIME'
@driver.ime.activated #=> True if IME is activated
@driver.ime.deactivate #=> Deactivate current IME engine

Returns:

  • (Appium::Core::Base::Driver::DeviceIME) 


353
354
355
356
 
# File 'lib/appium_lib_core/common/base/driver.rb', line 353

def ime
  ::Appium::Logger.warn "[DEPRECATION] Please use 'mobile: shell' extension instead"
  @ime ||= DeviceIME.new(@bridge)
end

#ime_activate(ime_name) ⇒ Object

Deprecated.

Use ‘mobile: shell’ extension instead.

Android only. Make an engine that is available active.

Examples:


@driver.ime_activate engine: 'com.android.inputmethod.latin/.LatinIME'
@driver.ime.activate engine: 'com.android.inputmethod.latin/.LatinIME'

Parameters:

  • ime_name (String) —

    The IME owning the activity [required]



368
369
370
 
# File 'lib/appium_lib_core/common/base/driver.rb', line 368

def ime_activate(ime_name)
  ime.activate(ime_name)
end

#ime_activated ⇒ Boolean

Deprecated.

Use ‘mobile: shell’ extension instead.

Examples:


@driver.ime_activated #=> True if IME is activated
@driver.ime.activated #=> True if IME is activated

Returns:

  • (Boolean) 


407
408
409
 
# File 'lib/appium_lib_core/common/base/driver.rb', line 407

def ime_activated
  ime.activated?
end

#ime_active_engine ⇒ Object

Deprecated.

Use ‘mobile: shell’ extension instead.

Android only. Get the name of the active IME engine.

Examples:


@driver.ime_active_engine #=> Get the current active IME such as 'com.android.inputmethod.latin/.LatinIME'
@driver.ime.active_engine #=> Get the current active IME such as 'com.android.inputmethod.latin/.LatinIME'


392
393
394
 
# File 'lib/appium_lib_core/common/base/driver.rb', line 392

def ime_active_engine
  ime.active_engine
end

#ime_available_engines ⇒ Object

Deprecated.

Use ‘mobile: shell’ extension instead.

Android only. List all available input engines on the machine.

Examples:


@driver.ime_available_engines #=> Get the list of IME installed in the target device
@driver.ime.available_engines #=> Get the list of IME installed in the target device


380
381
382
 
# File 'lib/appium_lib_core/common/base/driver.rb', line 380

def ime_available_engines
  ime.available_engines
end

#ime_deactivate ⇒ Object

Deprecated.

Use ‘mobile: shell’ extension instead.

Android only. De-activates the currently-active IME engine.

Examples:


@driver.ime_deactivate #=> Deactivate current IME engine
@driver.ime.deactivate #=> Deactivate current IME engine


419
420
421
 
# File 'lib/appium_lib_core/common/base/driver.rb', line 419

def ime_deactivate
  ime.deactivate
end

#install_app(path, **options) ⇒ Object

Install the given app onto the device. Each options can be snake-case or camel-case. Snake-cases will be converted to camel-case as options value.

Other parameters such as github.com/appium/appium-xcuitest-driver#mobile-installapp also can be set. Then, arguments in snake case will be camel case as its request parameters.

Examples:


@driver.install_app("/path/to/test.apk")
@driver.install_app("/path/to/test.apk", replace: true, timeout: 20000, allow_test_packages: true,
                    use_sdcard: false, grant_permissions: false)
@driver.install_app("/path/to/test.ipa", timeoutMs: 20000)

Parameters:

  • path (String) —

    The absolute local path or remote http URL to an .ipa or .apk file, or a .zip containing one of these.

  • replace (Boolean) —

    Only for Android. Whether to reinstall/upgrade the package if it is already present on the device under test. true by default

  • timeout (Integer) —

    Only for Android. How much time to wait for the installation to complete. 60000ms by default.

  • allow_test_packages (Boolean) —

    Only for Android. Whether to allow installation of packages marked as test in the manifest. false by default

  • use_sdcard (Boolean) —

    Only for Android. Whether to use the SD card to install the app. false by default

  • grant_permissions (Boolean) —

    Only for Android. whether to automatically grant application permissions on Android 6+ after the installation completes. false by default



698
699
700
701
702
 
# File 'lib/appium_lib_core/common/base/driver.rb', line 698

def install_app(path, **options)
  # TODO: use mobile command in the background?
  options = options.transform_keys { |key| key.to_s.gsub(/_./) { |v| v[1].upcase } } unless options.nil?
  @bridge.install_app(path, options)
end

#key_action(async: false) ⇒ Object

Perform ‘key’ actions for W3C module. Generate key pointer action here and users can use this via driver.key_action

The pointer type is ‘key’ by default in the Appium Ruby client. driver.action in Appium Ruby client has ‘pointer’ action by default. This method is a shortcut to set ‘key’ type. Hense this method is equal to driver.action(devices: [::Selenium::WebDriver::Interactions.key(‘keyboard’)]) as below example.

Examples:


element = @driver.find_element(:id, "some id")
@driver.key_action.send_key('hiあ').perform # The 'send_key' is a part of 'KeyActions'
# is equal to:
# @driver.action(devices: [::Selenium::WebDriver::Interactions.key('keyboard')]).send_keys('hiあ').perform


220
221
222
223
224
225
 
# File 'lib/appium_lib_core/common/base/driver.rb', line 220

def key_action(async: false)
  @bridge.action(
    async: async,
    devices: [::Selenium::WebDriver::Interactions.key('keyboard')]
  )
end

#keyboard_shown? ⇒ Boolean Also known as: is_keyboard_shown

Deprecated.

Use ‘mobile: isKeyboardShown’ extension instead.

Get whether keyboard is displayed or not.

Examples:

@driver.is_keyboard_shown # false
@driver.keyboard_shown?   # true

Returns:

  • (Boolean) —

    Return true if keyboard is shown. Return false if keyboard is hidden.



295
296
297
298
 
# File 'lib/appium_lib_core/common/base/driver.rb', line 295

def keyboard_shown?
  ::Appium::Logger.warn "[DEPRECATION] Please use 'mobile: isKeyboardShown' extension instead"
  @bridge.is_keyboard_shown
end

#launch_app ⇒ Object

Deprecated.

Will be removed, or use ‘windows: launchApp’ extension instead for Windows.

Start the simulator and application configured with desired capabilities

Examples:


@driver.launch_app


613
614
615
 
# File 'lib/appium_lib_core/common/base/driver.rb', line 613

def launch_app
  @bridge.launch_app
end

#lock(duration = nil) ⇒ String

Deprecated.

Use ‘mobile: lock’ extension instead.

Lock the device

Examples:


@driver.lock    #=> Lock the device
@driver.lock(5) #=> Lock the device in 5 sec and unlock the device after 5 sec.
                #   Block other commands during locking the device.

Returns:

  • (String) 


237
238
239
240
 
# File 'lib/appium_lib_core/common/base/driver.rb', line 237

def lock(duration = nil)
  ::Appium::Logger.warn "[DEPRECATION] Please use 'mobile: lock' extension instead"
  @bridge.lock(duration)
end

#locked? ⇒ Boolean Also known as: device_locked?

Deprecated.

Use ‘mobile: isLocked’ extension instead.

Check current device status is weather locked or not

Examples:


@driver.device_locked?
@driver.locked?

Returns:

  • (Boolean) 


250
251
252
253
 
# File 'lib/appium_lib_core/common/base/driver.rb', line 250

def locked?
  ::Appium::Logger.warn "[DEPRECATION] Please use 'mobile: isLocked' extension instead"
  @bridge.device_locked?
end

#logs ⇒ Appium::Core::Logs

Get the device window’s logs.

Examples:


@driver.logs.available_types # [:syslog, :crashlog, :performance]
@driver.logs.get :syslog # []

Returns:



946
947
948
 
# File 'lib/appium_lib_core/common/base/driver.rb', line 946

def logs
  @logs ||= Logs.new(@bridge)
end

#long_press_keycode(key, metastate: [], flags: []) ⇒ Object

Deprecated.

Use ‘mobile: pressKey’ extension instead.

Long press keycode on the device. developer.android.com/reference/android/view/KeyEvent.html

Examples:


@driver.long_press_keycode 66
@driver.long_press_keycode 66, flags: [0x20, 0x2000]
@driver.long_press_keycode 66, metastate: [1], flags: [32, 8192]

Parameters:



601
602
603
604
 
# File 'lib/appium_lib_core/common/base/driver.rb', line 601

def long_press_keycode(key, metastate: [], flags: [])
  ::Appium::Logger.warn "[DEPRECATION] Please use 'mobile: pressKey' extension instead"
  @bridge.long_press_keycode(key, metastate: metastate, flags: flags)
end

#match_images_features(first_image:, second_image:, detector_name: 'ORB', match_func: 'BruteForce', good_matches_factor: nil, visualize: false) ⇒ Object

Image Comparison



1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
 
# File 'lib/appium_lib_core/common/base/driver.rb', line 1058

def match_images_features(first_image:,
                          second_image:,
                          detector_name: 'ORB',
                          match_func: 'BruteForce',
                          good_matches_factor: nil,
                          visualize: false)
  @bridge.match_images_features(first_image: first_image,
                                second_image: second_image,
                                detector_name: detector_name,
                                match_func: match_func,
                                good_matches_factor: good_matches_factor,
                                visualize: visualize)
end

#multi_touch(actions) ⇒ Object 



860
861
862
 
# File 'lib/appium_lib_core/common/base/driver.rb', line 860

def multi_touch(actions)
  @bridge.multi_touch(actions)
end

#perform_actions(data) ⇒ Object

Send multiple W3C action chains to server. Use @driver.action for single action chain.

@example: Zoom

f1 = ::Selenium::WebDriver::Interactions.pointer(:touch, name: 'finger1')
f1.create_pointer_move(duration: 1, x: 200, y: 500,
                       origin: ::Selenium::WebDriver::Interactions::PointerMove::VIEWPORT)
f1.create_pointer_down(:left)
f1.create_pointer_move(duration: 1, x: 200, y: 200,
                       origin: ::Selenium::WebDriver::Interactions::PointerMove::VIEWPORT)
f1.create_pointer_up(:left)

f2 = ::Selenium::WebDriver::Interactions.pointer(:touch, name: 'finger2')
f2.create_pointer_move(duration: 1, x: 200, y: 500,
                       origin: ::Selenium::WebDriver::Interactions::PointerMove::VIEWPORT)
f2.create_pointer_down(:left)
f2.create_pointer_move(duration: 1, x: 200, y: 800,
                       origin: ::Selenium::WebDriver::Interactions::PointerMove::VIEWPORT)
f2.create_pointer_up(:left)

@driver.perform_actions [f1, f2] #=> 'nil' if the action succeed

Parameters:

  • data (Array) —

    Array of actions

Returns:

  • nil|error

Raises:



890
891
892
893
894
895
896
897
898
899
900
 
# File 'lib/appium_lib_core/common/base/driver.rb', line 890

def perform_actions(data)
  raise ::Appium::Core::Error::ArgumentError, "'#{data}' must be Array" unless data.is_a? Array

  # NOTE: 'add_input' in Selenium Ruby implementation has additional 'pause'.
  # This implementation is to avoid the additional pause.
  # https://github.com/SeleniumHQ/selenium/blob/64447d4b03f6986337d1ca8d8b6476653570bcc1/rb/lib/selenium/webdriver/common/action_builder.rb#L207

  @bridge.send_actions data.map(&:encode).compact
  data.each(&:clear_actions)
  nil
end

#press_keycode(key, metastate: [], flags: []) ⇒ Object

Deprecated.

Use ‘mobile: pressKey’ extension instead.

Press keycode on the device. developer.android.com/reference/android/view/KeyEvent.html

Examples:


@driver.press_keycode 66
@driver.press_keycode 66, flags: [0x02]
@driver.press_keycode 66, metastate: [1], flags: [32]

Parameters:



577
578
579
580
 
# File 'lib/appium_lib_core/common/base/driver.rb', line 577

def press_keycode(key, metastate: [], flags: [])
  ::Appium::Logger.warn "[DEPRECATION] Please use 'mobile: pressKey' extension instead"
  @bridge.press_keycode(key, metastate: metastate, flags: flags)
end

#pull_file(path) ⇒ Base64-decoded

Pull a file from the remote device. On Android the application under test should be built with debuggable flag enabled in order to get access to its container on the internal file system.

Examples:


decoded_file = @driver.pull_file '/local/data/some/path'     #=> Get the file at that path
decoded_file = @driver.pull_file 'Shenanigans.app/some/file'
               #=> Get 'some/file' from the install location of Shenanigans.app
decoded_file = @driver.pull_file '@com.appium.example/Documents/file.txt'
               #=> Get 'file.txt' in @com.appium.example/Documents
File.open('proper_filename', 'wb') { |f| f<< decoded_file }

Parameters:

  • path (String) —

    Either an absolute path OR, for iOS devices, a path relative to the app, as described. If the path starts with application id prefix, then the file will be pulled from the root of the corresponding application container. Otherwise the root folder is considered as / on Android and on iOS it is a media folder root (real devices only). Only pulling files from application containers is supported for iOS Simulator. Provide the remote path in format @bundle.identifier:container_type/relative_path_in_container

Returns:

  • (Base64-decoded) —

    Base64 decoded data



527
528
529
530
 
# File 'lib/appium_lib_core/common/base/driver.rb', line 527

def pull_file(path)
  # TODO: use 'mobile: pullFile' internally
  @bridge.pull_file(path)
end

#pull_folder(path) ⇒ Base64-decoded

Pull a folder content from the remote device. On Android the application under test should be built with debuggable flag enabled in order to get access to its container on the internal file system.

Examples:


decoded_file = @driver.pull_folder '/data/local/tmp' #=> Get the folder at that path
decoded_file = @driver.pull_file '@com.appium.example/Documents' #=> Get 'Documents' in @com.appium.example
File.open('proper_filename', 'wb') { |f| f<< decoded_file }

Parameters:

  • path (String) —

    Absolute path to the folder. If the path starts with @applicationId/ prefix, then the folder will be pulled from the root of the corresponding application container. Otherwise the root folder is considered as / on Android and on iOS it is a media folder root (real devices only). Only pulling files from application containers is supported for iOS Simulator. Provide the remote path in format @bundle.identifier:container_type/relative_path_in_container

Returns:

  • (Base64-decoded) —

    Base64 decoded data which is zip archived



553
554
555
556
 
# File 'lib/appium_lib_core/common/base/driver.rb', line 553

def pull_folder(path)
  # TODO: use 'mobile: pullFolder' internally
  @bridge.pull_folder(path)
end

#push_file(path, filedata) ⇒ Object

Place a file in a specific location on the device. On Android, the application under test should be built with debuggable flag enabled in order to get access to its container on the internal file system.

Examples:


@driver.push_file "/file/to/path", "data"

file = File.read "your/path/to/test_image.png"
@driver.push_file "/sdcard/Pictures", file # Push a file binary to /sdcard/Pictures path in Android

Parameters:

  • path (String) —

    Either an absolute path OR, for iOS devices, a path relative to the app, as described. If the path starts with application id prefix, then the file will be pushed to the root of the corresponding application container.

  • filedata (String) —

    Raw file data to be sent to the device. Converted to base64 in the method.



498
499
500
501
 
# File 'lib/appium_lib_core/common/base/driver.rb', line 498

def push_file(path, filedata)
  # TODO: use 'mobile: pushFile' internally
  @bridge.push_file(path, filedata)
end

#remove_app(app_id, keep_data: nil, timeout: nil) ⇒ Object

Examples:


@driver.remove_app("io.appium.bundle")
@driver.remove_app("io.appium.bundle", keep_data: false, timeout, 10000)

Parameters:

  • app_id (Strong) —

    BundleId for iOS or package name for Android

  • keep_data (Boolean) (defaults to: nil) —

    Only for Android. Whether to keep application data and caches after it is uninstalled. false by default

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

    Only for Android. How much time to wait for the uninstall to complete. 20000ms by default.



719
720
721
722
 
# File 'lib/appium_lib_core/common/base/driver.rb', line 719

def remove_app(app_id, keep_data: nil, timeout: nil)
  # TODO: use mobile command in the background?
  @bridge.remove_app(app_id, keep_data: keep_data, timeout: timeout)
end

#reset ⇒ Object

Deprecated.

Reset the device, relaunching the application.

Examples:


@driver.reset


635
636
637
638
639
640
641
 
# File 'lib/appium_lib_core/common/base/driver.rb', line 635

def reset
  ::Appium::Logger.warn(
    '[DEPRECATION] reset is deprecated. Please use terminate_app and activate_app, ' \
    'or quit and create a new session instead.'
  )
  @bridge.reset
end

#session_capabilities ⇒ Selenium::WebDriver::Remote::Capabilities

Retrieve the capabilities of the specified session. It’s almost same as @driver.capabilities but you can get more details.

Examples:

@driver.session_capabilities

#=> uiautomator2
# <Selenium::WebDriver::Remote::Capabilities:0x007fa38dae1360
# @capabilities=
#     {:browser_name=>nil,
#      :browser_version=>nil,
#      :platform_name=>"android",
#      :page_load_strategy=>nil,
#      :remote_session_id=>nil,
#      :accessibility_checks=>nil,
#      :profile=>nil,
#      :rotatable=>nil,
#      :device=>nil,
#      "platform"=>"LINUX",
#      "webStorageEnabled"=>false,
#      "takesScreenshot"=>true,
#      "javascriptEnabled"=>true,
#      "databaseEnabled"=>false,
#      "networkConnectionEnabled"=>true,
#      "locationContextEnabled"=>false,
#      "warnings"=>{},
#      "desired"=>
#          {"platformName"=>"android",
#           "automationName"=>"uiautomator2",
#           "app"=>"/path/to/app/api.apk.zip",
#           "platformVersion"=>"8.1.0",
#           "deviceName"=>"Android Emulator",
#           "appPackage"=>"io.appium.android.apis",
#           "appActivity"=>"io.appium.android.apis.ApiDemos",
#           "someCapability"=>"some_capability",
#      "automationName"=>"uiautomator2",
#      "app"=>"/path/to/app/api.apk.zip",
#      "platformVersion"=>"8.1.0",
#      "deviceName"=>"emulator-5554",
#      "appPackage"=>"io.appium.android.apis",
#      "appActivity"=>"io.appium.android.apis.ApiDemos",
#      "someCapability"=>"some_capability",
#      "deviceUDID"=>"emulator-5554",
#      "deviceScreenSize"=>"1080x1920",
#      "deviceScreenDensity"=>420,
#      "deviceModel"=>"Android SDK built for x86",
#      "deviceManufacturer"=>"Google",
#      "pixelRatio"=>2.625,
#      "statBarHeight"=>63,
#      "viewportRect"=>{"left"=>0, "top"=>63, "width"=>1080, "height"=>1731}}>
#
#=> XCUITest
# <Selenium::WebDriver::Remote::Capabilities:0x007fb15dc01370
# @capabilities=
#     {:browser_name=>"UICatalog",
#      :browser_version=>nil,
#      :platform_name=>"ios",
#      :page_load_strategy=>nil,
#      :remote_session_id=>nil,
#      :accessibility_checks=>nil,
#      :profile=>nil,
#      :rotatable=>nil,
#      :device=>"iphone",
#      "udid"=>"DED4DBAD-8E5E-4AD6-BDC4-E75CF9AD84D8",
#      "automationName"=>"XCUITest",
#      "app"=>"/path/to/app/UICatalog.app",
#      "platformVersion"=>"11.4",
#      "deviceName"=>"iPhone Simulator",
#      "useNewWDA"=>true,
#      "useJSONSource"=>true,
#      "someCapability"=>"some_capability",
#      "sdkVersion"=>"11.4",
#      "CFBundleIdentifier"=>"com.example.apple-samplecode.UICatalog",
#      "pixelRatio"=>2,
#      "statBarHeight"=>23.4375,
#      "viewportRect"=>{"left"=>0, "top"=>47, "width"=>750, "height"=>1287}}>

Returns:

  • (Selenium::WebDriver::Remote::Capabilities, Selenium::WebDriver::Remote::Capabilities) 


1041
1042
1043
 
# File 'lib/appium_lib_core/common/base/driver.rb', line 1041

def session_capabilities
  @bridge.session_capabilities
end

#sessions ⇒ [Hash]

Returns available sessions on the Appium server

Examples:


@driver.sessions #=> [{'id' => 'c363add8-a7ca-4455-b9e3-9ac4d69e95b3', 'capabilities' => { capabilities as Hash }}]

Returns:

  • ([Hash]) 


1053
1054
1055
 
# File 'lib/appium_lib_core/common/base/driver.rb', line 1053

def sessions
  @bridge.sessions
end

#settings ⇒ Object

Returns an instance of DriverSettings to call get/update.

Examples:


@driver.settings.get
@driver.settings.update('allowInvisibleElements': true)


308
309
310
 
# File 'lib/appium_lib_core/common/base/driver.rb', line 308

def settings
  @settings ||= DriverSettings.new(@bridge)
end

#settings=(value) ⇒ Object Also known as: update_settings

Update Appium Settings for current test session Alias of @driver.settings#update

Examples:


@driver.update_settings({ 'allowInvisibleElements': true })
@driver.settings.update({ 'allowInvisibleElements': true })
@driver.settings = { 'allowInvisibleElements': true }

Parameters:

  • value (Hash) —

    Settings to update, keys are settings, values to value to set each setting to



335
336
337
 
# File 'lib/appium_lib_core/common/base/driver.rb', line 335

def settings=(value)
  settings.update(value)
end

#shake ⇒ Object

Deprecated.

Use ‘mobile: shake’ extension instead.

Cause the device to shake

Examples:


@driver.shake


832
833
834
835
 
# File 'lib/appium_lib_core/common/base/driver.rb', line 832

def shake
  ::Appium::Logger.warn "[DEPRECATION] Please use 'mobile: shake' extension instead"
  @bridge.shake
end

#stop_and_save_recording_screen(file_path) ⇒ Object

Examples:


# iOS
@driver.start_recording_screen video_type: 'libx264'
@driver.stop_and_save_recording_screen 'example.mp4' # Video type 'libx264' can be play as '.mp4' video

# Android
@driver.start_recording_screen
@driver.stop_and_save_recording_screen 'example.mp4'

Parameters:

  • file_path (String) —

    The path to save video decoded from base64 from Appium server.



821
822
823
 
# File 'lib/appium_lib_core/common/base/driver.rb', line 821

def stop_and_save_recording_screen(file_path)
  @bridge.stop_and_save_recording_screen(file_path)
end

#stop_recording_screen(remote_path: nil, user: nil, pass: nil, method: 'PUT') ⇒ Object

Examples:


@driver.stop_recording_screen
@driver.stop_recording_screen remote_path: 'https://example.com', user: 'example', pass: 'pass', method: 'POST'

Parameters:

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

    The path to the remote location, where the resulting video should be uploaded. The following protocols are supported: http/https, ftp. Null or empty string value (the default setting) means the content of resulting file should be encoded as Base64 and passed as the endpoint response value. An exception will be thrown if the generated media file is too big to fit into the available process memory.

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

    The name of the user for the remote authentication.

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

    The password for the remote authentication.

  • method (String) (defaults to: 'PUT') —

    The http multipart upload method name. The ‘PUT’ one is used by default.



805
806
807
 
# File 'lib/appium_lib_core/common/base/driver.rb', line 805

def stop_recording_screen(remote_path: nil, user: nil, pass: nil, method: 'PUT')
  @bridge.stop_recording_screen(remote_path: remote_path, user: user, pass: pass, method: method)
end

#switch_to_default_context ⇒ Object

Deprecated.

Use set context with proper context name instead.

Change to the default context. This is equivalent to set_context nil.

Examples:


@driver.switch_to_default_context


444
445
446
447
 
# File 'lib/appium_lib_core/common/base/driver.rb', line 444

def switch_to_default_context
  ::Appium::Logger.warn '[DEPRECATION] Please set proper context instead of calling this method.'
  @bridge.switch_to_default_context
end

#terminate_app(app_id, timeout: nil) ⇒ Boolean

Terminate the specified app.

Examples:


@driver.terminate_app("io.appium.bundle") # true
@driver.terminate_app("io.appium.bundle", timeout: 500)

Parameters:

  • app_id (Strong) —

    BundleId for iOS or package name for Android

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

    Only for Android. How much time to wait for the application termination to complete. 500ms by default.

Returns:

  • (Boolean) 


760
761
762
763
 
# File 'lib/appium_lib_core/common/base/driver.rb', line 760

def terminate_app(app_id, timeout: nil)
  # TODO: use mobile command in the background?
  @bridge.terminate_app(app_id, timeout: timeout)
end

#touch_actions(actions) ⇒ Object

touch actions



856
857
858
 
# File 'lib/appium_lib_core/common/base/driver.rb', line 856

def touch_actions(actions)
  @bridge.touch_actions(actions)
end

#unlock ⇒ Object

Deprecated.

Use ‘mobile: unlock’ extension instead.

Unlock the device

Examples:


@driver.unlock


263
264
265
266
 
# File 'lib/appium_lib_core/common/base/driver.rb', line 263

def unlock
  ::Appium::Logger.warn "[DEPRECATION] Please use 'mobile: unlock' extension instead"
  @bridge.unlock
end

#update_sending_request_to(protocol:, host:, port:, path:) ⇒ Object

Update server_url and HTTP clients following this arguments, protocol, host, port and path. After this method, @bridge.http will be a new instance following them instead of server_url which is set before creating session. If @bridge.http did not have update_sending_request_to method, this method returns immediately.

Examples:


driver = core.start_driver server_url: 'http://example1.com:8000/wd/hub # @bridge.http is for 'http://example1.com:8000/wd/hub/'
driver.update_sending_request_to protocol: 'https', host: 'example2.com', port: 9000, path: '/wd/hub'
driver.manage.timeouts.implicit_wait = 10 # @bridge.http is for 'https://example2.com:9000/wd/hub/'


108
109
110
111
112
113
114
115
116
117
118
119
 
# File 'lib/appium_lib_core/common/base/driver.rb', line 108

def update_sending_request_to(protocol:, host:, port:, path:)
  unless @bridge.http&.class&.method_defined? :update_sending_request_to
    ::Appium::Logger.warn "#{@bridge.http&.class} has no 'update_sending_request_to'. " \
                          'It keeps current connection target.'
    return
  end

  @bridge.http&.update_sending_request_to(scheme: protocol,
                                          host: host,
                                          port: port,
                                          path: path)
end

#window_rect ⇒ Selenium::WebDriver::Rectangle

Get the device window’s rect.

Examples:

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

Returns:

  • (Selenium::WebDriver::Rectangle) 


924
925
926
 
# File 'lib/appium_lib_core/common/base/driver.rb', line 924

def window_rect
  manage.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) 


910
911
912
 
# File 'lib/appium_lib_core/common/base/driver.rb', line 910

def window_size
  manage.window.size
end

#within_context(context, &block) ⇒ Object

Perform a block within the given context, then switch back to the starting context.

Examples:


result = @driver.within_context('NATIVE_APP') do
  @driver.find_element :tag, "button"
end # The result of 'find_element :tag, "button"'

Parameters:

  • context (String) —

    The context to switch to for the duration of the block.

  • block (Proc) —

    The block to involve within the context



433
434
435
 
# File 'lib/appium_lib_core/common/base/driver.rb', line 433

def within_context(context, &block)
  block_given? ? @bridge.within_context(context, &block) : @bridge.within_context(context)
end