view release on metacpan or  search on metacpan

README.md  view on Meta::CPAN

It closes the package specified in `$params`
on the current device. If there are
no entries yet in the list of installed packages,
it calls the ["find\_installed\_apps($params)"](#find_installed_apps-params) first to populate it.
It will refuse to close multiple apps matched perhaps
by a regular expression in the package specification.

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

- **`package`**

    is required. It can either be
    a scalar string with the exact package name
    or a [Regexp](https://metacpan.org/pod/Regexp) object which is a compiled regular expression
    created by e.g. `qr/^\.com.+?\.settings$/i`. If a regular
    expression, the call will fail if there is not
    exactly one match.

- **`lazy`**

    is a flag to be passed on to ["find\_installed\_apps($params)"](#find_installed_apps-params),
    if needed, to denote whether to enquire
    information about each package (app) at the time of this
    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**)