Add LLDB debugger support to swift-test command

Introduces interactive debugging capabilities to `swift test` via a
`--debugger` flag enabling developers to failing tests directly within LLDB.

This adds debugging parity with `swift run --debugger` which allows users
to debug their executables directly.

When launching lldb this implenentation uses `execv()` to replace the
`swift-test` process with LLDB. This approach avoids process hierarchy
complications and ensures LLDB has full terminal control for interactive
debugging features.

When there is only one type of tests the debugger creates a single LLDB
target configured specifically for that framework. For XCTest, this means
targeting the test bundle with xctest as the executable, while Swift Testing
targets the test binary directly with appropriate command-line arguments.

When both testing frameworks have tests available we create multiple LLDB
targets within a single debugging session. A Python script automatically switches
targets as the executable exits, which lets users debug both types of tests
spread across two executables in the same session. The Python script also
maintains breakpoint persistence across target switches, allowing you to set
a breakpoint for either test type no matter the active target.

Finally, we add a `failbreak` command alias that sets breakpoint(s) that break
on test failure, allowing users to automatically stop on failed tests.

Issue: #8129

Author: plemarquand

Fixtures/Miscellaneous/TestDebugging/Package.swift

@@ -0,0 +1,10 @@
+// swift-tools-version: 6.0
+import PackageDescription
+
+let package = Package(
+    name: "TestDebugging",
+    targets: [
+        .target(name: "TestDebugging"),
+        .testTarget(name: "TestDebuggingTests", dependencies: ["TestDebugging"]),
+    ]
+)

Fixtures/Miscellaneous/TestDebugging/Sources/TestDebugging/TestDebugging.swift

@@ -0,0 +1,23 @@
+public struct Calculator {
+    public init() {}
+
+    public func add(_ a: Int, _ b: Int) -> Int {
+        return a + b
+    }
+
+    public func subtract(_ a: Int, _ b: Int) -> Int {
+        return a - b
+    }
+
+    public func multiply(_ a: Int, _ b: Int) -> Int {
+        return a * b
+    }
+
+    public func divide(_ a: Int, _ b: Int) -> Int {
+        return a / b
+    }
+
+    public func purposelyFail() -> Bool {
+        return false
+    }
+}

Fixtures/Miscellaneous/TestDebugging/Tests/TestDebuggingTests/TestDebuggingTests.swift

@@ -0,0 +1,34 @@
+import XCTest
+import Testing
+@testable import TestDebugging
+
+// MARK: - XCTest Suite
+final class XCTestCalculatorTests: XCTestCase {
+
+    func testAdditionPasses() {
+        let calculator = Calculator()
+        let result = calculator.add(2, 3)
+        XCTAssertEqual(result, 5, "Addition should return 5 for 2 + 3")
+    }
+
+    func testSubtractionFails() {
+        let calculator = Calculator()
+        let result = calculator.subtract(5, 3)
+        XCTAssertEqual(result, 3, "This test is designed to fail - subtraction 5 - 3 should equal 2, not 3")
+    }
+}
+
+// MARK: - Swift Testing Suite
+@Test("Calculator Addition Works Correctly")
+func calculatorAdditionPasses() {
+    let calculator = Calculator()
+    let result = calculator.add(4, 6)
+    #expect(result == 10, "Addition should return 10 for 4 + 6")
+}
+
+@Test("Calculator Boolean Check Fails")
+func calculatorBooleanFails() {
+    let calculator = Calculator()
+    let result = calculator.purposelyFail()
+    #expect(result == true, "This test is designed to fail - purposelyFail() should return false, not true")
+}

Sources/Commands/SwiftTestCommand.swift

@@ -216,6 +216,11 @@ struct TestCommandOptions: ParsableArguments {
           help: "Enable code coverage.")
     var enableCodeCoverage: Bool = false
 
+    /// Launch tests under LLDB debugger.
+    @Flag(name: .customLong("debugger"),
+          help: "Launch tests under LLDB debugger.")
+    var shouldLaunchInLLDB: Bool = false
+
     /// Configure test output.
     @Option(help: ArgumentHelp("", visibility: .hidden))
     public var testOutput: TestOutput = .default
@@ -280,8 +285,17 @@ public struct SwiftTestCommand: AsyncSwiftCommand {
 
         var results = [TestRunner.Result]()
 
+        if options.shouldLaunchInLLDB {
+            let result = try await runTestProductsWithLLDB(
+                testProducts,
+                productsBuildParameters: buildParameters,
+                swiftCommandState: swiftCommandState
+            )
+            results.append(result)
+        }
+
         // Run XCTest.
-        if options.testLibraryOptions.isEnabled(.xctest, swiftCommandState: swiftCommandState) {
+        if !options.shouldLaunchInLLDB && options.testLibraryOptions.isEnabled(.xctest, swiftCommandState: swiftCommandState) {
             // Validate XCTest is available on Darwin-based systems. If it's not available and we're hitting this code
             // path, that means the developer must have explicitly passed --enable-xctest (or the toolchain is
             // corrupt, I suppose.)
@@ -351,7 +365,7 @@ public struct SwiftTestCommand: AsyncSwiftCommand {
         }
 
         // Run Swift Testing (parallel or not, it has a single entry point.)
-        if options.testLibraryOptions.isEnabled(.swiftTesting, swiftCommandState: swiftCommandState) {
+        if !options.shouldLaunchInLLDB && options.testLibraryOptions.isEnabled(.swiftTesting, swiftCommandState: swiftCommandState) {
             lazy var testEntryPointPath = testProducts.lazy.compactMap(\.testEntryPointPath).first
             if options.testLibraryOptions.isExplicitlyEnabled(.swiftTesting, swiftCommandState: swiftCommandState) || testEntryPointPath == nil {
                 results.append(
@@ -474,27 +488,200 @@ public struct SwiftTestCommand: AsyncSwiftCommand {
         }
     }
 
+    /// Runs test products under LLDB debugger for interactive debugging.
+    ///
+    /// This method handles debugging for enabled testing libraries:
+    /// 1. If both XCTest and Swift Testing are enabled, prompts user to choose or runs both in separate sessions
+    /// 2. Validates that exactly one test product is available for debugging
+    /// 3. Creates a DebugTestRunner and launches LLDB with the test binary
+    ///
+    /// - Parameters:
+    ///   - testProducts: The built test products
+    ///   - productsBuildParameters: Build parameters for the products
+    ///   - swiftCommandState: The Swift command state
+    /// - Returns: The test result (typically .success since LLDB takes over)
+    private func runTestProductsWithLLDB(
+        _ testProducts: [BuiltTestProduct],
+        productsBuildParameters: BuildParameters,
+        swiftCommandState: SwiftCommandState
+    ) async throws -> TestRunner.Result {
+        // Validate that we have exactly one test product for debugging
+        guard testProducts.count == 1 else {
+            if testProducts.isEmpty {
+                throw StringError("No test products found for debugging")
+            } else {
+                let productNames = testProducts.map { $0.productName }.joined(separator: ", ")
+                throw StringError("Multiple test products found (\(productNames)). Specify a single target with --filter when using --debugger")
+            }
+        }
+
+        let testProduct = testProducts[0]
+        let toolchain = try swiftCommandState.getTargetToolchain()
+
+        // Determine which testing libraries are enabled
+        let xctestEnabled = options.testLibraryOptions.isEnabled(.xctest, swiftCommandState: swiftCommandState)
+        let swiftTestingEnabled = options.testLibraryOptions.isEnabled(.swiftTesting, swiftCommandState: swiftCommandState) &&
+                                 (options.testLibraryOptions.isExplicitlyEnabled(.swiftTesting, swiftCommandState: swiftCommandState) ||
+                                  testProduct.testEntryPointPath == nil)
+
+        // Create a list of testing libraries to run in sequence, checking for actual tests
+        var librariesToRun: [TestingLibrary] = []
+        var skippedLibraries: [(TestingLibrary, String)] = []
+
+        // Only add XCTest if it's enabled AND has tests to run
+        if xctestEnabled {
+            // Always check for XCTest tests by getting test suites
+            let testSuites = try TestingSupport.getTestSuites(
+                in: testProducts,
+                swiftCommandState: swiftCommandState,
+                enableCodeCoverage: options.enableCodeCoverage,
+                shouldSkipBuilding: options.sharedOptions.shouldSkipBuilding,
+                experimentalTestOutput: options.enableExperimentalTestOutput,
+                sanitizers: globalOptions.build.sanitizers
+            )
+            let filteredTests = try testSuites
+                .filteredTests(specifier: options.testCaseSpecifier)
+                .skippedTests(specifier: options.skippedTests(fileSystem: swiftCommandState.fileSystem))
+
+            if !filteredTests.isEmpty {
+                librariesToRun.append(.xctest)
+            } else {
+                skippedLibraries.append((.xctest, "no XCTest tests found"))
+            }
+        }
+
+        if swiftTestingEnabled {
+            librariesToRun.append(.swiftTesting)
+        }
+
+        // Ensure we have at least one library to run
+        guard !librariesToRun.isEmpty else {
+            if !skippedLibraries.isEmpty {
+                let skippedMessages = skippedLibraries.map { library, reason in
+                    let libraryName = library == .xctest ? "XCTest" : "Swift Testing"
+                    return "\(libraryName): \(reason)"
+                }
+                throw StringError("No testing libraries have tests to debug. Skipped: \(skippedMessages.joined(separator: ", "))")
+            }
+            throw StringError("No testing libraries are enabled for debugging")
+        }
+
+        try await runTestLibrariesWithLLDB(
+            testProduct: testProduct,
+            target: DebuggableTestSession(
+                targets: librariesToRun.map {
+                    DebuggableTestSession.Target(
+                        library: $0,
+                        additionalArgs: try additionalLLDBArguments(for: $0, testProducts: testProducts, swiftCommandState: swiftCommandState),
+                        bundlePath: testBundlePath(for: $0, testProduct: testProduct)
+                    )
+                }
+            ),
+            testProducts: testProducts,
+            productsBuildParameters: productsBuildParameters,
+            swiftCommandState: swiftCommandState,
+            toolchain: toolchain
+        )
+
+        // Clean up Python script file after all sessions complete
+        // (Breakpoint file cleanup is handled by DebugTestRunner based on SessionState)
+        if librariesToRun.count > 1 {
+            let tempDir = try swiftCommandState.fileSystem.tempDirectory
+            let pythonScriptFile = tempDir.appending("save_breakpoints.py")
+
+            if swiftCommandState.fileSystem.exists(pythonScriptFile) {
+                try? swiftCommandState.fileSystem.removeFileTree(pythonScriptFile)
+            }
+        }
+
+        return .success
+    }
+
+    private func additionalLLDBArguments(for library: TestingLibrary, testProducts: [BuiltTestProduct], swiftCommandState: SwiftCommandState) throws -> [String] {
+        // Determine test binary path and arguments based on the testing library
+        switch library {
+        case .xctest:
+            let (xctestArgs, _) = try xctestArgs(for: testProducts, swiftCommandState: swiftCommandState)
+            return xctestArgs
+
+        case .swiftTesting:
+            let commandLineArguments = CommandLine.arguments.dropFirst()
+            var swiftTestingArgs = ["--testing-library", "swift-testing", "--enable-swift-testing"]
+
+            if let separatorIndex = commandLineArguments.firstIndex(of: "--") {
+                // Only pass arguments after the "--" separator
+                swiftTestingArgs += Array(commandLineArguments.dropFirst(separatorIndex + 1))
+            }
+            return  swiftTestingArgs
+        }
+    }
+
+    private func testBundlePath(for library: TestingLibrary, testProduct: BuiltTestProduct) -> AbsolutePath {
+        switch library {
+        case .xctest:
+            testProduct.bundlePath
+        case .swiftTesting:
+            testProduct.binaryPath
+        }
+    }
+
+    /// Runs a single testing library under LLDB debugger.
+    ///
+    /// - Parameters:
+    ///   - testProduct: The test product to debug
+    ///   - library: The testing library to run
+    ///   - testProducts: All built test products (for XCTest args generation)
+    ///   - productsBuildParameters: Build parameters for the products
+    ///   - swiftCommandState: The Swift command state
+    ///   - toolchain: The toolchain to use
+    ///   - sessionState: The debugging session state for breakpoint persistence
+    private func runTestLibrariesWithLLDB(
+        testProduct: BuiltTestProduct,
+        target: DebuggableTestSession,
+        testProducts: [BuiltTestProduct],
+        productsBuildParameters: BuildParameters,
+        swiftCommandState: SwiftCommandState,
+        toolchain: UserToolchain
+    ) async throws {
+        // Create and launch the debug test runner
+        let debugRunner = DebugTestRunner(
+            target: target,
+            buildParameters: productsBuildParameters,
+            toolchain: toolchain,
+            testEnv: try TestingSupport.constructTestEnvironment(
+                toolchain: toolchain,
+                destinationBuildParameters: productsBuildParameters,
+                sanitizers: globalOptions.build.sanitizers,
+                library: .xctest // TODO
+            ),
+            cancellator: swiftCommandState.cancellator,
+            fileSystem: swiftCommandState.fileSystem,
+            observabilityScope: swiftCommandState.observabilityScope,
+            verbose: globalOptions.logging.verbose
+        )
+
+        // Launch LLDB using AsyncProcess with proper input/output forwarding
+        try debugRunner.run()
+    }
+
     private func runTestProducts(
         _ testProducts: [BuiltTestProduct],
         additionalArguments: [String],
         productsBuildParameters: BuildParameters,
         swiftCommandState: SwiftCommandState,
         library: TestingLibrary
     ) async throws -> TestRunner.Result {
-        // Pass through all arguments from the command line to Swift Testing.
+        // Pass through arguments that come after "--" to Swift Testing.
         var additionalArguments = additionalArguments
         if library == .swiftTesting {
-            // Reconstruct the arguments list. If an xUnit path was specified, remove it.
-            var commandLineArguments = [String]()
-            var originalCommandLineArguments = CommandLine.arguments.dropFirst().makeIterator()
-            while let arg = originalCommandLineArguments.next() {
-                if arg == "--xunit-output" {
-                    _ = originalCommandLineArguments.next()
-                } else {
-                    commandLineArguments.append(arg)
-                }
+            // Only pass arguments that come after the "--" separator to Swift Testing
+            let allCommandLineArguments = CommandLine.arguments.dropFirst()
+
+            if let separatorIndex = allCommandLineArguments.firstIndex(of: "--") {
+                // Only pass arguments after the "--" separator
+                let testArguments = Array(allCommandLineArguments.dropFirst(separatorIndex + 1))
+                additionalArguments += testArguments
             }
-            additionalArguments += commandLineArguments
 
             if var xunitPath = options.xUnitOutput {
                 if options.testLibraryOptions.isEnabled(.xctest, swiftCommandState: swiftCommandState) {
@@ -667,6 +854,11 @@ public struct SwiftTestCommand: AsyncSwiftCommand {
     ///
     /// - Throws: if a command argument is invalid
     private func validateArguments(swiftCommandState: SwiftCommandState) throws {
+        // Validation for --debugger first, since it affects other validations.
+        if options.shouldLaunchInLLDB {
+            try validateLLDBCompatibility(swiftCommandState: swiftCommandState)
+        }
+
         // Validation for --num-workers.
         if let workers = options.numberOfWorkers {
             // The --num-worker option should be called with --parallel. Since
@@ -690,6 +882,36 @@ public struct SwiftTestCommand: AsyncSwiftCommand {
         }
     }
 
+    /// Validates that --debugger is compatible with other provided arguments
+    ///
+    /// - Throws: if --debugger is used with incompatible flags
+    private func validateLLDBCompatibility(swiftCommandState: SwiftCommandState) throws {
+        // --debugger cannot be used with release configuration
+        let configuration = options.globalOptions.build.configuration ?? swiftCommandState.preferredBuildConfiguration
+        if configuration == .release {
+            throw StringError("--debugger cannot be used with release configuration (debugging requires debug symbols)")
+        }
+
+        // --debugger cannot be used with parallel testing
+        if options.shouldRunInParallel {
+            throw StringError("--debugger cannot be used with --parallel (debugging requires sequential execution)")
+        }
+
+        // --debugger cannot be used with --num-workers (which requires --parallel anyway)
+        if options.numberOfWorkers != nil {
+            throw StringError("--debugger cannot be used with --num-workers (debugging requires sequential execution)")
+        }
+
+        // --debugger cannot be used with information-only modes that exit early
+        if options._deprecated_shouldListTests {
+            throw StringError("--debugger cannot be used with --list-tests (use 'swift test list' for listing tests)")
+        }
+
+        if options.shouldPrintCodeCovPath {
+            throw StringError("--debugger cannot be used with --show-codecov-path (debugging session cannot show paths)")
+        }
+    }
+
     public init() {}
 }