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

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

Constant Summary

Constants included from SearchContext

SearchContext::FINDERS

Instance Method Summary collapse

Methods included from TakeScreenshot

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

Methods included from SearchContext

#find_element, #find_elements

Constructor Details

#initialize(opts = {}) ⇒ Driver

Returns a new instance of Driver.



32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
 
# File 'lib/appium_lib_core/common/base/driver.rb', line 32

def initialize(opts = {})
  listener = opts.delete(:listener)
  @bridge = ::Appium::Core::Base::Bridge.handshake(opts)
  if @bridge.dialect == :oss # MJSONWP
    extend ::Selenium::WebDriver::DriverExtensions::HasTouchScreen
    extend ::Selenium::WebDriver::DriverExtensions::HasLocation
    extend ::Selenium::WebDriver::DriverExtensions::HasNetworkConnection
  elsif @bridge.dialect == :w3c
    # TODO: Only for Appium. Ideally, we'd like to remove the below like selenium-webdriver
    extend ::Selenium::WebDriver::DriverExtensions::HasTouchScreen
    extend ::Selenium::WebDriver::DriverExtensions::HasLocation
    extend ::Selenium::WebDriver::DriverExtensions::HasNetworkConnection
  end
  super(@bridge, listener: listener)
end

Instance Method Details

#activate_app(app_id) ⇒ Hash

Activate(Launch) the specified app.

Examples:


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

Returns:

  • (Hash) 


645
646
647
 
# File 'lib/appium_lib_core/common/base/driver.rb', line 645

def activate_app(app_id)
  @bridge.activate_app(app_id)
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) 


634
635
636
 
# File 'lib/appium_lib_core/common/base/driver.rb', line 634

def app_installed?(app_id)
  @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



684
685
686
 
# File 'lib/appium_lib_core/common/base/driver.rb', line 684

def app_state(app_id)
  @bridge.app_state(app_id)
end

#app_strings(language = nil) ⇒ Hash

Return the hash of all localization strings.

Examples:


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

Returns:

  • (Hash) 


560
561
562
 
# File 'lib/appium_lib_core/common/base/driver.rb', line 560

def app_strings(language = nil)
  @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.



347
348
349
 
# File 'lib/appium_lib_core/common/base/driver.rb', line 347

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) 


825
826
827
 
# File 'lib/appium_lib_core/common/base/driver.rb', line 825

def back
  navigate.back
end

#background_app(duration = 0) ⇒ String

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) 


575
576
577
 
# File 'lib/appium_lib_core/common/base/driver.rb', line 575

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

#close_app ⇒ Object

Close an app on device

Examples:


@driver.close_app



539
540
541
 
# File 'lib/appium_lib_core/common/base/driver.rb', line 539

def close_app
  @bridge.close_app
end

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



968
969
970
 
# File 'lib/appium_lib_core/common/base/driver.rb', line 968

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 = null) ⇒ 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: null) —

    The context to change to



359
360
361
 
# File 'lib/appium_lib_core/common/base/driver.rb', line 359

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

#current_context ⇒ String

Returns The context currently being used.

Examples:


@driver.current_context

Returns:

  • (String) —

    The context currently being used.



337
338
339
 
# File 'lib/appium_lib_core/common/base/driver.rb', line 337

def current_context
  @bridge.current_context
end

#device_time(format = nil) ⇒ String

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



746
747
748
 
# File 'lib/appium_lib_core/common/base/driver.rb', line 746

def device_time(format = nil)
  @bridge.device_time(format)
end

#dialect ⇒ :oss|:w3c

Get the dialect value

Returns:

  • (:oss|:w3c) 


50
51
52
 
# File 'lib/appium_lib_core/common/base/driver.rb', line 50

def dialect
  @bridge.dialect
end

#find_element_by_image(img_path) ⇒ ::Selenium::WebDriver::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



989
990
991
992
 
# File 'lib/appium_lib_core/common/base/driver.rb', line 989

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) ⇒ ::Selenium::WebDriver::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



1012
1013
1014
1015
 
# File 'lib/appium_lib_core/common/base/driver.rb', line 1012

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) ⇒ Object 



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

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

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



964
965
966
 
# File 'lib/appium_lib_core/common/base/driver.rb', line 964

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



188
189
190
 
# File 'lib/appium_lib_core/common/base/driver.rb', line 188

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) 


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

def get_timeouts
  @bridge.get_timeouts
end

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

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`.



121
122
123
 
# File 'lib/appium_lib_core/common/base/driver.rb', line 121

def hide_keyboard(close_key = nil, strategy = nil)
  @bridge.hide_keyboard close_key, strategy
end

#ime ⇒ Object

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



246
247
248
 
# File 'lib/appium_lib_core/common/base/driver.rb', line 246

def ime
  @device_ime ||= DeviceIME.new(@bridge) # rubocop:disable Naming/MemoizedInstanceVariableName
end

#ime_activate(ime_name) ⇒ Object

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]



259
260
261
 
# File 'lib/appium_lib_core/common/base/driver.rb', line 259

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

#ime_activated ⇒ Object

Examples:


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



293
294
295
 
# File 'lib/appium_lib_core/common/base/driver.rb', line 293

def ime_activated
  ime.activated?
end

#ime_active_engine ⇒ Object

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'



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

def ime_active_engine
  ime.active_engine
end

#ime_available_engines ⇒ Object

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



270
271
272
 
# File 'lib/appium_lib_core/common/base/driver.rb', line 270

def ime_available_engines
  ime.available_engines
end

#ime_deactivate ⇒ Object

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

Examples:


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



304
305
306
 
# File 'lib/appium_lib_core/common/base/driver.rb', line 304

def ime_deactivate
  ime.deactivate
end

#install_app(path, replace: nil, timeout: nil, allow_test_packages: nil, use_sdcard: nil, grant_permissions: nil) ⇒ Object

Install the given app onto the device

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)

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) (defaults to: nil) —

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

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

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

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

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

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

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

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

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



599
600
601
602
603
604
605
606
607
608
609
610
611
 
# File 'lib/appium_lib_core/common/base/driver.rb', line 599

def install_app(path,
                replace: nil,
                timeout: nil,
                allow_test_packages: nil,
                use_sdcard: nil,
                grant_permissions: nil)
  @bridge.install_app(path,
                      replace: replace,
                      timeout: timeout,
                      allow_test_packages: allow_test_packages,
                      use_sdcard: use_sdcard,
                      grant_permissions: grant_permissions)
end

#keyboard_shown? ⇒ Boolean Also known as: is_keyboard_shown

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.



132
133
134
 
# File 'lib/appium_lib_core/common/base/driver.rb', line 132

def keyboard_shown?
  @bridge.is_keyboard_shown
end

#keyevent(key, metastate = nil) ⇒ Object

Send keyevent on the device.(Only for Selendroid) developer.android.com/reference/android/view/KeyEvent.html

Examples:


@driver.keyevent 82

Parameters:

  • key (integer) —

    The key to press.

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

    The state the metakeys should be in when pressing the key.



475
476
477
 
# File 'lib/appium_lib_core/common/base/driver.rb', line 475

def keyevent(key, metastate = nil)
  @bridge.keyevent(key, metastate)
end

#launch_app ⇒ Object

Start the simulator and application configured with desired capabilities

Examples:


@driver.launch_app



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

def launch_app
  @bridge.launch_app
end

#lock(duration = nil) ⇒ String

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) 


82
83
84
 
# File 'lib/appium_lib_core/common/base/driver.rb', line 82

def lock(duration = nil)
  @bridge.lock(duration)
end

#locked? ⇒ Boolean Also known as: device_locked?

Check current device status is weather locked or not

Examples:


@driver.device_locked?
@driver.locked?

Returns:

  • (Boolean) 


93
94
95
 
# File 'lib/appium_lib_core/common/base/driver.rb', line 93

def locked?
  @bridge.device_locked?
end

#logs ⇒ String

Get the device window’s logs.

Examples:


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

Returns:

  • (String) 


837
838
839
 
# File 'lib/appium_lib_core/common/base/driver.rb', line 837

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

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

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:



519
520
521
 
# File 'lib/appium_lib_core/common/base/driver.rb', line 519

def long_press_keycode(key, metastate: [], flags: [])
  @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



943
944
945
946
947
948
949
950
951
952
953
954
955
 
# File 'lib/appium_lib_core/common/base/driver.rb', line 943

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 



755
756
757
 
# File 'lib/appium_lib_core/common/base/driver.rb', line 755

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 = @driver.action.add_pointer_input(:touch, '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 = @driver.action.add_pointer_input(:touch, '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:

  • (ArgumentError) 


785
786
787
788
789
790
791
 
# File 'lib/appium_lib_core/common/base/driver.rb', line 785

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

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

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

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:



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

def press_keycode(key, metastate: [], flags: [])
  @bridge.press_keycode(key, metastate: metastate, flags: flags)
end

#pull_file(path) ⇒ Base64-decoded

Pull a file from the simulator/device. On iOS the server should have ifuse libraries installed and configured properly for this feature to work on real devices. 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.

iFuse GitHub page6

osxFuse FAQ

‘Debug Your App’ developer article

Examples:


@driver.pull_file '/local/data/some/path'     #=> Get the file at that path
@driver.pull_file 'Shenanigans.app/some/file' #=> Get 'some/file' from the install location of Shenanigans.app

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

Returns:

  • (Base64-decoded) —

    Base64 decoded data



436
437
438
 
# File 'lib/appium_lib_core/common/base/driver.rb', line 436

def pull_file(path)
  @bridge.pull_file(path)
end

#pull_folder(path) ⇒ Base64-decoded

Pull a folder content from the simulator/device. On iOS the server should have ifuse libraries installed and configured properly for this feature to work on real devices. 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.

iFuse GitHub page6 osxFuse FAQ / ‘Debug Your App’ developer article

Examples:


@driver.pull_folder '/data/local/tmp' #=> Get the folder at that path

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

Returns:

  • (Base64-decoded) —

    Base64 decoded data which is zip archived



462
463
464
 
# File 'lib/appium_lib_core/common/base/driver.rb', line 462

def pull_folder(path)
  @bridge.pull_folder(path)
end

#push_file(path, filedata) ⇒ Object

Place a file in a specific location on the device. On iOS, the server should have ifuse libraries installed and configured properly for this feature to work on real devices. 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.

iFuse GitHub page6

osxFuse FAQ

‘Debug Your App’ developer article

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.



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

def push_file(path, filedata)
  @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.



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

def remove_app(app_id, keep_data: nil, timeout: nil)
  @bridge.remove_app(app_id, keep_data: keep_data, timeout: timeout)
end

#replace_value(element, *value) ⇒ Object

Replace the value to element directly

Examples:


replace_value element, 'hello'



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

def replace_value(element, *value)
  @bridge.replace_value(element, *value)
end

#reset ⇒ Object

Reset the device, relaunching the application.

Examples:


@driver.reset



549
550
551
 
# File 'lib/appium_lib_core/common/base/driver.rb', line 549

def reset
  @bridge.reset
end

#send_keys(*key) ⇒ Object Also known as: type

DEPRECATION

Send keys for a current active element

Examples:


@driver.send_keys 'happy testing!'

Parameters:

  • key (String) —

    Input text



145
146
147
148
149
150
 
# File 'lib/appium_lib_core/common/base/driver.rb', line 145

def send_keys(*key)
  ::Appium::Logger.warn(
    '[DEPRECATION] Driver#send_keys is deprecated in W3C spec. Use driver.action.<command>.perform instead'
  )
  @bridge.send_keys_to_active_element(key)
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::W3C::Capabilities:0x007fa38dae1360
# @capabilities=
#     {:proxy=>nil,
#      :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",
#           "unicodeKeyboard"=>true,
#           "resetKeyboard"=>true},
#      "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",
#      "unicodeKeyboard"=>true,
#      "resetKeyboard"=>true,
#      "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::W3C::Capabilities:0x007fb15dc01370
# @capabilities=
#     {:proxy=>nil,
#      :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) 


938
939
940
 
# File 'lib/appium_lib_core/common/base/driver.rb', line 938

def session_capabilities
  @bridge.session_capabilities
end

#set_immediate_value(element, *value) ⇒ Object

Set the value to element directly

Examples:


@driver.set_immediate_value element, 'hello'



370
371
372
 
# File 'lib/appium_lib_core/common/base/driver.rb', line 370

def set_immediate_value(element, *value)
  @bridge.set_immediate_value(element, *value)
end

#settings ⇒ Object

Returns an instance of DriverSettings to call get/update.

Examples:


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



176
177
178
 
# File 'lib/appium_lib_core/common/base/driver.rb', line 176

def settings
  @driver_settings ||= DriverSettings.new(@bridge) # rubocop:disable Naming/MemoizedInstanceVariableName
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



203
204
205
 
# File 'lib/appium_lib_core/common/base/driver.rb', line 203

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

#shake ⇒ Object

Cause the device to shake

Examples:


@driver.shake



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

def shake
  @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.



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

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.



704
705
706
 
# File 'lib/appium_lib_core/common/base/driver.rb', line 704

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

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

Examples:


@driver.switch_to_default_context



327
328
329
 
# File 'lib/appium_lib_core/common/base/driver.rb', line 327

def switch_to_default_context
  @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) 


661
662
663
 
# File 'lib/appium_lib_core/common/base/driver.rb', line 661

def terminate_app(app_id, timeout: nil)
  @bridge.terminate_app(app_id, timeout: timeout)
end

#touch_actions(actions) ⇒ Object

touch actions



751
752
753
 
# File 'lib/appium_lib_core/common/base/driver.rb', line 751

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

#unlock ⇒ Object

Unlock the device

Examples:


@driver.unlock



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

def unlock
  @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.

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/`



64
65
66
67
68
69
 
# File 'lib/appium_lib_core/common/base/driver.rb', line 64

def update_sending_request_to(protocol:, host:, port:, path:)
  @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) 


815
816
817
 
# File 'lib/appium_lib_core/common/base/driver.rb', line 815

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) 


801
802
803
 
# File 'lib/appium_lib_core/common/base/driver.rb', line 801

def window_size
  manage.window.size
end

#within_context(context) ⇒ 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.



317
318
319
 
# File 'lib/appium_lib_core/common/base/driver.rb', line 317

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