view release on metacpan or  search on metacpan

README.md  view on Meta::CPAN

`$params` is a HASH\_REF which may or should contain:

- **`extra-fields`**

    optionally add more fields (columns) to the report by `ps`, as an ARRAY\_REF.
    For example, `['TTY','TIME']`.

It needs that connect\_device() to have been called prior to this call

It returns `undef` on failure or a hash with these keys on success:

- **`raw`** : contains the raw \`ps\` output as a string.
- **`perl`** : contains the parsed raw output as a Perl hash with
each item corresponding to one process, keyed on process command and arguments
(as reported by `ps`, verbatim), as a hash keyed on each field (column)
of the `ps` output.
- **`json`** : the above data converted into a JSON string.

## **`pidof($params)`**

It returns the PID of the specified command name.
The specified command name must match the app or command
name exactly. **Use L/pgrep()** if you want to match command
names with a regular expression>.

`$params` is a HASH\_REF which should contain:

- **`name`**

    the name of the process. It can be a command name,
    e.g. `audioserver` or an app name e.g. `android.hardware.vibrator-service.example`.

It returns `undef` on failure or the PID of the matched command on success.

## **`pgrep($params)`**

It returns the PIDs matching the specified command or app
name (which can be an extended regular expression that `pgrep`
understands). The returned array will contain zero, one or more
hashes with keys `pid` and `command`. The former key is the pid of the command
whose full name (as per the process table) will be under the latter key.
Unless parameter `dont-show-command-name` was set to `1`.

`$params` is a HASH\_REF which should contain:

- **`name`**

    the name of the process. It can be a command name,
    e.g. `audioserver` or an app name e.g. `android.hardware.vibrator-service.example`
    or part of these e.g. `audio` or `hardware` or an extended
    regular expression that Android's `pgrep` understands, e.g.
    `^com.+google.+mess`.

It returns `undef` on failure or an ARRAY\_REF containing
a HASH\_REF of data for each command matched (under keys `pid` and `command`).
The returned ARRAY\_REF can contain 0, 1 or more items depending
on what was matched.

## **`geofix($params)`**

It fixes the geolocation of the device to the specified coordinates.
After this, app API calls to get current geolocation will result to this
position (unless they use their own, roundabout way).

`$params` is a HASH\_REF which should contain:

- **`latitude`**

    the latitude of the position as a floating point number.

- **`longitude`**

    the longitude of the position as a floating point number.

It returns `1` on failure or a `0` on success.

## **`dump_current_location()`**

It finds the current GPS location of the device
according to ALL the GPS providers available.

It needs that connect\_device() to have been called prior to this call

It takes no parameters.

On failure, it returns `undef`.

On success, it returns a HASH\_REF of results.
Each item will be keyed on provider name (e.g. '`network provider`')
and will contain the parsed output of
what each GPS provider returned as a HASH\_REF with
the following keys:

- **`provider`** : the provider name. This is also the key of the item
in the parent hash.
- **`latitude`** : the latitude as a floating point number (can be negative too)
or ` <na> ` if the provider failed to return valid output.
- **`longitude`** : the longitude as a floating point number (can be negative too)
or ` <na > ` if the provider failed to return valid output.
- **`last-location-string`** : the last location string, or
` <na > ` if the provider failed to return valid output.

## **`pull_app_apk_from_device($params)`**

It pulls the APK file (bytecode) for the
app(s) matched by the specified package
specification,
from the device and writes them
into the specified output directory, locally.

`$params` is a HASH\_REF which should contain:

- **`package`**

    the package name of the app to pull from the device.
    `package` can be a string containing the fully qualified package name
    or a `Regexp` object.
    The former should be a fully qualified package name, for example '`com.android.gallery2`'.
    The latter is a regular expression matching the package name and
    can be created via the `qr//modifiers` construct,
    for example: `qr/gallery\d$/i`. The regular expression does not
    need to match exactly one app. Any apps matched they will be extracted.

README.md  view on Meta::CPAN

    call (set it to `1`) or lazily, on a if-and-when-needed basis
    (set it to `0` which is the default). `lazy` affects
    all packages except those specified in `packages`, if any. Default is `1`.

- **`force-reload-apps-list`**

    is a flag to be passed on to ["find\_installed\_apps($params)"](#find_installed_apps-params),
    if needed, and can be set to 1 to
    erase previous packages information and start fresh. Default is `0`.

It returns a HASH\_REF of matched packages names (keys) along
with enquired information (as a [Android::ElectricSheep::Automator::AppProperties](https://metacpan.org/pod/Android%3A%3AElectricSheep%3A%3AAutomator%3A%3AAppProperties)
object). At the moment, because ["close\_app($params)"](#close_app-params) allows closing only a single app,
this hash will contain only one entry unless we allow closing multiple
apps (e.g. via a regex which it is already supported) in the future.

# SCRIPTS

For convenience, a few simple scripts are provided:

## **`electric-sheep-find-installed-apps.pl`**

Find all install packages in the connected device. E.g.

    electric-sheep-find-installed-apps.pl --configfile config/myapp.conf --device Pixel_2_API_30_x86_ --output myapps.json

    electric-sheep-find-installed-apps.pl --configfile config/myapp.conf --device Pixel_2_API_30_x86_ --output myapps.json --fast

## **`electric-sheep-open-app.pl`**

Open an app by its exact name or a keyword matching it (uniquely):

    electric-sheep-open-app.pl --configfile config/myapp.conf --name com.android.settings

    electric-sheep-open-app.pl --configfile config/myapp.conf --keyword 'clock'

Note that it constructs a regular expression from escaped user input.

## **`electric-sheep-close-app.pl`**

Close an app by its exact name or a keyword matching it (uniquely):

    electric-sheep-close-app.pl --configfile config/myapp.conf --name com.android.settings

    electric-sheep-close-app.pl --configfile config/myapp.conf --keyword 'clock'

Note that it constructs a regular expression from escaped user input.

## **`electric-sheep-dump-ui.pl`**

Dump the current screen UI as XML to STDOUT or to a file:

    electric-sheep-dump-ui.pl --configfile config/myapp.conf --output ui.xml

Note that it constructs a regular expression from escaped user input.

## **`electric-sheep-dump-current-location.pl`**

Dump the GPS / geo-location position for the device from its various providers, if enabled.

    electric-sheep-dump-current-location.pl --configfile config/myapp.conf --output geolocation.json

## **`electric-sheep-emulator-geofix.pl`**

Set the GPS / geo-location position to the specified coordinates.

    electric-sheep-dump-ui.pl --configfile config/myapp.conf --latitude 12.3 --longitude 45.6

## **`electric-sheep-dump-screen-shot.pl`**

Take a screenshot of the device (current screen) and save to a PNG file.

    electric-sheep-dump-screen-shot.pl --configfile config/myapp.conf --output screenshot.png

## **`electric-sheep-dump-screen-video.pl`**

Record a video of the device's current screen and save to an MP4 file.

    electric-sheep-dump-screen-video.pl --configfile config/myapp.conf --output video.mp4 --time-limit 30

## **`electric-sheep-pull-app-apk.pl`**

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.