Module: Appium::Core::Device

Extended by:
Forwardable
Defined in:
lib/appium_lib_core/device.rb,
lib/appium_lib_core/device/value.rb,
lib/appium_lib_core/device/context.rb,
lib/appium_lib_core/device/setting.rb,
lib/appium_lib_core/device/keyboard.rb,
lib/appium_lib_core/device/keyevent.rb,
lib/appium_lib_core/device/app_state.rb,
lib/appium_lib_core/device/device_lock.rb,
lib/appium_lib_core/device/ime_actions.rb,
lib/appium_lib_core/device/screen_record.rb,
lib/appium_lib_core/device/touch_actions.rb,
lib/appium_lib_core/device/app_management.rb,
lib/appium_lib_core/device/battery_status.rb,
lib/appium_lib_core/device/file_management.rb,
lib/appium_lib_core/device/image_comparison.rb,
lib/appium_lib_core/device/clipboard_content_type.rb

Defined Under Namespace

Modules: AppManagement, AppState, BatteryStatus, Clipboard, Context, DeviceLock, FileManagement, ImageComparison, ImeActions, KeyEvent, Keyboard, Setting, TouchActions, Value Classes: ScreenRecord

Class Method Summary collapse

Instance Method Summary collapse

Class Method Details

.add_endpoint_method(method) ⇒ Object 



563
564
565
566
567
568
 
# File 'lib/appium_lib_core/device.rb', line 563

def add_endpoint_method(method)
  block_given? ? create_bridge_command(method, &Proc.new) : create_bridge_command(method)

  delegate_driver_method method
  delegate_from_appium_driver method
end

.create_bridge_command(method) ⇒ Object 



591
592
593
594
595
596
597
598
 
# File 'lib/appium_lib_core/device.rb', line 591

def create_bridge_command(method)
  ::Appium::Core::Base::Bridge::MJSONWP.class_eval do
    block_given? ? class_eval(&Proc.new) : define_method(method) { execute method }
  end
  ::Appium::Core::Base::Bridge::W3C.class_eval do
    block_given? ? class_eval(&Proc.new) : define_method(method) { execute method }
  end
end

.delegate_driver_method(method) ⇒ Object 



585
586
587
588
 
# File 'lib/appium_lib_core/device.rb', line 585

def delegate_driver_method(method)
  return if ::Appium::Core::Base::Driver.method_defined? method
  ::Appium::Core::Base::Driver.class_eval { def_delegator :@bridge, method }
end

.delegate_from_appium_driver(method, delegation_target = :driver) ⇒ Object

For ruby_lib compatibility



580
581
582
 
# File 'lib/appium_lib_core/device.rb', line 580

def delegate_from_appium_driver(method, delegation_target = :driver)
  def_delegator delegation_target, method
end

.extend_webdriver_with_forwardable ⇒ Object 



571
572
573
574
575
576
 
# File 'lib/appium_lib_core/device.rb', line 571

def extend_webdriver_with_forwardable
  return if ::Appium::Core::Base::Driver.is_a? Forwardable
  ::Appium::Core::Base::Driver.class_eval do
    extend Forwardable
  end
end

.extended(_mod) ⇒ Object 



512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
 
# File 'lib/appium_lib_core/device.rb', line 512

def extended(_mod)
  extend_webdriver_with_forwardable

  add_endpoint_method(:shake) do
    def shake
      execute :shake
    end
  end

  add_endpoint_method(:device_time) do
    def device_time(format = nil)
      arg = {}
      arg[:format] = format unless format.nil?
      execute :device_time, {}, arg
    end
  end

  add_endpoint_method(:save_viewport_screenshot) do
    def save_viewport_screenshot(png_path)
      extension = File.extname(png_path).downcase
      if extension != '.png'
        ::Appium::Logger.warn 'name used for saved screenshot does not match file type. '\
                          'It should end with .png extension'
      end
      viewport_screenshot_encode64 = execute_script('mobile: viewportScreenshot')
      File.open(png_path, 'wb') { |f| f << viewport_screenshot_encode64.unpack('m')[0] }
    end
  end

  Value.add_methods
  Setting.add_methods
  KeyEvent.add_methods
  Context.add_methods
  ImeActions.add_methods
  DeviceLock.add_methods
  TouchActions.add_methods
  FileManagement.add_methods
  Keyboard.add_methods
  AppManagement.add_methods
  ScreenRecord.add_methods
  ImageComparison.add_methods
  AppState.add_methods

  # Compatibility for appium_lib
  # TODO: Will remove
  delegate_from_appium_driver :take_element_screenshot
end

Instance Method Details

#activate_app(app_id) ⇒ Hash

Activate(Launch) the specified app.

Examples:


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

Returns:

  • (Hash) 



# File 'lib/appium_lib_core/device.rb', line 150

#app_installed?(app_id) ⇒ Boolean

Check whether the specified app is installed on the device

Examples:


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

Returns:

  • (Boolean) 



# File 'lib/appium_lib_core/device.rb', line 128

#app_strings(language = nil) ⇒ Hash

Return the hash of all localization strings.

Examples:


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

Returns:

  • (Hash) 



# File 'lib/appium_lib_core/device.rb', line 177

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




# File 'lib/appium_lib_core/device.rb', line 455

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



# File 'lib/appium_lib_core/device.rb', line 197

#close_app ⇒ Object

Close an app on device

Examples:


@driver.close_app




# File 'lib/appium_lib_core/device.rb', line 42

#current_context ⇒ String

Returns The context currently being used.

Examples:


@driver.current_context

Returns:

  • (String) —

    The context currently being used.




# File 'lib/appium_lib_core/device.rb', line 447

#device_locked? ⇒ Object

Check current device status is weather locked or not

Examples:


@driver.device_locked?




# File 'lib/appium_lib_core/device.rb', line 74

#device_time ⇒ Object

Get the time on the device




# File 'lib/appium_lib_core/device.rb', line 82

#get_settings ⇒ Object

Get appium Settings for current test session

Examples:


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




# File 'lib/appium_lib_core/device.rb', line 355

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




# File 'lib/appium_lib_core/device.rb', line 210

#ime_activate(ime_name) ⇒ Object

Android only. Make an engine that is available active.

Examples:


ime_activate engine: 'com.android.inputmethod.latin/.LatinIME'

Parameters:

  • ime_name (String) —

    The IME owning the activity [required]




# File 'lib/appium_lib_core/device.rb', line 397

#ime_activated ⇒ Object

Android only. Indicates whether IME input is active at the moment (not if it is available).




# File 'lib/appium_lib_core/device.rb', line 422

#ime_active_engine ⇒ Object

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

Examples:


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




# File 'lib/appium_lib_core/device.rb', line 414

#ime_available_engines ⇒ Object

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

Examples:


ime_available_engines #=> Get the list of IME installed in the target device




# File 'lib/appium_lib_core/device.rb', line 406

#ime_deactivate ⇒ Object

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

Examples:


ime_deactivate #=> Deactivate current IME engine




# File 'lib/appium_lib_core/device.rb', line 430

#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




# File 'lib/appium_lib_core/device.rb', line 100

#is_keyboard_shown ⇒ Boolean

Get whether keyboard is displayed or not.

Examples:

@driver.is_keyboard_shown # false

Returns:

  • (Boolean) —

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




# File 'lib/appium_lib_core/device.rb', line 225

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




# File 'lib/appium_lib_core/device.rb', line 233

#launch_app ⇒ Object

Start the simulator and application configured with desired capabilities

Examples:


@driver.launch_app




# File 'lib/appium_lib_core/device.rb', line 34

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



# File 'lib/appium_lib_core/device.rb', line 186

#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:




# File 'lib/appium_lib_core/device.rb', line 264

#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:




# File 'lib/appium_lib_core/device.rb', line 244

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

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

See Also:




# File 'lib/appium_lib_core/device.rb', line 308

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

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

See Also:




# File 'lib/appium_lib_core/device.rb', line 332

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

Parameters:

  • path (String) —

    The absolute path on the device to store data at. If the path starts with application id prefix, then the file will be pushed to the root of the corresponding application container.

See Also:




# File 'lib/appium_lib_core/device.rb', line 284

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




# File 'lib/appium_lib_core/device.rb', line 116

#replace_value(element, *value) ⇒ Object

Replace the value to element directly




# File 'lib/appium_lib_core/device.rb', line 389

#reset ⇒ Object

Reset the device, relaunching the application.

Examples:


@driver.reset




# File 'lib/appium_lib_core/device.rb', line 50

#save_viewport_screenshot ⇒ Object

Save screenshot except for status bar while ‘@driver.save_screenshot` save entire screen.

Examples:


@driver.save_viewport_screenshot 'path/to/save.png' #=> Get the File instance of viewport_screenshot

Since:

  • 1.3.4




# File 'lib/appium_lib_core/device.rb', line 363

#set_context(context) ⇒ Object

Change the context to the given context.

Examples:


@driver.set_context "NATIVE_APP"

Parameters:

  • context (String) —

    The context to change to




# File 'lib/appium_lib_core/device.rb', line 438

#set_immediate_value(element, *value) ⇒ Object

Set the value to element directly




# File 'lib/appium_lib_core/device.rb', line 381

#shake ⇒ Object

Cause the device to shake

Examples:


@driver.shake




# File 'lib/appium_lib_core/device.rb', line 58

#stop_and_save_recording_screen(file_path) ⇒ Object

Examples:


@driver.stop_and_save_recording_screen 'example.mp4'

Parameters:

  • file_path (String) —

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




# File 'lib/appium_lib_core/device.rb', line 497

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




# File 'lib/appium_lib_core/device.rb', line 480

#terminate_app(app_id) ⇒ 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) —

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

Returns:

  • (Boolean) 



# File 'lib/appium_lib_core/device.rb', line 137

#unlock ⇒ Object

Unlock the device

Examples:


@driver.unlock




# File 'lib/appium_lib_core/device.rb', line 66

#update_settings(settings) ⇒ Object

Update Appium Settings for current test session

Examples:


@driver.update_settings('allowInvisibleElements': true)

Parameters:

  • settings (Hash) —

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




# File 'lib/appium_lib_core/device.rb', line 372