Skip to main content
Version: 0.10.1


Marathon supports execution of macOS tests for desktop apps as well as apps targeting iOS, iPadOS, tvOS, visionOS (xctest only) using simulators.

Test execution requires Apple hardware capable of executing tests. This can be a local macOS instance or a remote instance accessible via secure shell. For remote access file transfers are carried out incrementally using rsync.

Device provider can provision simulators on-demand, reuse existing ones if they match desired configuration as well as utilize pre-provisioned simulators. See documentation on workers for more information on this topic.

Marathon is capable of executing both XCUITests and XCTests. Test bundle requires you to specify application under test as well as test application. After preprocessing both of these inputs are distilled into an application bundle (e.g. and xctest bundle ( e.g. my-tests.xctest) or UI test runner app containing xctest bundle (e.g. You can specify .ipa application archives as well as .zip with the same content as application archive. They will be searched for the application and xctest bundles. If there are multiple entries matching description - marathon will fail.


It is much easier to supply the .app application bundle and .xctest bundle directly instead of wasting time on packaging a signed application archive and depending on runtime discovery of your bundles

An exception here is if you actually need to use signed application with certain entitlements, i.e. for macOS desktop testing

Compatibility notes


For users of XcodeGen marathon requires you to specify the following in your project's spec to make sure Info.plist is generated for parsing your app's information:


Test plans

Support for Xcode test plans is intentionally missing: fundamentally test plan is a way of filtering tests and Marathon supports universal test filtering regardless of the test platform. Having multiple layers of filtering is undesirable and leads to cumbersome user experience. The simplest way to achieve test plans is to provide a list of tests in a file by combining dynamic configuration and fully-qualified-test-name filter providing the external file via values-file-filtering.

See XcodeGen docs for more information.