This GitHub Action helps you start an iOS (tvOS, watchOS) Simulator inside the workflow you are running. It runs equally well on GitHub runners as well as self-hosted runners.
steps:
- uses: actions/checkout@v5
- uses: futureware-tech/simulator-action@v5with:
model: 'iPhone 8'
- run: flutter driveMost inputs are dedicated to refine the selection of device you'd like to launch. However, launching a device requires having a profile -- something which is either preinstalled or needs an Apple ID to download. Since it's unlikely that you'll trust your CI with an Apple ID, it's easier to select one of the preinstalled profiles.
For GitHub Actions runners, a fresh list of devices is maintained in the
Wiki of this
project. Note that UDID and OS version can be rather volatile and may change
when Mac OS updates, so it's recommended to stay with only specifying the model
or if you really need OS version, leave it on the loose side (e.g.
os_version: ">=14.0"). The UDIDs on that page also cannot be used to register
a device with Apple Developer account, because a Simulator UDID
can not be used there.
| Name | Sample values | Description |
|---|---|---|
model | iPhone 8 | Model of the device you'd like to launch |
os | iOS, tvOS, watchOS | OS type of the device |
os_version | >=14.0 | OS version specification in semver format |
udid | ABCD-EFGH | Specific UDID you'd like to launch |
erase_before_boot | true | Whether the data should be erased from device before boot. Starting from a clean state helps getting a stable environment for tests |
wait_for_boot | false | Whether the action must wait for the Simulator to finish booting requested image |
boot_timeout_seconds | 360 | Maximum number of seconds to wait for the Simulator to finish booting (0 disables the timeout) |
boot_retries | 2 | Number of times to retry booting when waiting for the Simulator to finish booting fails. Setting this to 2 will result in 3 attempts: one normal attempt and two retries. |
settle_timeout_seconds | (unset) | Maximum number of seconds to wait, after boot, for the Simulator's background CPU usage (daemons spawned by launchd_sim) to settle down before continuing. Leave unset (default) or set to 0 to skip this check entirely, preserving prior behavior -- nothing is logged either way. When set to a positive value, if the Simulator hasn't settled within that time, a warning is logged and the action continues without failing the job. |
settle_check_interval_seconds | 2 | Number of seconds between checks of the Simulator's background CPU usage. Only relevant when settle_timeout_seconds is set to a positive value. |
settle_cpu_threshold_percent | 20 | Aggregate %CPU (summed across all direct children of launchd_sim) below which the Simulator is considered settled. Only relevant when settle_timeout_seconds is set to a positive value. |
settle_consecutive_samples | 3 | Number of consecutive checks below settle_cpu_threshold_percent required before the Simulator is considered settled. Only relevant when settle_timeout_seconds is set to a positive value. |
shutdown_after_job | true | Whether to shutdown the launched Simulator after the workflow job has been finished |
| Name | Sample values | Description |
|---|---|---|
udid | ABCD-EFGH | UDID of the launched device |