WebAssembly Support

WASI does not have thread spawning method yet, but the existing
implementation blocks threads to wait async test cases synchronously.
This commit introduced a new waiter method for running async test cases in
single-threaded WASI environments, enabled by USE_SWIFT_CONCURRENCY_WAITER
flag.

With the new waiter, `XCTMain` is async runs the given test suites
without blocking the thread by bypassing some synchronous public APIs
like `XCTest.perform` and `XCTest.run`. This ignores those APIs even if
they are overridden by user-defined subclasses, so it's not 100%
compatible with the existing XCTest APIs. This is a trade-off to
support async test execution in single-threaded environments, but it
should be fine because the APIs are seldom overridden by user code.

Author: kateinoigakukun

CMakeLists.txt

@@ -8,7 +8,15 @@ project(XCTest LANGUAGES Swift)
 option(BUILD_SHARED_LIBS "Build shared libraries" ON)
 option(USE_FOUNDATION_FRAMEWORK "Use Foundation.framework on Darwin" NO)
 
-if(NOT CMAKE_SYSTEM_NAME STREQUAL Darwin)
+set(USE_SWIFT_CONCURRENCY_WAITER_default NO)
+
+if(CMAKE_SYSTEM_PROCESSOR STREQUAL wasm32)
+  set(USE_SWIFT_CONCURRENCY_WAITER_default ON)
+endif()
+
+option(USE_SWIFT_CONCURRENCY_WAITER "Use Swift Concurrency-based waiter implementation" "${USE_SWIFT_CONCURRENCY_WAITER_default}")
+
+if(NOT CMAKE_SYSTEM_NAME STREQUAL Darwin AND NOT USE_SWIFT_CONCURRENCY_WAITER)
   find_package(dispatch CONFIG REQUIRED)
   find_package(Foundation CONFIG REQUIRED)
 endif()
@@ -30,6 +38,7 @@ add_library(XCTest
   Sources/XCTest/Private/WaiterManager.swift
   Sources/XCTest/Private/IgnoredErrors.swift
   Sources/XCTest/Private/XCTestCase.TearDownBlocksState.swift
+  Sources/XCTest/Private/DispatchShims.swift
   Sources/XCTest/Public/XCTestRun.swift
   Sources/XCTest/Public/XCTestMain.swift
   Sources/XCTest/Public/XCTestCase.swift
@@ -49,6 +58,12 @@ add_library(XCTest
   Sources/XCTest/Public/Asynchronous/XCTWaiter.swift
   Sources/XCTest/Public/Asynchronous/XCTestCase+Asynchronous.swift
   Sources/XCTest/Public/Asynchronous/XCTestExpectation.swift)
+
+if(USE_SWIFT_CONCURRENCY_WAITER)
+  target_compile_definitions(XCTest PRIVATE
+    USE_SWIFT_CONCURRENCY_WAITER)
+endif()
+
 if(USE_FOUNDATION_FRAMEWORK)
   target_compile_definitions(XCTest PRIVATE
     USE_FOUNDATION_FRAMEWORK)

Sources/XCTest/Private/DispatchShims.swift

@@ -0,0 +1,47 @@
+// This source file is part of the Swift.org open source project
+//
+// Copyright (c) 2014 - 2024 Apple Inc. and the Swift project authors
+// Licensed under Apache License v2.0 with Runtime Library Exception
+//
+// See http://swift.org/LICENSE.txt for license information
+// See http://swift.org/CONTRIBUTORS.txt for the list of Swift project authors
+//
+//
+//  NoThreadDispatchShims.swift
+//
+
+// This file is a shim for platforms that don't have libdispatch and do assume a single-threaded environment.
+
+// NOTE: We can't use use `#if canImport(Dispatch)` because Dispatch Clang module is placed directly in the resource
+// directory, and not split into target-specific directories. This means that the module is always available, even on
+// platforms that don't have libdispatch. Thus, we need to check for the actual platform.
+#if os(WASI)
+
+/// No-op shim function
+func dispatchPrecondition(condition: DispatchPredicate) {}
+
+struct DispatchPredicate {
+    static func onQueue<X>(_: X) -> Self {
+        return DispatchPredicate()
+    }
+
+    static func notOnQueue<X>(_: X) -> Self {
+        return DispatchPredicate()
+    }
+}
+
+extension XCTWaiter {
+    /// Single-threaded queue without any actual queueing
+    struct DispatchQueue {
+        init(label: String) {}
+
+        func sync<T>(_ body: () -> T) -> T {
+            body()
+        }
+        func async(_ body: @escaping () -> Void) {
+            body()
+        }
+    }
+}
+
+#endif

Sources/XCTest/Private/WaiterManager.swift

@@ -9,6 +9,7 @@
 //
 //  WaiterManager.swift
 //
+#if !USE_SWIFT_CONCURRENCY_WAITER
 
 internal protocol ManageableWaiter: AnyObject, Equatable {
     var isFinished: Bool { get }
@@ -143,3 +144,5 @@ internal final class WaiterManager<WaiterType: ManageableWaiter> : NSObject {
     }
 
 }
+
+#endif

Sources/XCTest/Public/Asynchronous/XCTNSNotificationExpectation.swift

@@ -10,6 +10,8 @@
 //  XCTNSNotificationExpectation.swift
 //
 
+#if !USE_SWIFT_CONCURRENCY_WAITER
+
 /// Expectation subclass for waiting on a condition defined by a Foundation Notification instance.
 open class XCTNSNotificationExpectation: XCTestExpectation {
 
@@ -114,3 +116,5 @@ open class XCTNSNotificationExpectation: XCTestExpectation {
 /// - SeeAlso: `XCTNSNotificationExpectation.handler`
 @available(*, deprecated, renamed: "XCTNSNotificationExpectation.Handler")
 public typealias XCNotificationExpectationHandler = XCTNSNotificationExpectation.Handler
+
+#endif

Sources/XCTest/Public/Asynchronous/XCTNSPredicateExpectation.swift

@@ -10,6 +10,8 @@
 //  XCTNSPredicateExpectation.swift
 //
 
+#if !USE_SWIFT_CONCURRENCY_WAITER
+
 /// Expectation subclass for waiting on a condition defined by an NSPredicate and an optional object.
 open class XCTNSPredicateExpectation: XCTestExpectation {
 
@@ -133,3 +135,4 @@ open class XCTNSPredicateExpectation: XCTestExpectation {
 /// - SeeAlso: `XCTNSPredicateExpectation.handler`
 @available(*, deprecated, renamed: "XCTNSPredicateExpectation.Handler")
 public typealias XCPredicateExpectationHandler = XCTNSPredicateExpectation.Handler
+#endif

Sources/XCTest/Public/Asynchronous/XCTWaiter.swift

@@ -117,7 +117,9 @@ open class XCTWaiter {
     private var state = State.ready
     internal var timeout: TimeInterval = 0
     internal var waitSourceLocation: SourceLocation?
+    #if !USE_SWIFT_CONCURRENCY_WAITER
     private weak var manager: WaiterManager<XCTWaiter>?
+    #endif
     private var runLoop: RunLoop?
 
     private weak var _delegate: XCTWaiterDelegate?
@@ -187,9 +189,16 @@ open class XCTWaiter {
     ///   these environments. To ensure compatibility of tests between
     ///   swift-corelibs-xctest and Apple XCTest, it is not recommended to pass
     ///   explicit values for `file` and `line`.
+    #if USE_SWIFT_CONCURRENCY_WAITER
+    @available(*, unavailable, message: "Expectation-based waiting is not available when using the Swift concurrency waiter.")
+    #else
     @available(*, noasync, message: "Use await fulfillment(of:timeout:enforceOrder:) instead.")
+    #endif
     @discardableResult
     open func wait(for expectations: [XCTestExpectation], timeout: TimeInterval, enforceOrder: Bool = false, file: StaticString = #file, line: Int = #line) -> Result {
+        #if USE_SWIFT_CONCURRENCY_WAITER
+        fatalError("This method is not available when using the Swift concurrency waiter.")
+        #else
         precondition(Set(expectations).count == expectations.count, "API violation - each expectation can appear only once in the 'expectations' parameter.")
 
         self.timeout = timeout
@@ -251,6 +260,7 @@ open class XCTWaiter {
         }
 
         return result
+        #endif
     }
 
     /// Wait on an array of expectations for up to the specified timeout, and optionally specify whether they
@@ -276,9 +286,16 @@ open class XCTWaiter {
     ///   these environments. To ensure compatibility of tests between
     ///   swift-corelibs-xctest and Apple XCTest, it is not recommended to pass
     ///   explicit values for `file` and `line`.
+    #if USE_SWIFT_CONCURRENCY_WAITER
+    @available(*, unavailable, message: "Expectation-based waiting is not available when using the Swift concurrency waiter.")
+    #else
     @available(macOS 12.0, *)
+    #endif
     @discardableResult
     open func fulfillment(of expectations: [XCTestExpectation], timeout: TimeInterval, enforceOrder: Bool = false, file: StaticString = #file, line: Int = #line) async -> Result {
+#if USE_SWIFT_CONCURRENCY_WAITER
+        fatalError("This method is not available when using the Swift concurrency waiter.")
+#else
         return await withCheckedContinuation { continuation in
             // This function operates by blocking a background thread instead of one owned by libdispatch or by the
             // Swift runtime (as used by Swift concurrency.) To ensure we use a thread owned by neither subsystem, use
@@ -288,6 +305,7 @@ open class XCTWaiter {
                 continuation.resume(returning: result)
             }
         }
+#endif
     }
 
     /// Convenience API to create an XCTWaiter which then waits on an array of expectations for up to the specified timeout, and optionally specify whether they
@@ -306,9 +324,17 @@ open class XCTWaiter {
     ///   expectations are not fulfilled before the given timeout. Default is the line
     ///   number of the call to this method in the calling file. It is rare to
     ///   provide this parameter when calling this method.
+    #if USE_SWIFT_CONCURRENCY_WAITER
+    @available(*, unavailable, message: "Expectation-based waiting is not available when using the Swift concurrency waiter.")
+    #else
     @available(*, noasync, message: "Use await fulfillment(of:timeout:enforceOrder:) instead.")
+    #endif
     open class func wait(for expectations: [XCTestExpectation], timeout: TimeInterval, enforceOrder: Bool = false, file: StaticString = #file, line: Int = #line) -> Result {
+#if USE_SWIFT_CONCURRENCY_WAITER
+        fatalError("This method is not available when using the Swift concurrency waiter.")
+#else
         return XCTWaiter().wait(for: expectations, timeout: timeout, enforceOrder: enforceOrder, file: file, line: line)
+#endif
     }
 
     /// Convenience API to create an XCTWaiter which then waits on an array of expectations for up to the specified timeout, and optionally specify whether they
@@ -327,9 +353,17 @@ open class XCTWaiter {
     ///   expectations are not fulfilled before the given timeout. Default is the line
     ///   number of the call to this method in the calling file. It is rare to
     ///   provide this parameter when calling this method.
+    #if USE_SWIFT_CONCURRENCY_WAITER
+    @available(*, unavailable, message: "Expectation-based waiting is not available when using the Swift concurrency waiter.")
+    #else
     @available(macOS 12.0, *)
+    #endif
     open class func fulfillment(of expectations: [XCTestExpectation], timeout: TimeInterval, enforceOrder: Bool = false, file: StaticString = #file, line: Int = #line) async -> Result {
+#if USE_SWIFT_CONCURRENCY_WAITER
+        fatalError("This method is not available when using the Swift concurrency waiter.")
+#else
         return await XCTWaiter().fulfillment(of: expectations, timeout: timeout, enforceOrder: enforceOrder, file: file, line: line)
+#endif
     }
 
     deinit {
@@ -338,6 +372,7 @@ open class XCTWaiter {
         }
     }
 
+#if !USE_SWIFT_CONCURRENCY_WAITER
     private func queue_configureExpectations(_ expectations: [XCTestExpectation]) {
         dispatchPrecondition(condition: .onQueue(XCTWaiter.subsystemQueue))
 
@@ -413,9 +448,11 @@ open class XCTWaiter {
             queue_validateExpectationFulfillment(dueToTimeout: false)
         }
     }
+#endif
 
 }
 
+#if !USE_SWIFT_CONCURRENCY_WAITER
 private extension XCTWaiter {
     func primitiveWait(using runLoop: RunLoop, duration timeout: TimeInterval) {
         // The contract for `primitiveWait(for:)` explicitly allows waiting for a shorter period than requested
@@ -436,6 +473,7 @@ private extension XCTWaiter {
 #endif
     }
 }
+#endif
 
 extension XCTWaiter: Equatable {
     public static func == (lhs: XCTWaiter, rhs: XCTWaiter) -> Bool {
@@ -453,6 +491,7 @@ extension XCTWaiter: CustomStringConvertible {
     }
 }
 
+#if !USE_SWIFT_CONCURRENCY_WAITER
 extension XCTWaiter: ManageableWaiter {
     var isFinished: Bool {
         return XCTWaiter.subsystemQueue.sync {
@@ -479,3 +518,5 @@ extension XCTWaiter: ManageableWaiter {
         }
     }
 }
+
+#endif

Sources/XCTest/Public/Asynchronous/XCTestCase+Asynchronous.swift

@@ -11,6 +11,8 @@
 //  Methods on XCTestCase for testing asynchronous operations
 //
 
+#if !USE_SWIFT_CONCURRENCY_WAITER
+
 public extension XCTestCase {
 
     /// Creates a point of synchronization in the flow of a test. Only one
@@ -265,3 +267,4 @@ internal extension XCTestCase {
             expected: false)
     }
 }
+#endif

Sources/XCTest/Public/XCAbstractTest.swift

@@ -36,20 +36,43 @@ open class XCTest {
     /// testRunClass. If the test has not yet been run, this will be nil.
     open private(set) var testRun: XCTestRun? = nil
 
+    internal var performTask: Task<Void, Never>?
+
+    #if USE_SWIFT_CONCURRENCY_WAITER
+    internal func _performAsync(_ run: XCTestRun) async {
+        fatalError("Must be overridden by subclasses.")
+    }
+    internal func _runAsync() async {
+        guard let testRunType = testRunClass as? XCTestRun.Type else {
+            fatalError("XCTest.testRunClass must be a kind of XCTestRun.")
+        }
+        testRun = testRunType.init(test: self)
+        await _performAsync(testRun!)
+    }
+    #endif
+
     /// The method through which tests are executed. Must be overridden by
     /// subclasses.
+    #if USE_SWIFT_CONCURRENCY_WAITER
+    @available(*, unavailable)
+    #endif
     open func perform(_ run: XCTestRun) {
         fatalError("Must be overridden by subclasses.")
     }
 
     /// Creates an instance of the `testRunClass` and passes it as a parameter
     /// to `perform()`.
+    #if USE_SWIFT_CONCURRENCY_WAITER
+    @available(*, unavailable)
+    #endif
     open func run() {
+        #if !USE_SWIFT_CONCURRENCY_WAITER
         guard let testRunType = testRunClass as? XCTestRun.Type else {
             fatalError("XCTest.testRunClass must be a kind of XCTestRun.")
         }
         testRun = testRunType.init(test: self)
         perform(testRun!)
+        #endif
     }
 
     /// Async setup method called before the invocation of `setUpWithError` for each test method in the class.