# Android

> Android apps, on emulators Axx starts or on devices adb lists, driven by the UiAutomator2 server ([Appium](https://appium.io)'s), which Axx downloads on first use, installs on each device and keeps running while the device is in use. It needs the Android SDK (ANDROID_HOME): its emulator and its devices (AVDs), and adb.

Source: https://axx.nimbusxr.us/references/packs/mobile-android/

Android apps, on emulators Axx starts or on devices adb lists, driven by the UiAutomator2 server ([Appium](https://appium.io)'s), which Axx downloads on first use, installs on each device and keeps running while the device is in use. It needs the Android SDK (ANDROID_HOME): its emulator and its devices (AVDs), and adb.

**Each scenario has a device to itself.** Axx starts emulators of a device (AVD) as scenarios need them, read-only so that several run at once and nothing a scenario changes outlives it, up to `devices` at once (1 by default: Android scenarios then take turns). A scenario leases a device for its whole run.

**Each scenario starts from a clean app.** Before the app starts, its data is cleared (and with it what it stored, its permissions and its notifications), the permissions the registration names are granted, the photos Axx put in the library before are taken out (and the registration's put in), so are the documents in Downloads, the system's file picker starts afresh (on an emulator Axx started), and the device's language, time zone and location are set. There is no switch that skips it: a scenario is one journey, and that journey is its own.

**What the camera sees.** On an emulator Axx starts, the back camera renders the AVD's environment, which Axx sets for each scenario: what `the <app> app's camera sees <file>` gives it (a picture, a video or a glTF scene, seen from where the phone is in it), or else the emulator's own room. In a debuggable app that has ARCore, an agent Axx attaches as the app starts answers ARCore from the scene. An emulator started from a quick-boot snapshot saved with another camera starts afresh the first time a scenario's camera sees something.

Add it to a project with `axx pack add mobile-android`; it builds on [`mobile-core`](https://axx.nimbusxr.us/references/packs/mobile-core/), which comes with it.

## Settings

In `axx.yaml`, under `packs.mobile-android`:

| Setting | Takes | Values |
|---|---|---|
| `bootTimeout` | How long an emulator may take to boot, like 3m. Default 3m. | text |
| `devices` | How many emulators of a device (AVD) run at once: each scenario has one to itself, so it is how many Android scenarios run at once. Default 1. | a number |
| `emulatorArgs` | More arguments for the emulators Axx starts, like [-gpu, host]. On Linux they draw without a GPU (-gpu swiftshader_indirect) unless these name one. | a list of text |

## Steps

### `mobile-android.app`

```gherkin
Given the {word} android app with the following properties:
  | property | value |
```

The table may start with the row naming its columns, as above, or go straight to its rows.

Register an Android app, and the device it runs on. The app starts when a step launches it or opens a link in it.

| Parameter | Takes | For example |
|---|---|---|
| `{word}` | one word, with no spaces | `parcels`, `PX-4101` |

| Property | Takes | Default |
|---|---|---|
| `apk` | the app: an APK, a file of the project | |
| `package` | the app's package; with no `apk`, an app the device has | |
| `activity` | the activity the app starts with | `the APK's launcher activity` |
| `device` | an emulator's device (AVD) Axx starts, like `Pixel_9`, or a device adb lists, by its serial | _required_ |
| `permissions` | the permissions the app has from the start, like `POST_NOTIFICATIONS, ACCESS_FINE_LOCATION` | |
| `locale` | the device's language and region, like `de-DE` | `en-US` |
| `timezone` | the device's time zone, like `Europe/Berlin` | `UTC` |
| `host ports` | ports of the machine Axx runs on that the app reaches as `localhost` on the device, like `5500, 8090`: the app calls `http://localhost:5500` as it does on a developer's device, and gets the service there | |
| `location` | where an emulator says it is, every second as a phone's GPS does: a latitude and a longitude, like `51.3397, 12.3731` | `where an emulator starts (37.4219983, -122.084), whatever the scenario before set` |
| `photos` | image or video files put in the device's photo library before the app starts, for it to pick, like `photos/begin.jpg, photos/end.jpg` (found as a step finds a file: next to the feature file first; put in DCIM/axx): the library shows each by the time it was taken, from the file's own metadata. The next scenario's reset takes them out again | `none` |
| `documents` | files put in the device's Downloads before the app starts, where the system's file picker shows them, for the app to pick, like `documents/safe-place-authorization.pdf` (found as a step finds a file: next to the feature file first; the phone has them by their names). The picker opens at Recent: tap Show roots, then Downloads, then the file. The next scenario's reset takes them out again: on an emulator Axx started, Downloads is emptied, whatever an app saved there too | `none` |
| `appium` | an Appium server of the project's own or a device farm's, which then runs the device, in place of `device` | |
| `capability.<name>` | an Appium capability for that server, like a device farm's options, as text or JSON | |

**Example:**

```gherkin
Given the courier android app with the following properties:
  | apk         | ../courier/android/app/build/outputs/apk/debug/app-debug.apk |
  | device      | Pixel_9                                                      |
  | permissions | POST_NOTIFICATIONS                                           |
```

_Since 0.1.5._

### `mobile-android.back`

```gherkin
When the {word} app's back button is pressed
```

Press Android's back button: back to the previous screen, or out of the app from its first.

| Parameter | Takes | For example |
|---|---|---|
| `{word}` | one word, with no spaces | `parcels`, `PX-4101` |

**Example:**

```gherkin
When the courier app's back button is pressed
```

_Since 0.1.5._