Base Skip gradle plugin module and unit testing for Skip apps, adapting Swift XCUnit to transpiled Kotlin JUnit test cases.

SkipUnit vends the skip.unit Kotlin package containing a Swift XCTest interface to the Java/Kotlin JUnit testing framework. Combined with the Skip transpiler ↗, this provides automatic transpilation of XCUnit test cases as JUnit tests, which enables parity testing to identify and isolate any differences between your Swift code and your transpiled Skip Kotlin code.

SkipUnit depends on the skip ↗ transpiler plugin and has no additional library dependencies.

It is part of the Skip Core Frameworks and is not intended to be imported directly. The module is transparently adopted through the translation of import XCUnit into import skip.unit.* by the Skip transpiler.

Parity testing is a central aspect of Skip development. It ensures that your Swift and Kotlin behave exactly the same.

You do not need to import any Skip-specific libraries or APIs in order to perform parity testing. The standard modules of XCTest and Foundation, as well as your own library dependencies, will be sufficient for performing most test operations.

Your tests do need to run against both the macOS and iOS platforms, because the Skip tests are only executed when running on the macOS destination. See Running Tests from Xcode.

When writing Swift code that doesn’t need access to device-specific services or other iOS-specific capabilities, the fastest development path is to build and run against macOS. Most common APIs behave the same between macOS and iOS, and running tests locally against the macOS version of an app enables quick unit testing cycles, both when developing with Xcode interactively, as well as running as part of a continuous integration (CI) process by running swift test. When tests need iOS-specific functionality, those tests can be gated inside #if os(iOS) blocks on order to enable them to be run only when targeting the iOS Simulator or device.

Similarly, when running transpiled Kotlin/Gradle tests, the fastest development mode is to run the JUnit tests locally without launching an Android emulator or connecting to a device. While the Java and Kotlin APIs that underly SkipFoundation are sufficient for many testing needs, there are some Android-specific APIs that are needed. This compatibility is provided by the Robolectric framework, which provides a set of Android-compatible APIs for app testing.

Keep in mind that Robolectric is not Android. The local Robolectric testing environment is similar, but not identical, to an actual Android emulator or device. Some Android APIs are missing from Robolectric, and it is possible that the compiled Java bytecode run locally differs from the Dalvik/ART byte code that is run in a true Android environment. If this becomes a problem, follow the instructions below to run the tests on an Android device or emulator instead.

These six modes of testing can be summarized by the following table:

By default, Skip uses the simulated Robolectric Android environment to run your transpiled tests. To run them against an Android device or emulator instead, set the device or emulator ID in the ANDROID_SERIAL environment variable. This can be done either in the Xcode scheme’s Run action arguments for the target, or as a standard environment variable when using the command line:

> ANDROID_SERIAL=emulator-5554 swift test

Skip Lite supports both XCTest and a subset of Swift Testing for writing transpiled tests.

A standard Skip test using XCTest:

import XCTest

final class MyUnitTests: XCTestCase {
    func testSomeLogic() throws {
        XCTAssertEqual(1 + 2, 3, "basic test")
    }
}

You can also write tests using Swift Testing’s @Test and @Suite annotations. The #expect macro maps to assertion functions and #require maps to requireNotNil:

import Testing

@Suite struct MathTests {
    @Test func addition() {
        #expect(1 + 1 == 2)
    }

    @Test func inequality() {
        #expect(3 != 5)
    }
}

Freestanding @Test functions (not inside a struct or class) are also supported and are automatically wrapped in a generated test class for JUnit:

import Testing

@Test func addition() {
    #expect(1 + 2 == 3)
}

The following Swift Testing features are supported:

• @Test functions (both as members and freestanding)
• @Suite types
• #expect with equality (==), inequality (!=), comparisons (>, <, >=, <=), and boolean expressions
• #require for optional unwrapping

Not all Swift Testing features are currently transpiled. Parameterized tests, traits, and tags are not supported.

Note: The Skip transpiler currently does not have access to the internal API of the module being tested. If you take advantage of Swift’s @testable imports to exercise internal API, the transpiler will not be able to perform its usual type inference when translating your test code. This just means that you might have to be more explicit about types and to fully-qualify values (e.g. MyType.value instead of just .value) when unit testing internal API.

The transpiled unit tests are intended to be run as part of the standard Xcode and Swift Package Manager testing process.

The tests are driven by a test harness file called XCSkipTests.swift. If your test target does not already contain a file with this name, the Skip build plugin will auto-generate one during the build. This means that for most projects, you do not need to create or maintain this file yourself — just run swift test and the harness is created for you.

If you need to customize the test harness (for example, to specify a device target or adjust the Gradle task), you can add your own XCSkipTests.swift to your test target and the build plugin will use it instead of generating one:

#if os(macOS) // Skip transpiled tests only run on macOS targets
import SkipTest

/// This test case will run the transpiled tests for the Skip module.
@available(macOS 13, *)
final class XCSkipTests: XCTestCase, XCGradleHarness {
    public func testSkipModule() async throws {
        try await runGradleTests(device: .none) // set device ID to run in Android emulator vs. Robolectric
    }
}
#endif

The transpiled test cases will automatically run whenever testing against the macOS run destination. As such, you need to ensure that your Swift code compiles and runs the same on macOS and iOS. This is a pre-requisite for Skip’s parity testing, which runs the XCUnit test cases on macOS against the transpiled Kotlin tests in the Android testing environment. While many of the Foundation and SwiftUI APIs are identical on macOS and iOS, you may occasionally have to work around minor differences.

The transpiled unit tests are run by forking the gradle test process on the macOS host machine against the output folder of the skip transpiler plugin. The JUnit test output XML files are then parsed, and a report summarizing the test results is presented.

The swift test command on macOS will automatically perform test transpliation. This can be used for headless testing locally as well as on a continuous integration (CI) server.

Note that running test cases will also initiate a Gradle build, which has the side-effect of Gradle downloading all the library dependencies for the modules. When tests depend on frameworks like SkipUI, which depends on many Jetpack Compose libraries, the dependencies can amount to over 1 gigabyte in the ~/.gradle/ folder.

This may lead to a slow initial run of the tests and a perception that the tests may be hanging or excessively slow. Subsequent runs will use the cached dependencies, and will thus run much more quickly.

Once your module and tests have been transpiled, you can run the JUnit tests directly from Android Studio. To open the tests for a module created with skip init, navigate to your module’s Skip/build/<module>.output/<module>Tests/skipstone folder. Control-click the settings.gradle.kts file and select ‘Open with External Editor’ from the resulting context menu.

Running in Android Studio allows you to bypass the iOS tests and to run - and to debug - individual Android tests. This can be helpful when tracking down Android-specific failures.

Test failures differ in the XCTest and JUnit worlds.

When an XCTAssert* failure occurs in Swift, the test failure is noted, but the test continues to run. When the adapted assert* failure occurs in Kotlin, that failure is signalled by an exception, which halts the execution of that test method. This distinction can be noted in the differing number of test failures that occur when mulitple XCTAssert* failures occur. The same applies to XCTFail, but not to XCTSkip, which is the supported and recommended way to prevent tests from running in one or the other environment.

The adaptation from Swift XCUnit to Kotlin JUnit test cases is quite simple. For example:

fun XCTAssertEqual(a: Any?, b: Any?): Unit = org.junit.Assert.assertEquals(b, a)

While you may never need to interact with it directly, the transpiled Kotlin for the example test case above looks like this:

package app.module.name

import skip.lib.*

import skip.unit.*

internal class MyUnitTests: XCTestCase {
    @Test
    internal fun testSomeLogic() = XCTAssertEqual(1 + 2, 3, "basic test")
}

The 10 most recent releases of skiptools/skip-unit ↗:

• Release 1.7.2 ↗ — 2026-09-16
• Release 1.7.1 ↗ — 2026-08-19
• Release 1.7.0 ↗ — 2026-05-25
• Release 1.6.2 ↗ — 2026-05-23
• Release 1.6.1 ↗ — 2026-04-07
• Release 1.6.0 ↗ — 2026-03-12
• Release 1.5.0 ↗ — 2026-02-04
• Release 1.4.0 ↗ — 2025-09-13
• Release 1.3.7 ↗ — 2025-08-13
• Release 1.3.6 ↗ — 2025-08-01

Full history: github.com/skiptools/skip-unit/releases ↗ — .atom feed ↗