Return workspace tests in a hierarchical format

This ways the client doesn’t need to create a hierarchical structure using the container names. It is also more flexible and allows nesting of test suites + the addition of labels and tags for swift-testing.

The data structure for `TestItem` has been heavily inspired by VS Code’s `TestItem` for the test explorer, which should make it fairly straightforward to integrate these results into the VS Code test explorer.

Author: ahoppen

Sources/LanguageServerProtocol/CMakeLists.txt

@@ -124,6 +124,7 @@ add_library(LanguageServerProtocol STATIC
   SupportTypes/SKCompletionOptions.swift
   SupportTypes/StringOrMarkupContent.swift
   SupportTypes/SymbolKind.swift
+  SupportTypes/TestItem.swift
   SupportTypes/TextDocumentContentChangeEvent.swift
   SupportTypes/TextDocumentEdit.swift
   SupportTypes/TextDocumentIdentifier.swift

Sources/LanguageServerProtocol/Requests/WorkspaceTestsRequest.swift

@@ -15,7 +15,7 @@
 /// **(LSP Extension)**
 public struct WorkspaceTestsRequest: RequestType, Hashable {
   public static let method: String = "workspace/tests"
-  public typealias Response = [WorkspaceSymbolItem]?
+  public typealias Response = [TestItem]
 
   public init() {}
 }

Sources/LanguageServerProtocol/SupportTypes/TestItem.swift

@@ -0,0 +1,67 @@
+//===----------------------------------------------------------------------===//
+//
+// This source file is part of the Swift.org open source project
+//
+// Copyright (c) 2014 - 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 the list of Swift project authors
+//
+//===----------------------------------------------------------------------===//
+
+public struct TestTag: Codable, Equatable, Sendable {
+  /// ID of the test tag. `TestTag` instances with the same ID are considered to be identical.
+  public let id: String
+
+  public init(id: String) {
+    self.id = id
+  }
+}
+
+/// A test item that can be shown an a client's test explorer or used to identify tests alongside a source file.
+///
+/// A `TestItem` can represent either a test suite or a test itself, since they both have similar capabilities.
+public struct TestItem: ResponseType, Equatable {
+  /// Identifier for the `TestItem`.
+  ///
+  /// This identifier uniquely identifies the test case or test suite. It can be used to run an individual test (suite).
+  public let id: String
+
+  /// Display name describing the test.
+  public let label: String
+
+  /// Optional description that appears next to the label.
+  public let description: String?
+
+  /// A string that should be used when comparing this item with other items.
+  /// When `nil` the `label` is used.
+  public let sortText: String?
+
+  /// The location of the test item in the source code.
+  public let location: Location
+
+  /// The children of this test item. For a test suite, this may contain the individual test cases or nested suites.
+  public let children: [TestItem]
+
+  /// Tags associated with this test item.
+  public let tags: [TestTag]
+
+  public init(
+    id: String,
+    label: String,
+    description: String? = nil,
+    sortText: String? = nil,
+    location: Location,
+    children: [TestItem],
+    tags: [TestTag]
+  ) {
+    self.id = id
+    self.label = label
+    self.description = description
+    self.sortText = sortText
+    self.location = location
+    self.children = children
+    self.tags = tags
+  }
+}

Sources/SourceKitLSP/SourceKitLSPServer.swift

@@ -1317,7 +1317,7 @@ extension SourceKitLSPServer {
       semanticTokensProvider: semanticTokensOptions,
       inlayHintProvider: inlayHintOptions,
       experimental: .dictionary([
-        "workspace/tests": .dictionary(["version": .int(1)]),
+        "workspace/tests": .dictionary(["version": .int(2)]),
         "textDocument/tests": .dictionary(["version": .int(1)]),
       ])
     )

Sources/SourceKitLSP/TestDiscovery.swift

@@ -34,15 +34,65 @@ fileprivate extension SymbolOccurrence {
 }
 
 extension SourceKitLSPServer {
-  func workspaceTests(_ req: WorkspaceTestsRequest) async throws -> [WorkspaceSymbolItem]? {
-    let testSymbols = workspaces.flatMap { (workspace) -> [SymbolOccurrence] in
+  func workspaceTests(_ req: WorkspaceTestsRequest) async throws -> [TestItem] {
+    // Gather all tests classes and test methods.
+    let testSymbolOccurrences = workspaces.flatMap { (workspace) -> [SymbolOccurrence] in
       return workspace.index?.unitTests() ?? []
     }
-    return
-      testSymbols
-      .filter { $0.canBeTestDefinition }
+
+    // Arrange tests by the USR they are contained in. This allows us to emit test methods as children of test classes.
+    // `occurrencesByParent[nil]` are the root test symbols that aren't a child of another test symbol.
+    var occurrencesByParent: [String?: [SymbolOccurrence]] = [:]
+
+    let testSymbolUsrs = Set(testSymbolOccurrences.map(\.symbol.usr))
+
+    for testSymbolOccurrence in testSymbolOccurrences {
+      let childOfUsrs = testSymbolOccurrence.relations
+        .filter { $0.roles.contains(.childOf) }
+        .map(\.symbol.usr)
+        .filter { testSymbolUsrs.contains($0) }
+      if childOfUsrs.count > 1 {
+        logger.fault(
+          "Test symbol \(testSymbolOccurrence.symbol.usr) is child or multiple symbols: \(childOfUsrs.joined(separator: ", "))"
+        )
+      }
+      occurrencesByParent[childOfUsrs.sorted().first, default: []].append(testSymbolOccurrence)
+    }
+
+    /// Returns a test item for the given `testSymbolOccurrence`.
+    ///
+    /// Also includes test items for all tests that are children of this test.
+    ///
+    /// `context` is used to build the test's ID. It is an array containing the names of all parent symbols. These will
+    /// be joined with the test symbol's name using `/` to form the test ID. The test ID can be used to run an
+    /// individual test.
+    func testItem(for testSymbolOccurrence: SymbolOccurrence, context: [String]) -> TestItem {
+      let symbolPosition = Position(
+        line: testSymbolOccurrence.location.line - 1,  // 1-based -> 0-based
+        // FIXME: we need to convert the utf8/utf16 column, which may require reading the file!
+        utf16index: testSymbolOccurrence.location.utf8Column - 1
+      )
+
+      let symbolLocation = Location(
+        uri: DocumentURI(URL(fileURLWithPath: testSymbolOccurrence.location.path)),
+        range: Range(symbolPosition)
+      )
+      let children =
+        occurrencesByParent[testSymbolOccurrence.symbol.usr, default: []]
+        .sorted()
+        .map { testItem(for: $0, context: context + [testSymbolOccurrence.symbol.name]) }
+      return TestItem(
+        id: (context + [testSymbolOccurrence.symbol.name]).joined(separator: "/"),
+        label: testSymbolOccurrence.symbol.name,
+        location: symbolLocation,
+        children: children,
+        tags: []
+      )
+    }
+
+    return occurrencesByParent[nil, default: []]
       .sorted()
-      .map(WorkspaceSymbolItem.init)
+      .map { testItem(for: $0, context: []) }
   }
 
   func documentTests(

Tests/SourceKitLSPTests/TestDiscoveryTests.swift

@@ -47,27 +47,27 @@ final class TestDiscoveryTests: XCTestCase {
     XCTAssertEqual(
       tests,
       [
-        WorkspaceSymbolItem.symbolInformation(
-          SymbolInformation(
-            name: "MyTests",
-            kind: .class,
-            location: Location(
-              uri: try project.uri(for: "MyTests.swift"),
-              range: Range(try project.position(of: "1️⃣", in: "MyTests.swift"))
+        TestItem(
+          id: "MyTests",
+          label: "MyTests",
+          location: Location(
+            uri: try project.uri(for: "MyTests.swift"),
+            range: Range(try project.position(of: "1️⃣", in: "MyTests.swift"))
+          ),
+          children: [
+            TestItem(
+              id: "MyTests/testMyLibrary()",
+              label: "testMyLibrary()",
+              location: Location(
+                uri: try project.uri(for: "MyTests.swift"),
+                range: Range(try project.position(of: "2️⃣", in: "MyTests.swift"))
+              ),
+              children: [],
+              tags: []
             )
-          )
-        ),
-        WorkspaceSymbolItem.symbolInformation(
-          SymbolInformation(
-            name: "testMyLibrary()",
-            kind: .method,
-            location: Location(
-              uri: try project.uri(for: "MyTests.swift"),
-              range: Range(try project.position(of: "2️⃣", in: "MyTests.swift"))
-            ),
-            containerName: "MyTests"
-          )
-        ),
+          ],
+          tags: []
+        )
       ]
     )
   }