iOS setup

Marathon Cloud runs iOS tests on ARM64 iOS Simulators. XCTest, XCUITest, Flutter via Patrol, and KIF are supported.

Quick start

marathon-cloud run ios \
  --api-key $MARATHON_CLOUD_API_KEY \
  --application build/Build/Products/Debug-iphonesimulator/YourApp.app \
  --test-application build/Build/Products/Debug-iphonesimulator/YourAppUITests-Runner.app

Build for testing

Build with xcodebuild build-for-testing against a simulator destination. Device builds (Debug-iphoneos) will not run.

1. Build from the root of your project.

   xcodebuild build-for-testing \
     -workspace YourApp.xcworkspace \
     -scheme YourApp \
     -destination 'generic/platform=iOS Simulator' \
     -derivedDataPath build

   Use -project YourApp.xcodeproj instead of -workspace if you do not use a workspace.

2. Locate the bundles.

   build/Build/Products/Debug-iphonesimulator/YourApp.app
   build/Build/Products/Debug-iphonesimulator/YourAppUITests-Runner.app

   For unit-test targets that run inside the host app, the test bundle is YourAppTests.xctest inside the app’s PlugIns directory; pass that as --test-application.

Run tests

marathon-cloud run ios \
  --api-key $MARATHON_CLOUD_API_KEY \
  --application build/Build/Products/Debug-iphonesimulator/YourApp.app \
  --test-application build/Build/Products/Debug-iphonesimulator/YourAppUITests-Runner.app \
  --os-version 18.4 \
  --device iPhone-16

The CLI accepts .app and .xctest directories and zips them before upload. Pre-zipped .zip files and .ipa archives are also accepted.

Device selection

Parameter	Description
--os-version	18.2, 18.4, or 26.1. Inferred from --device when omitted.
--device	iPhone-11, iPhone-16, iPhone-16-Plus, iPhone-16-Pro, iPhone-16-Pro-Max on iOS 18.x; iPhone-16-Pro, iPhone-17, iPhone-17-Pro, iPhone-17-Pro-Max on iOS 26.1.
--batch-isolation	default, or uninstall_app to remove the app between batches.

Xcode is selected by the platform from the iOS version. --xcode-version is deprecated and ignored.

Advanced configuration

The examples below omit --api-key; the CLI reads it from MARATHON_CLOUD_API_KEY when the flag is absent.

Environment variables

marathon-cloud run ios \
  --application YourApp.app \
  --test-application YourAppUITests-Runner.app \
  --xctestrun-env "API_BASE_URL=https://api.staging.example.com" \
  --xctestrun-test-env "ENABLE_LOGGING=YES"

--xctestrun-env is visible to the test runner process; --xctestrun-test-env is visible to the app under test. Both are repeatable.

Test plans

Select tests with an .xctestplan file instead of a filter file:

marathon-cloud run ios \
  --application YourApp.app \
  --test-application YourAppUITests-Runner.app \
  --xctestplan-filter-file YourApp.xctestplan \
  --xctestplan-target-name "YourAppUITests"

Permissions

Pre-grant system permissions so tests do not hit permission dialogs:

marathon-cloud run ios \
  --application YourApp.app \
  --test-application YourAppUITests-Runner.app \
  --granted-permission location \
  --granted-permission notifications

Values: calendar, contacts-limited, contacts, location, location-always, photos-add, photos, media-library, microphone, motion, notifications, reminders, siri.

Timeouts

Timeouts are in seconds.

marathon-cloud run ios \
  --application YourApp.app \
  --test-application YourAppUITests-Runner.app \
  --test-timeout-default 300 \
  --test-timeout-max 600

--test-timeout-default applies to every test (default 300). --test-timeout-max caps timeouts that a test plan sets higher.

Code coverage

marathon-cloud run ios \
  --application YourApp.app \
  --test-application YourAppUITests-Runner.app \
  --code-coverage

Troubleshooting

Tests never start on the simulator

The bundle was probably built for iphoneos. Rebuild with -destination 'generic/platform=iOS Simulator' and pick the bundles from Debug-iphonesimulator.

Tests fail to launch with missing symbols

Confirm all frameworks the test runner links are embedded in the runner target, and enable Allow testing Host Application APIs if tests import the app module.

Permission dialogs block tests

Pass the permissions with --granted-permission rather than tapping through dialogs in test code.

Note

See CLI parameters for every flag.