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 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, 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 (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

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:

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.