appcommander 0.0.23

Performs controlled Android app automation through UI.

Command Android Apps from Python

Uses uiautomator to automatically and safely control and navigate Android apps. The user can specify some app logic (series of screens and button clicks) that is executed on your Android phone through ADB.

Why

I wanted self-host my Nextcloud calendar with 1 command, from anywhere in the world, no port-forwarding, no DNS stuff, no domain-name, no registrar configuration no nothing. That includes complete Android phone configuration automation for me. Some apps did not have, and perhaps may not want, a configuration API. Configuring Android apps with automated key-presses is not safe because an unexpected event may come up, e.g. a prompt for a phone update, a call may come in etc.

So I wanted a safe- and controlled way to configure the app, using the UI. This repository verifies each step in an arbitrary script, verifies the button is the desired button etc. If unexpected changes are expected, the script aborts.

Also, each phone manufacturer has a different rooting process, this repo can become a library to safely- and automatically root all (rootable) Android phones automatically (except the user must enable ADB themselves).

Example

Usage

First satisfy the prerequisites:

pip install appcommander

Connect your phone, and tell this code which app you want to automate, and how:

python -m src.appcommander -a org.torproject.android -v "16.6.3 RC 1" -t "DAVx5"

which is the same as:

python -m src.appcommander --app-name org.torproject.android \
--version "16.6.3 RC 1" -torify "DAVx5"

Or, to configure DAVx5:

python -m src.appcommander -a at.bitfire.davdroid -v "4.2.6" -nu \
<your_nextcloud_username> -np <your_nextcloud_password> -o <your_onion_url>

For more info, run:

python -m src.appcommander --help

Testing

One can simulate an android phone with:

chmod +x emulate_android.sh
./emulate_android.sh

And then launch the emulated android phone with:

. ~/.profile
cd ~/.android/avd/android-small.avd/
rm *.lock
emulator -avd android-small -netdelay none -netspeed full -skin 768x1280

And run tests with:

python -m pytest

or to see live output, on any tests filenames containing substring: results:

python -m pytest --capture=tee-sys

Test Coverage

Developers can use:

conda env create --file environment.yml
conda activate appcommander
python -m pytest

Currently the test coverage is 65%. For type checking:

mypy --disallow-untyped-calls --disallow-untyped-defs tests/some_test.py

Releasing pip package update

To udate the Python pip package, one can first satisfy the following requirements:

pip install --upgrade pip setuptools wheel
pip install twine

Followed by updating the package with:

rm -r dist
rm -r build
python3 setup.py sdist bdist_wheel
python -m twine upload dist/\*

Developer pip install

mkdir -p ~/bin
cp apk-ct.sh ~/bin/apk-ct
chmod +x ~/bin/apk-ct

Then you can rebuild and locally re-install the appcommander pip package the command:

apk-ct

If you want to quickly test if your changes work, you can go into the root dir of this project and run:

pip install -e .

that installs the latest changes into the pip package locally (into your conda environment).

Show your app-flow

To show how your script works, run (along with any additional input args required for that script):

python -m src.appcommander -a <package_name> -v <app_version> -f \
<additional arguments>

For example:

python -m src.appcommander -a "at.bitfire.davdroid" -v "4.2.6" -f  -nu \
<some_filler> -np <some_filler> -o <some_filler>
python -m src.appcommander -a "at.bitfire.davdroid" -v "4.2.6" -f -nu \
asdf -np asdf -o asdf
python -m src.appcommander -a org.torproject.android -v "16.6.3 RC 1" \
-f -t "DAVx5"