Change argument name and clarify what happens if you don't specify an event stream version

Author: grynspan

Documentation/ABI/JSON.md

@@ -11,8 +11,8 @@ 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 `--event-stream-output` command-line argument. For more
-information about the ABI entry point, see the documentation for
+entry point and for the `--event-stream-output-path` 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
@@ -99,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 `--event-stream-output` to the test executable created by
-`swift build --build-tests`.
+accessed by passing `--event-stream-output-path` 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

@@ -201,7 +201,7 @@ Package Manager:
 | Argument | Value Type | Description |
 |---|:-:|---|
 | `--configuration-path` | File system path | Specifies a path to a file, named pipe, etc. containing test configuration/options. |
-| `--event-stream-output` | File system path | Specifies a path to a file, named pipe, etc. to which output should be written. |
+| `--event-stream-output-path` | File system path | Specifies a path to a file, named pipe, etc. to which output should be written. |
 | `--event-stream-version` | Integer | Specifies the version of the stable JSON schema to use for output. |
 
 The process for adding arguments to Swift Package Manager is separate from the
@@ -210,24 +210,29 @@ speculative and are subject to change as part of the Swift Package Manager
 review process.
 
 If `--configuration-path` is specified, Swift Testing will open it for reading
-and attempt to decode its contents as JSON. If `--event-stream-output` is
+and attempt to decode its contents as JSON. If `--event-stream-output-path` is
 specified, Swift Testing will open it for writing and will write a sequence of
 [JSON Lines](https://jsonlines.org) to it representing the data and events
 produced by the test run. `--event-stream-version` determines the stable schema
 used for output; pass `0` to match the schema proposed in this document.
 
 > [!NOTE]
-> If `--event-stream-output` is specified but `--event-stream-version` is not,
-> the format _currently_ used is based on direct JSON encodings of the internal
-> Swift structures used by Swift Testing. This format is necessary to support
-> Xcode 16 Beta 1. In the future, the default value of this argument will be
-> assumed to be `0` instead (i.e. the JSON schema will match what we are
-> proposing here.)
+> If `--event-stream-output-path` is specified but `--event-stream-version` is
+> not, the format _currently_ used is based on direct JSON encodings of the
+> internal Swift structures used by Swift Testing. This format is necessary to
+> support Xcode 16 Beta 1. In the future, the default value of this argument
+> will be assumed to equal the newest available JSON schema version (`0` as of
+> this document's acceptance, i.e. the JSON schema will match what we are
+> proposing here until a new schema supersedes it.)
+>
+> Tools authors that rely on the JSON schema are strongly advised to specify a
+> version rather than relying on this behavior to avoid breaking changes in the
+> future.
 
 On platforms that support them, callers can use a named pipe with
-`--event-stream-output` to get live results back from the test run rather than
-needing to wait until the file is closed by the test process. Named pipes can be
-created on Darwin or Linux with the POSIX [`mkfifo()`](https://developer.apple.com/library/archive/documentation/System/Conceptual/ManPages_iPhoneOS/man2/mkfifo.2.html)
+`--event-stream-output-path` to get live results back from the test run rather
+than needing to wait until the file is closed by the test process. Named pipes
+can be created on Darwin or Linux with the POSIX [`mkfifo()`](https://developer.apple.com/library/archive/documentation/System/Conceptual/ManPages_iPhoneOS/man2/mkfifo.2.html)
 function or on Windows with the [`CreateNamedPipe()`](https://learn.microsoft.com/en-us/windows/win32/api/namedpipeapi/nf-namedpipeapi-createnamedpipew)
 function.
 
@@ -278,8 +283,8 @@ public enum ABIv0 {
   /// 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
+  /// `swift test --event-stream-output-path` 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 { get }
 }

Sources/Testing/ABI/EntryPoints/ABIEntryPoint.swift

@@ -42,8 +42,8 @@ extension ABIv0 {
   /// using `dlsym()` or a platform equivalent.
   ///
   /// The value of this property can be thought of as equivalent to a call 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
+  /// `swift test --event-stream-output-path` 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

Sources/Testing/ABI/EntryPoints/EntryPoint.swift

@@ -200,7 +200,7 @@ public struct __CommandLineArguments_v0: Sendable {
   /// The value of the `--xunit-output` argument.
   public var xunitOutput: String?
 
-  /// The value of the `--event-stream-output` argument.
+  /// The value of the `--event-stream-output-path` 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,7 +215,7 @@ public struct __CommandLineArguments_v0: Sendable {
   ///
   /// The file is closed when this process terminates or the test run completes,
   /// whichever occurs first.
-  public var eventStreamOutput: String?
+  public var eventStreamOutputPath: String?
 
   /// The version of the event stream schema to use when writing events to
   /// ``eventStreamOutput``.
@@ -252,7 +252,7 @@ extension __CommandLineArguments_v0: Codable {
     case quiet
     case _verbosity = "verbosity"
     case xunitOutput
-    case eventStreamOutput
+    case eventStreamOutputPath
     case eventStreamVersion
     case filter
     case skip
@@ -303,9 +303,9 @@ func parseCommandLineArguments(from args: [String]) throws -> __CommandLineArgum
   }
 
   // Event stream output (experimental)
-  if let eventOutputIndex = args.firstIndex(of: "--event-stream-output") ?? args.firstIndex(of: "--experimental-event-stream-output"),
+  if let eventOutputIndex = args.firstIndex(of: "--event-stream-output-path") ?? args.firstIndex(of: "--experimental-event-stream-output"),
      !isLastArgument(at: eventOutputIndex) {
-    result.eventStreamOutput = args[args.index(after: eventOutputIndex)]
+    result.eventStreamOutputPath = args[args.index(after: eventOutputIndex)]
   }
   // Event stream output (experimental)
   if let eventOutputVersionIndex = args.firstIndex(of: "--event-stream-version") ?? args.firstIndex(of: "--experimental-event-stream-version"),
@@ -407,7 +407,7 @@ public func configurationForEntryPoint(from args: __CommandLineArguments_v0) thr
 
 #if canImport(Foundation)
   // Event stream output (experimental)
-  if let eventStreamOutputPath = args.eventStreamOutput {
+  if let eventStreamOutputPath = args.eventStreamOutputPath {
     let file = try FileHandle(forWritingAtPath: eventStreamOutputPath)
     let eventHandler = try eventHandlerForStreamingEvents(version: args.eventStreamVersion) { json in
       try? _writeJSONLine(json, to: file)

Tests/TestingTests/SwiftPMTests.swift

@@ -207,9 +207,9 @@ struct SwiftPMTests {
       }
   }
 
-  @Test("--event-stream-output argument (writes to a stream and can be read back)",
+  @Test("--event-stream-output-path argument (writes to a stream and can be read back)",
         arguments: [
-          ("--event-stream-output", "--event-stream-version", "0"),
+          ("--event-stream-output-path", "--event-stream-version", "0"),
           ("--experimental-event-stream-output", "--experimental-event-stream-version", "0"),
         ])
   func eventStreamOutput(outputArgumentName: String, versionArgumentName: String, version: String) async throws {