Launch iOS Simulator in GitHub Actions

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.

Usage

steps:
  - uses: actions/checkout@v5
  - uses: futureware-tech/simulator-action@v5
    with:
      model: 'iPhone 8'
  - run: flutter drive

Inputs

Most 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

Outputs

Name	Sample values	Description
udid	ABCD-EFGH	UDID of the launched device