Propose a stabilized C-compatible ABI interface and JSON schema for event streaming.

Author: grynspan

Documentation/ABI/JSON.md

@@ -11,13 +11,9 @@ See https://swift.org/CONTRIBUTORS.txt for Swift project authors
 -->
 
 This document outlines the JSON schemas used by the testing library for its ABI
-entry point and for the `--experimental-event-stream-output` command-line
-argument. For more information about the ABI entry point, see the documentation
-for [ABI.EntryPoint_v0](https://github.com/search?q=repo%3Aapple%2Fswift-testing%EntryPoint_v0&type=code).
-
-> [!WARNING]
-> This JSON schema is still being developed and is subject to any and all
-> changes including removal from the package.
+entry point and for the `--event-stream-output` command-line argument. For more
+information about the ABI entry point, see the documentation for
+[ABIv0.EntryPoint](https://github.com/search?q=repo%3Aapple%2Fswift-testing%EntryPoint&type=code).
 
 ## Modified Backus-Naur form
 
@@ -103,8 +99,8 @@ encoded as a single [JSON Lines](https://jsonlines.org) value.
 
 A stream consists of a sequence of values encoded as [JSON Lines](https://jsonlines.org).
 A single instance of `<output-stream>` is defined per test process and can be
-accessed by passing `--experimental-event-stream-output` to the test executable
-created by `swift build --build-tests`.
+accessed by passing `--event-stream-output` to the test executable created by
+`swift build --build-tests`.
 
 ```
 <output-stream> ::= <output-record>\n | <output-record>\n <output-stream>

Documentation/Proposals/NNNN-json-abi.md

@@ -9,65 +9,27 @@
 //
 
 #if canImport(Foundation) && !SWT_NO_ABI_ENTRY_POINT
-/// The type of the entry point to the testing library used by tools that want
-/// to remain version-agnostic regarding the testing library.
-///
-/// - Parameters:
-///   - argumentsJSON: A buffer to memory representing the JSON encoding of an
-///     instance of `__CommandLineArguments_v0`. If `nil`, a new instance is
-///     created from the command-line arguments to the current process.
-///   - recordHandler: A JSON record handler to which is passed a buffer to
-///     memory representing each record as described in `ABI/JSON.md`.
-///
-/// - Returns: The result of invoking the testing library. The type of this
-///   value is subject to change.
-///
-/// - Throws: Any error that occurred prior to running tests. Errors that are
-///   thrown while tests are running are handled by the testing library.
-///
-/// This function examines the command-line arguments to the current process
-/// and then invokes available tests in the current process.
+private import _TestingInternals
+
+/// An older signature for ``ABIv0/EntryPoint-swift.typealias`` used by Xcode 16
+/// Beta 1.
 ///
-/// - Warning: This function's signature and the structure of its JSON inputs
-///   and outputs have not been finalized yet.
-@_spi(Experimental) @_spi(ForToolsIntegrationOnly)
-public typealias ABIEntryPoint_v0 = @Sendable (
+/// This type will be removed in a future update.
+@available(*, deprecated, message: "Use ABIv0.EntryPoint instead.")
+typealias ABIEntryPoint_v0 = @Sendable (
   _ argumentsJSON: UnsafeRawBufferPointer?,
   _ recordHandler: @escaping @Sendable (_ recordJSON: UnsafeRawBufferPointer) -> Void
 ) async throws -> CInt
 
-/// Get the entry point to the testing library used by tools that want to remain
-/// version-agnostic regarding the testing library.
+/// An older signature for ``ABIv0/entryPoint-swift.type.property`` used by
+/// Xcode 16 Beta 1.
 ///
-/// - Returns: A pointer to an instance of ``ABIEntryPoint_v0`` representing the
-///   ABI-stable entry point to the testing library. The caller owns this memory
-///   and is responsible for deinitializing and deallocating it when done.
-///
-/// This function can be used by tools that do not link directly to the testing
-/// library and wish to invoke tests in a binary that has been loaded into the
-/// current process. The function is emitted into the binary under the name
-/// `"swt_copyABIEntryPoint_v0"` and can be dynamically looked up at runtime
-/// using `dlsym()` or a platform equivalent.
-///
-/// The returned function can be thought of as equivalent to
-/// `swift test --experimental-event-stream-output` except that, instead of
-/// streaming JSON records to a named pipe or file, it streams them to an
-/// in-process callback.
-///
-/// - Warning: This function's signature and the structure of its JSON inputs
-///   and outputs have not been finalized yet.
+/// This function will be removed in a future update.
+@available(*, deprecated, message: "Use ABIv0.entryPoint (swt_abiv0_getEntryPoint()) instead.")
 @_cdecl("swt_copyABIEntryPoint_v0")
-@_spi(Experimental) @_spi(ForToolsIntegrationOnly)
-public func copyABIEntryPoint_v0() -> UnsafeMutableRawPointer {
+@usableFromInline func copyABIEntryPoint_v0() -> UnsafeMutableRawPointer {
   let result = UnsafeMutablePointer<ABIEntryPoint_v0>.allocate(capacity: 1)
-  result.initialize { argumentsJSON, recordHandler in
-    let args = try argumentsJSON.map { argumentsJSON in
-      try JSON.decode(__CommandLineArguments_v0.self, from: argumentsJSON)
-    }
-
-    let eventHandler = try eventHandlerForStreamingEvents(version: args?.experimentalEventStreamVersion, forwardingTo: recordHandler)
-    return await entryPoint(passing: args, eventHandler: eventHandler)
-  }
+  result.initialize { try await ABIv0.entryPoint($0, $1) ? EXIT_SUCCESS : EXIT_FAILURE }
   return .init(result)
 }
 #endif

Sources/Testing/EntryPoints/ABIEntryPoint.swift

@@ -0,0 +1,71 @@
+//
+// This source file is part of the Swift.org open source project
+//
+// Copyright (c) 2023 Apple Inc. and the Swift project authors
+// Licensed under Apache License v2.0 with Runtime Library Exception
+//
+// See https://swift.org/LICENSE.txt for license information
+// See https://swift.org/CONTRIBUTORS.txt for Swift project authors
+//
+
+#if canImport(Foundation) && !SWT_NO_ABI_ENTRY_POINT
+private import _TestingInternals
+
+@_spi(ForToolsIntegrationOnly)
+extension ABIv0 {
+  /// The type of the entry point to the testing library used by tools that want
+  /// to remain version-agnostic regarding the testing library.
+  ///
+  /// - Parameters:
+  ///   - configurationJSON: A buffer to memory representing the test
+  ///     configuration and options. If `nil`, a new instance is synthesized
+  ///     from the command-line arguments to the current process.
+  ///   - recordHandler: A JSON record handler to which is passed a buffer to
+  ///     memory representing each record as described in `ABI/JSON.md`.
+  ///
+  /// - Returns: Whether or not the test run finished successfully.
+  ///
+  /// - Throws: Any error that occurred prior to running tests. Errors that are
+  ///   thrown while tests are running are handled by the testing library.
+  public typealias EntryPoint = @convention(thin) @Sendable (
+    _ configurationJSON: UnsafeRawBufferPointer?,
+    _ recordHandler: @escaping @Sendable (_ recordJSON: UnsafeRawBufferPointer) -> Void
+  ) async throws -> Bool
+
+  /// The entry point to the testing library used by tools that want to remain
+  /// version-agnostic regarding the testing library.
+  ///
+  /// The value of this property is a Swift function that can be used by tools
+  /// that do not link directly to the testing library and wish to invoke tests
+  /// in a binary that has been loaded into the current process. The value of
+  /// this property is accessible from C and C++ as a function with name
+  /// `"swt_abiv0_getEntryPoint"` and can be dynamically looked up at runtime
+  /// using `dlsym()` or a platform equivalent.
+  ///
+  /// The value of this property can be thought of as equivalent to
+  /// `swift test --event-stream-output` except that, instead of streaming JSON
+  /// records to a named pipe or file, it streams them to an in-process
+  /// callback.
+  public static var entryPoint: EntryPoint {
+    return { configurationJSON, recordHandler in
+      let args = try configurationJSON.map { configurationJSON in
+        try JSON.decode(__CommandLineArguments_v0.self, from: configurationJSON)
+      }
+
+      let eventHandler = try eventHandlerForStreamingEvents(version: args?.eventStreamVersion, forwardingTo: recordHandler)
+      let exitCode = await Testing.entryPoint(passing: args, eventHandler: eventHandler)
+      return exitCode == EXIT_SUCCESS
+    }
+  }
+}
+
+/// An exported C function that is the equivalent of
+/// ``ABIv0/entryPoint-swift.type.property``.
+///
+/// - Returns: The value of ``ABIv0/entryPoint-swift.type.property`` cast to an
+///   untyped pointer.
+@_cdecl("swt_abiv0_getEntryPoint")
+@usableFromInline func abiv0_getEntryPoint() -> UnsafeRawPointer {
+  unsafeBitCast(ABIv0.entryPoint, to: UnsafeRawPointer.self)
+}
+#endif

Sources/Testing/EntryPoints/ABIv0/ABIv0.EntryPoint.swift

@@ -15,7 +15,7 @@ extension ABIv0.Record {
   ///
   /// - Parameters:
   ///   - eventHandler: The event handler to forward events to. See
-  ///     ``ABIv0/EntryPoint`` for more information.
+  ///     ``ABIv0/EntryPoint-swift.typealias`` for more information.
   ///
   /// - Returns: An event handler.
   ///
@@ -74,7 +74,7 @@ extension EventAndContextSnapshot: Codable {}
 ///
 /// - Parameters:
 ///   - eventHandler: The event handler to forward events to. See
-///     ``ABIEntryPoint_v0`` for more information.
+///     ``ABIv0/EntryPoint-swift.typealias`` for more information.
 ///
 /// - Returns: An event handler.
 ///

Sources/Testing/EntryPoints/ABIv0/ABIv0.Record+Streaming.swift

@@ -9,4 +9,5 @@
 //
 
 /// A namespace for ABI version 0 symbols.
-enum ABIv0: Sendable {}
+@_spi(ForToolsIntegrationOnly)
+public enum ABIv0: Sendable {}

Sources/Testing/EntryPoints/ABIv0/ABIv0.swift

@@ -25,8 +25,8 @@ private import _TestingInternals
 ///     to this function.
 ///
 /// External callers cannot call this function directly. The can use
-/// ``copyABIEntryPoint_v0()`` to get a reference to an ABI-stable version of
-/// this function.
+/// ``ABIv0/entryPoint-swift.type.property`` to get a reference to an ABI-stable
+/// version of this function.
 func entryPoint(passing args: __CommandLineArguments_v0?, eventHandler: Event.Handler?) async -> CInt {
   let exitCode = Locked(rawValue: EXIT_SUCCESS)
 
@@ -200,7 +200,7 @@ public struct __CommandLineArguments_v0: Sendable {
   /// The value of the `--xunit-output` argument.
   public var xunitOutput: String?
 
-  /// The value of the `--experimental-event-stream-output` argument.
+  /// The value of the `--event-stream-output` argument.
   ///
   /// Data is written to this file in the [JSON Lines](https://jsonlines.org)
   /// text format. For each event handled by the resulting event handler, a JSON
@@ -215,18 +215,18 @@ public struct __CommandLineArguments_v0: Sendable {
   ///
   /// The file is closed when this process terminates or the test run completes,
   /// whichever occurs first.
-  public var experimentalEventStreamOutput: String?
+  public var eventStreamOutput: String?
 
   /// The version of the event stream schema to use when writing events to
-  /// ``experimentalEventStreamOutput``.
+  /// ``eventStreamOutput``.
   ///
   /// If the value of this property is `nil`, events are encoded verbatim (using
   /// ``Event/Snapshot``.) Otherwise, the corresponding stable schema is used
   /// (e.g. ``ABIv0/Record`` for `0`.)
   ///
   /// - Warning: The behavior of this property will change when the ABI version
   ///   0 JSON schema is finalized.
-  public var experimentalEventStreamVersion: Int?
+  public var eventStreamVersion: Int?
 
   /// The value(s) of the `--filter` argument.
   public var filter: [String]?
@@ -252,8 +252,8 @@ extension __CommandLineArguments_v0: Codable {
     case quiet
     case _verbosity = "verbosity"
     case xunitOutput
-    case experimentalEventStreamOutput
-    case experimentalEventStreamVersion
+    case eventStreamOutput
+    case eventStreamVersion
     case filter
     case skip
     case repetitions
@@ -288,7 +288,8 @@ func parseCommandLineArguments(from args: [String]) throws -> __CommandLineArgum
   // NOTE: While the output event stream is opened later, it is necessary to
   // open the configuration file early (here) in order to correctly construct
   // the resulting __CommandLineArguments_v0 instance.
-  if let configurationIndex = args.firstIndex(of: "--experimental-configuration-path"), !isLastArgument(at: configurationIndex) {
+  if let configurationIndex = args.firstIndex(of: "--configuration-path") ?? args.firstIndex(of: "--experimental-configuration-path"),
+     !isLastArgument(at: configurationIndex) {
     let path = args[args.index(after: configurationIndex)]
     let file = try FileHandle(forReadingAtPath: path)
     let configurationJSON = try file.readToEnd()
@@ -302,12 +303,14 @@ func parseCommandLineArguments(from args: [String]) throws -> __CommandLineArgum
   }
 
   // Event stream output (experimental)
-  if let eventOutputIndex = args.firstIndex(of: "--experimental-event-stream-output"), !isLastArgument(at: eventOutputIndex) {
-    result.experimentalEventStreamOutput = args[args.index(after: eventOutputIndex)]
+  if let eventOutputIndex = args.firstIndex(of: "--event-stream-output") ?? args.firstIndex(of: "--experimental-event-stream-output"),
+     !isLastArgument(at: eventOutputIndex) {
+    result.eventStreamOutput = args[args.index(after: eventOutputIndex)]
   }
   // Event stream output (experimental)
-  if let eventOutputVersionIndex = args.firstIndex(of: "--experimental-event-stream-version"), !isLastArgument(at: eventOutputVersionIndex) {
-    result.experimentalEventStreamVersion = Int(args[args.index(after: eventOutputVersionIndex)])
+  if let eventOutputVersionIndex = args.firstIndex(of: "--event-stream-version") ?? args.firstIndex(of: "--experimental-event-stream-version"),
+     !isLastArgument(at: eventOutputVersionIndex) {
+    result.eventStreamVersion = Int(args[args.index(after: eventOutputVersionIndex)])
   }
 #endif
 
@@ -404,9 +407,9 @@ public func configurationForEntryPoint(from args: __CommandLineArguments_v0) thr
 
 #if canImport(Foundation)
   // Event stream output (experimental)
-  if let eventStreamOutputPath = args.experimentalEventStreamOutput {
+  if let eventStreamOutputPath = args.eventStreamOutput {
     let file = try FileHandle(forWritingAtPath: eventStreamOutputPath)
-    let eventHandler = try eventHandlerForStreamingEvents(version: args.experimentalEventStreamVersion) { json in
+    let eventHandler = try eventHandlerForStreamingEvents(version: args.eventStreamVersion) { json in
       try? _writeJSONLine(json, to: file)
     }
     configuration.eventHandler = { [oldEventHandler = configuration.eventHandler] event, context in
@@ -487,7 +490,7 @@ func eventHandlerForStreamingEvents(version: Int?, forwardingTo eventHandler: @e
   case 0:
     ABIv0.Record.eventHandler(forwardingTo: eventHandler)
   case let .some(unsupportedVersion):
-    throw _EntryPointError.invalidArgument("--experimental-event-stream-version", value: "\(unsupportedVersion)")
+    throw _EntryPointError.invalidArgument("--event-stream-version", value: "\(unsupportedVersion)")
   }
 }