view release on metacpan or  search on metacpan

README  view on Meta::CPAN

 swipe($params)

    Emulates a "swipe" in four directions. Sets the current Android device
    to control. It is only required if you have more than one device
    connected. $params is a HASH_REF which may or should contain:

      * direction

      should be one of

      up

      down

      left

      right

      * dt

      denotes the time taken for the swipe in milliseconds. The smaller its
      value the faster the swipe. A value of 100 is fast enough to swipe to
      the next screen.

    It returns 0 on success, 1 on failure.

 tap($params)

    Emulates a "tap" at the specified location. $params is a HASH_REF which
    must contain one of the following items:

      * position

      should be an ARRAY_REF as the X,Y coordinates of the point to "tap".

      * bounds

      should be an ARRAY_REF of a bounding rectangle of the widget to tap.
      Which contains two ARRAY_REFs for the top-left and bottom-right
      coordinates, e.g.  [ [tlX,tlY], [brX,brY] ] . This is convenient when
      the widget is extracted from an XML dump of the UI (see
      "dump_current_screen_ui($params)") which contains exactly this
      bounding rectangle.

    It returns 0 on success, 1 on failure.

 input_text($params)

    It "types" the specified text into the specified position, where a
    text-input widget is expected to exist. At first it taps at the
    widget's location in order to get the focus. And then it enters the
    text. You need to find the position of the desired text-input widget by
    first getting the current screen UI (using
    "dump_current_screen_ui($params)") and then using an XPath selector to
    identify the desired widget by name/id/attributes. See the source code
    of method "send_message()" in file
    lib/Android/ElectricSheep/Automator/Plugins/Apps/Viber.pm for how this
    is done for the message-sending text-input widget of the Viber app.

    $params is a HASH_REF which must contain text and one of the two
    position (of the text-edit widget) specifiers position or bounds:

      * text

      the text to write on the text edit widget. At the moment, this must
      be plain ASCII string, not unicode. No spaces are accepted. Each
      space character must be replaced with %s.

      * position

      should be an ARRAY_REF as the X,Y coordinates of the point to "tap"
      in order to get the focus of the text edit widget, preceding the text
      input.

      * bounds

      should be an ARRAY_REF of a bounding rectangle of the widget to tap,
      in order to get the focus, preceding the text input. Which contains
      two ARRAY_REFs for the top-left and bottom-right coordinates, e.g.  [
      [tlX,tlY], [brX,brY] ] . This is convenient when the widget is
      extracted from an XML dump of the UI (see
      "dump_current_screen_ui($params)") which contains exactly this
      bounding rectangle.

    It returns 0 on success, 1 on failure.

 clear_input_field($params)

    It clears the contents of a text-input widget at specified location.

    There are several ways to do this. The simplest way (with
    keycombination) does not work in some devices, in which case a failsafe
    way is employed which deletes characters one after the other for 250
    times.

    $params is a HASH_REF which must contain one of the two position (of
    the text-edit widget) specifiers position or bounds:

    <position

      should be an ARRAY_REF as the X,Y coordinates of the point to "tap"
      in order to get the focus of the text edit widget, preceding the text
      input.

    bounds

      should be an ARRAY_REF of a bounding rectangle of the widget to tap,
      in order to get the focus, preceding the text input. Which contains
      two ARRAY_REFs for the top-left and bottom-right coordinates, e.g.  [
      [tlX,tlY], [brX,brY] ] . This is convenient when the widget is
      extracted from an XML dump of the UI (see
      "dump_current_screen_ui($params)") which contains exactly this
      bounding rectangle.

    num-characters

      how many times to press the backspace? Default is 250! But if you
      know the length of the text currently at the text-edit widget then
      enter this here.

    It returns 0 on success, 1 on failure.

 home_screen()

    Go to the "home" screen.

    It returns 0 on success, 1 on failure.

 wake_up()

    "Wake" up the device.

    It returns 0 on success, 1 on failure.

 next_screen()

    Swipe to the next screen (on the right).

    It returns 0 on success, 1 on failure.

 previous_screen()

    Swipe to the previous screen (on the left).

    It returns 0 on success, 1 on failure.

 navigation_menu_back_button()

    Press the "back" button which is the triangular button at the left of
    the navigation menu at the bottom.

    It returns 0 on success, 1 on failure.

 navigation_menu_home_button()

    Press the "home" button which is the circular button in the middle of
    the navigation menu at the bottom.

    It returns 0 on success, 1 on failure.

 navigation_menu_overview_button()

    Press the "overview" button which is the square button at the right of
    the navigation menu at the bottom.

    It returns 0 on success, 1 on failure.

 apps()

    It returns a HASH_REF containing all the packages (apps) installed on
    the device keyed on package name (which is like com.android.settings.
    The list of installed apps is populated either if device-is-connected
    is set to 1 during construction or a call has been made to any of these
    methods: "open_app($params)", "close_app($params)",
    "search_app($params)", "find_installed_apps($params)".

 find_installed_apps($params)

README  view on Meta::CPAN

    Extract the APK file (java bytecode) for an app installed on the device
    and save locally, perhaps, for disassembly and/or modification and/or
    re-installation.

        electric-sheep-pull-app-apk.pl --package calendar2 --wildcard --output anoutdir --configfile config/myapp.conf --device Pixel_2_API_30_x86_

 electric-sheep-install-app

    Install an APK file onto the device, passing extra installation
    parameters -r (for re-install) and -g (for granting permissions),

        electric-sheep-install-app --apk-filename test.apk -p '-r' -p '-g' --configfile config/myapp.conf --device Pixel_2_API_30_x86_

 electric-sheep-viber-send-message.pl

    Send a message using the Viber app.

        electric-sheep-viber-send-message.pl --message 'hello%sthere' --recipient 'george' --configfile config/myapp.conf --device Pixel_2_API_30_x86_

    This one saves a lot of debugging information to debug which can be
    used to deal with special cases or different versions of Viber:

        electric-sheep-viber-send-message.pl --outbase debug --verbosity 1 --message 'hello%sthere' --recipient 'george' --configfile config/myapp.conf --device Pixel_2_API_30_x86_

TESTING

    The normal tests under the t/ directory, initiated with make test
    command, are quite limited in scope because they do not assume a
    connected device. That is, they do not check any functions which
    require interaction with a connected device.

    The live tests under the xt/live directory, initiated with make
    livetest command, require an Android emulator or real device (the
    latter is not recommended) connected to your desktop computer on which
    you are doing the testing. Note that testing with your smartphone is
    not a good idea, please do not do this, unless it is some phone which
    you do not store important data. It is very easy to get an emulated
    Android device running on any OS.

    So, prior to make livetest make sure you have an android emulator up
    and running with, for example, emulator -avd Pixel_2_API_30_x86_ . See
    section "Android Emulators" for how to install, list and run them
    buggers.

    At least one of the author tests under the xt/author directory,
    initiated with make authortest command, require an APK file (to be
    installed on the connected device) which is quite large and it is not
    included in the distribution bundle of this module. Anyway, it is not a
    good idea to install an unknown APK to your device. But if you want to
    make this test then pull an APK of an existing app on your connected
    device with electric-sheep-pull-app-apk.pl and point the test file to
    this APK.

    Testing will not send any messages via the device's apps. E.g. the
    plugin Android::ElectricSheep::Automator::Plugins::Apps::Viber will not
    send a message via Viber but it will mock it.

    The live tests will sometimes fail because, so far, something
    unexpected happened in the device. For example, in testing sending
    input text to a text-edit widget, the calendar will be opened and a new
    entry will be added and its text-edit widget will be targeted. Well,
    sometimes the calendar app will give you some notification on startup
    and this messes up with the focus. Other times, the OS will detect that
    some app is taking too long to launch and pops up a notification about
    "something is not responding, shall I close it". This steals the focus
    and sometimes it causes the tests to fail.

PREREQUISITES

 Android Studio

    This is not a prerequisite but it is highly recommended to install it
    (from https://developer.android.com/studio) on your desktop computer
    because it contains all the executables you will need, saved in a well
    documented file system hierarchy, which can then be accessed from the
    command line. You will not be using the IDE or anything, just the
    accompaniying binaries and libraries it comes with.

    Additionally, Android Studio offers possibly the easiest way to create
    Android Virtual Devices (AVD) which emulate an Android phone of various
    specifications, phone models and sizes, API levels, etc. I mention this
    because one can install apps on an AVD and control them from your
    desktop as long as you are able to receive sms verification codes from
    a real phone. Perhaps you will need an Android emulator image which
    comes with Google Play Services, if you are installing apps from their
    store. This is great for experimenting without plugging in your real
    smartphone on your desktop.

    The bottom line is that by installing Android Studio, you have all the
    executables you need for running things from the command line and,
    additionally, you have the easiest way for creating Android Virtual
    Devices, which emulate Android devices: phones, tablets, automotive
    displays. Once you have this set up, you will not need to open Android
    Studio ever again unless you want to update your kit. All the
    functionality will be accessible from the command line.

 ADB

    Android Debug Bridge (ADB) is the program which communicates with your
    smartphone or an Android Virtual Device from your desktop (Linux, osx
    and the unnamed 0$).

    If you do not want to install Android Studio, the adb executable is
    included in the package called "Android SDK Platform Tools" available
    from the Android official site, here:
    https://developer.android.com/tools/releases/platform-tools#downloads

    You will need the adb executable to be on your path or specify its
    fullpath in the configuration file supplied to
    Android::ElectricSheep::Automator's constructor.

 USB Debugging

    The targeted smartphone must have "USB Debugging" enabled via the
    "Developer mode". This is not to be confused with 'rooted' or
    'jailbroken' modes, none of these are required for experimenting with
    the current module.

    In order to enable "USB Debugging", you need to set the smartphone to
    enter "Developer" mode by following this procedure: