# iOS

> iOS apps, on simulators Axx runs, driven through WebDriverAgent, the app on the simulator that drives yours: Axx downloads the build of it that the [Appium](https://appium.io) project publishes on first use, and starts it on each simulator itself. It needs a Mac with Xcode and an iOS simulator runtime.

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

iOS apps, on simulators Axx runs, driven through WebDriverAgent, the app on the simulator that drives yours: Axx downloads the build of it that the [Appium](https://appium.io) project publishes on first use, and starts it on each simulator itself. It needs a Mac with Xcode and an iOS simulator runtime.

**Each scenario has a simulator to itself.** Axx makes simulators as scenarios need them, up to `devices` at once (1 by default: iOS scenarios then take turns), each a clone, deleted when the run ends: for a device type, like iPhone 16, of Axx's own simulator of it, which it sets up once and keeps in its cache (no scenario ever runs on it); for a simulator the project set up, of that one. A scenario leases a simulator for its whole run.

**Each scenario starts from a clean app.** Before the app starts, it is installed afresh (its data and its notifications go with the old one), the simulator's keychain and the app's permissions are reset, the permissions the registration names are granted, the documents a scenario before put On My iPhone are taken out (and the registration's put in), and the location is set. A dialog a scenario leaves unanswered, like a request for notifications, is dismissed as it ends: it would outlive the app and take the next scenario's taps. The app starts in the registration's language, region and time zone. There is no switch that skips it: a scenario is one journey, and that journey is its own.

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

## Settings

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

| Setting | Takes | Values |
|---|---|---|
| `bootTimeout` | How long a simulator may take to boot, like 30m. The simulator Axx sets up once, to clone, takes over ten minutes on GitHub's macOS runners; its clones boot in seconds, and are ready once iOS serves apps' requests for notifications (seconds more, or a minute on a busy Mac). Default 20m. | text |
| `devices` | How many simulators of a device run at once: each scenario has one to itself, so it is how many iOS scenarios run at once. Default 1. | a number |
| `keep` | Keep the simulators booted after the run, for the next run to start at once, instead of making them for each run: in Xcode's set, named Axx <device type> (n), where Device Hub lists them. Each scenario still has its simulator to itself, and its app reset. A watched run (axx run --watch) keeps them. Default false. | `true`, `false` |

## Steps

### `mobile-ios.app`

```gherkin
Given the {word} ios 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 iOS app, and the simulator 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 |
|---|---|---|
| `app` | the app: a simulator build (a `.app` folder, or it zipped), a file of the project | |
| `bundle id` | the app's bundle identifier; with no `app`, an app the simulator has | `the app's own` |
| `device` | a device type Axx makes simulators of, like `iPhone 16` or `iPhone 16, iOS 18.1` (the newest iOS Xcode has, by default); a simulator the project set up, by its name, which Axx clones; or a simulator's UDID | _required_ |
| `permissions` | what the app may use from the start, like `location, photos` (`xcrun simctl help privacy` lists them); notifications cannot be granted: the app asks, and the scenario answers the dialog | |
| `locale` | the app's language and region, like `de-DE` | `en-US` |
| `timezone` | the app's time zone, like `Europe/Berlin` | `UTC` |
| `location` | where the simulator says it is: a latitude and a longitude, like `51.3397, 12.3731` | `none` |
| `photos` | image or video files put in the simulator'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): the library shows each by the time it was taken, from the file's own metadata. A simulator Axx makes, or keeps for runs, is not used again after a scenario that put photos in it (its library cannot be emptied); one of yours keeps them | `none` |
| `documents` | files put On My iPhone, in the simulator's Files, before the app starts, where the document 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). In the picker, tap Browse, then On My iPhone, then the file as a list item, by its name without its extension. The next scenario's reset takes them out again: on a simulator Axx makes, On My iPhone 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 ios app with the following properties:
  | app    | ../courier/ios/build/Build/Products/Debug-iphonesimulator/Courier.app |
  | device | iPhone 16                                                             |
```

_Since 0.1.5._