view release on metacpan or  search on metacpan

README.md  view on Meta::CPAN

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)"](#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)"](#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()"](#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)"](#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)"](#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)"](#open_app-params), ["close\_app($params)"](#close_app-params),
["search\_app($params)"](#search_app-params), ["find\_installed\_apps($params)"](#find_installed_apps-params).

## **`find_installed_apps($params)`**

README.md  view on Meta::CPAN

    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"](#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](https://metacpan.org/pod/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](https://metacpan.org/pod/Android%3A%3AElectricSheep%3A%3AAutomator%3A%3APlugins%3A%3AApps%3A%3AViber)
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](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](https://developer.android.com/tools/releases/platform-tools#downloads)

You will need the `adb` executable to be on your path