Module: Appium::Core::Device

Extended by:
Forwardable
Defined in:
lib/appium_lib_core/common/device.rb

Class Method Summary collapse

Instance Method Summary collapse

Class Method Details

.add_endpoint_method(method) ⇒ Object 



536
537
538
539
540
541
 
# File 'lib/appium_lib_core/common/device.rb', line 536

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

.add_handling_context ⇒ Object 



650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
 
# File 'lib/appium_lib_core/common/device.rb', line 650

def add_handling_context
  add_endpoint_method(:within_context) do
    def within_context(context)
      existing_context = current_context
      set_context context
      if block_given?
        result = yield
        set_context existing_context
        result
      else
        set_context existing_context
      end
    end
  end

  add_endpoint_method(:switch_to_default_context) do
    def switch_to_default_context
      set_context nil
    end
  end
end

.add_ime_actions ⇒ Object 



614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
 
# File 'lib/appium_lib_core/common/device.rb', line 614

def add_ime_actions
  add_endpoint_method(:ime_activate) do
    def ime_activate(ime_name)
      # from Selenium::WebDriver::Remote::OSS
      execute :ime_activate_engine, {}, engine: ime_name
    end
  end

  add_endpoint_method(:ime_available_engines) do
    def ime_available_engines
      execute :ime_get_available_engines
    end
  end

  add_endpoint_method(:ime_active_engine) do
    # from Selenium::WebDriver::Remote::OSS
    def ime_active_engine
      execute :ime_get_active_engine
    end
  end

  add_endpoint_method(:ime_activated) do
    # from Selenium::WebDriver::Remote::OSS
    def ime_activated
      execute :ime_is_activated
    end
  end

  add_endpoint_method(:ime_deactivate) do
    # from Selenium::WebDriver::Remote::OSS
    def ime_deactivate
      execute :ime_deactivate, {}
    end
  end
end

.add_keyevent ⇒ Object 



572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
 
# File 'lib/appium_lib_core/common/device.rb', line 572

def add_keyevent
  # Only for Selendroid
  add_endpoint_method(:keyevent) do
    def keyevent(key, metastate = nil)
      args             = { keycode: key }
      args[:metastate] = metastate if metastate
      execute :keyevent, {}, args
    end
  end

  add_endpoint_method(:press_keycode) do
    def press_keycode(key, metastate = nil)
      args             = { keycode: key }
      args[:metastate] = metastate if metastate
      execute :press_keycode, {}, args
    end
  end

  add_endpoint_method(:long_press_keycode) do
    def long_press_keycode(key, metastate = nil)
      args             = { keycode: key }
      args[:metastate] = metastate if metastate
      execute :long_press_keycode, {}, args
    end
  end
end

.add_touch_actions ⇒ Object 



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

def add_touch_actions
  add_endpoint_method(:touch_actions) do
    def touch_actions(actions)
      actions = { actions: [actions].flatten }
      execute :touch_actions, {}, actions
    end
  end

  add_endpoint_method(:multi_touch) do
    def multi_touch(actions)
      execute :multi_touch, {}, actions: actions
    end
  end
end

.create_bridge_command(method) ⇒ Object 



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

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

.delegate_driver_method(method) ⇒ Object 



552
553
554
555
 
# File 'lib/appium_lib_core/common/device.rb', line 552

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 



558
559
560
 
# File 'lib/appium_lib_core/common/device.rb', line 558

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

.extend_webdriver_with_forwardable ⇒ Object 



544
545
546
547
548
549
 
# File 'lib/appium_lib_core/common/device.rb', line 544

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 



393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
 
# File 'lib/appium_lib_core/common/device.rb', line 393

def extended(_mod)
  extend_webdriver_with_forwardable

  ::Appium::Core::Commands::COMMAND_NO_ARG.each_key do |method|
    add_endpoint_method method
  end

  # Don't define selenium-side methods. We pick up from them.
  # ::Appium::Core::Base::Commands::MJSONWP.each_key do |method|
  #   add_endpoint_method method
  # end

  add_endpoint_method(:available_contexts) do
    def available_contexts
      # return empty array instead of nil on failure
      execute(:available_contexts, {}) || []
    end
  end

  add_endpoint_method(:app_strings) do
    def app_strings(language = nil)
      opts = language ? { language: language } : {}
      execute :app_strings, {}, opts
    end
  end

  add_endpoint_method(:lock) do
    def lock(duration = nil)
      opts = duration ? { seconds: duration } : {}
      execute :lock, {}, opts
    end
  end

  add_endpoint_method(:install_app) do
    def install_app(path)
      execute :install_app, {}, appPath: path
    end
  end

  add_endpoint_method(:remove_app) do
    def remove_app(id)
      execute :remove_app, {}, appId: id
    end
  end

  add_endpoint_method(:app_installed?) do
    def app_installed?(app_id)
      execute :app_installed?, {}, bundleId: app_id
    end
  end

  add_endpoint_method(:background_app) do
    def background_app(duration = 0)
      execute :background_app, {}, seconds: duration
    end
  end

  add_endpoint_method(:set_context) do
    def set_context(context = null)
      execute :set_context, {}, name: context
    end
  end

  add_endpoint_method(:hide_keyboard) do
    def hide_keyboard(close_key = nil, strategy = nil)
      option = {}

      option[:key] = close_key || 'Done'        # default to Done key.
      option[:strategy] = strategy || :pressKey # default to pressKey

      execute :hide_keyboard, {}, option
    end
  end

  add_endpoint_method(:take_element_screenshot) do
    def take_element_screenshot(element, png_path)
      result = execute :take_element_screenshot, id: element.ref

      extension = File.extname(png_path).downcase
      if extension != '.png'
        WebDriver.logger.warn 'name used for saved screenshot does not match file type. '\
                        'It should end with .png extension'
      end
      File.open(png_path, 'wb') { |f| f << result.unpack('m')[0] }
    end
  end

  add_endpoint_method(:set_immediate_value) do
    def set_immediate_value(element, *value)
      keys = ::Selenium::WebDriver::Keys.encode(value)
      execute :set_immediate_value, { id: element.ref }, value: Array(keys)
    end
  end

  add_endpoint_method(:replace_value) do
    def replace_value(element, *value)
      keys = ::Selenium::WebDriver::Keys.encode(value)
      execute :replace_value, { id: element.ref }, value: Array(keys)
    end
  end

  add_endpoint_method(:push_file) do
    def push_file(path, filedata)
      encoded_data = Base64.encode64 filedata
      execute :push_file, {}, path: path, data: encoded_data
    end
  end

  add_endpoint_method(:pull_file) do
    def pull_file(path)
      data = execute :pull_file, {}, path: path
      Base64.decode64 data
    end
  end

  add_endpoint_method(:pull_folder) do
    def pull_folder(path)
      data = execute :pull_folder, {}, path: path
      Base64.decode64 data
    end
  end

  add_endpoint_method(:get_settings) do
    def get_settings
      execute :get_settings, {}
    end
  end

  add_endpoint_method(:update_settings) do
    def update_settings(settings)
      execute :update_settings, {}, settings: settings
    end
  end

  add_keyevent
  add_touch_actions
  add_ime_actions
  add_handling_context
end

Instance Method Details

#app_installed?(app_id) ⇒ bool

Check whether the specified app is installed on the device

Examples:


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

Returns:

  • (bool) 



# File 'lib/appium_lib_core/common/device.rb', line 153

#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/common/device.rb', line 162

#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/common/device.rb', line 353

#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/common/device.rb', line 171

#close_app ⇒ Object

Close an app on device

Examples:


@driver.close_app



# File 'lib/appium_lib_core/common/device.rb', line 64

#current_activity ⇒ String

Get current activity name

Examples:


@driver.current_activity # '.ApiDemos'

Returns:

  • (String) —

    An activity name




# File 'lib/appium_lib_core/common/device.rb', line 12

#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/common/device.rb', line 345

#current_package ⇒ String

Get current package name

Examples:


@driver.current_package # 'com.example.android.apis'

Returns:

  • (String) —

    A package name




# File 'lib/appium_lib_core/common/device.rb', line 21

#device_locked? ⇒ Object

Check current device status is weather locked or not

Examples:


@driver.device_locked?



# File 'lib/appium_lib_core/common/device.rb', line 104

#device_time ⇒ Object

Get the time on the device




# File 'lib/appium_lib_core/common/device.rb', line 124

#get_display_density ⇒ Integer

Get connected device’s density.

Examples:


@driver.get_display_density # 320

Returns:

  • (Integer) —

    The size of density




# File 'lib/appium_lib_core/common/device.rb', line 39

#get_network_connection ⇒ Object

Get the device network connection current status See set_network_connection method for return value




# File 'lib/appium_lib_core/common/device.rb', line 112

#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/common/device.rb', line 262

#get_system_bars ⇒ String

Get system bar’s information

Examples:


@driver.get_system_bars

Returns:

  • (String) 



# File 'lib/appium_lib_core/common/device.rb', line 30

#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/common/device.rb', line 184

#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/common/device.rb', line 295

#ime_activated ⇒ Object

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




# File 'lib/appium_lib_core/common/device.rb', line 320

#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/common/device.rb', line 312

#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/common/device.rb', line 304

#ime_deactivate ⇒ Object

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

Examples:


ime_deactivate #=> Deactivate current IME engine



# File 'lib/appium_lib_core/common/device.rb', line 328

#install_app(path) ⇒ Object

Install the given app onto the device

Examples:


@driver.install_app("/path/to/test.apk")



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

#is_keyboard_shown ⇒ Bool

Get whether keyboard is displayed or not.

Examples:

@driver.is_keyboard_shown # false

Returns:

  • (Bool) —

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




# File 'lib/appium_lib_core/common/device.rb', line 48

#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/common/device.rb', line 199

#launch_app ⇒ Object

Start the simulator and application configured with desired capabilities

Examples:


@driver.launch_app



# File 'lib/appium_lib_core/common/device.rb', line 56

#long_press_keycode(key, metastate = nil) ⇒ Object

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

Examples:


@driver.long_press_keycode 82

Parameters:

  • key (integer) —

    The key to long press.

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

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




# File 'lib/appium_lib_core/common/device.rb', line 221

#open_notifications ⇒ Object

Open Android notifications




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

#press_keycode(key, metastate = nil) ⇒ Object

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

Examples:


@driver.press_keycode 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/common/device.rb', line 210

#pull_file(path) ⇒ Object

Retrieve a file from the device. This can retrieve an absolute path or a path relative to the installed app (iOS only).

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.




# File 'lib/appium_lib_core/common/device.rb', line 242

#pull_folder(path) ⇒ Object

Retrieve a folder from the device.

Examples:


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

Parameters:

  • path (String) —

    absolute path to the folder




# File 'lib/appium_lib_core/common/device.rb', line 253

#push_file(path, filedata) ⇒ Object

Place a file in a specific location on the device.

Examples:


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

Parameters:

  • path (String) —

    The absolute path on the device to store data at.

  • filedata (String) —

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




# File 'lib/appium_lib_core/common/device.rb', line 232

#remove_app(app_id) ⇒ Object

Install the given app onto the device

Examples:


@driver.remove_app("io.appium.bundle")



# File 'lib/appium_lib_core/common/device.rb', line 145

#replace_value(element, *value) ⇒ Object

Replace the value to element directly




# File 'lib/appium_lib_core/common/device.rb', line 287

#reset ⇒ Object

Reset the device, relaunching the application.

Examples:


@driver.reset



# File 'lib/appium_lib_core/common/device.rb', line 72

#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/common/device.rb', line 336

#set_immediate_value(element, *value) ⇒ Object

Set the value to element directly




# File 'lib/appium_lib_core/common/device.rb', line 279

#shake ⇒ Object

Cause the device to shake

Examples:


@driver.shake



# File 'lib/appium_lib_core/common/device.rb', line 80

#take_element_screenshot(element, png_path) ⇒ File

Returns Path to the screenshot.

Examples:


@driver.take_element_screenshot(element, "fine_name.png")

Parameters:

Returns:

  • (File) —

    Path to the screenshot.




# File 'lib/appium_lib_core/common/device.rb', line 378

#toggle_flight_mode ⇒ Object

Toggle flight mode on or off

Examples:


@driver.toggle_flight_mode



# File 'lib/appium_lib_core/common/device.rb', line 88

#unlock ⇒ Object

Unlock the device

Examples:


@driver.unlock



# File 'lib/appium_lib_core/common/device.rb', line 96

#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/common/device.rb', line 270