Add docstring and unit tests for attachDebugger (#1056)

michael-weng · web-flow · commit 5a4786f53408 · 2024-09-17T12:59:11.000-04:00
* Refactor to use showQuickPick to reduce test surface The onButtonPressed param was never utilized, so opt to use the simpler showQuickPick instead to keep things simple. Issue: #1023 * Add docstring and unit tests for attachDebugger We should hit 100% line coverage for this module now. Issue: #1023 * Fix comment that does not reflect what the test is doing
diff --git a/src/commands/attachDebugger.ts b/src/commands/attachDebugger.ts
@@ -14,41 +14,34 @@
 
 import * as vscode from "vscode";
 import { WorkspaceContext } from "../WorkspaceContext";
-import { withQuickPick } from "../ui/QuickPick";
-import { execFile, getErrorDescription } from "../utilities/utilities";
+import { getLldbProcess } from "../debugger/lldb";
 
 /**
- * Attach the debugger to a running process.
+ * Attaches the LLDB debugger to a running process selected by the user.
+ *
+ * This function retrieves a list of processes using `getLldbProcess`, then presents
+ * a process picker to the user. If the user selects a process, it configures LLDB
+ * to attach to that process and starts the debugging session in VS Code.
+ *
+ * @param {WorkspaceContext} ctx - The workspace context, which provides access to toolchain and configuration details.
+ * @returns {Promise<void>} - A promise that resolves when the debugger is successfully attached or the user cancels the operation.
+ *
+ * @throws Will display an error message if no processes are available, or if the debugger fails to attach to the selected process.
  */
 export async function attachDebugger(ctx: WorkspaceContext) {
-    // use LLDB to get list of processes
-    const lldb = await ctx.toolchain.getLLDB();
-    try {
-        const { stdout } = await execFile(lldb, [
-            "--batch",
-            "--no-lldbinit",
-            "--one-line",
-            "platform process list --show-args --all-users",
-        ]);
-        const entries = stdout.split("\n");
-        const processPickItems = entries.flatMap(line => {
-            const match = /^(\d+)\s+\d+\s+\S+\s+\S+\s+(.+)$/.exec(line);
-            if (match) {
-                return [{ pid: parseInt(match[1]), label: `${match[1]}: ${match[2]}` }];
-            } else {
-                return [];
-            }
+    const processPickItems = await getLldbProcess(ctx);
+    if (processPickItems !== undefined) {
+        const picked = await vscode.window.showQuickPick(processPickItems, {
+            placeHolder: "Select Process",
         });
-        await withQuickPick("Select Process", processPickItems, async selected => {
+        if (picked) {
             const debugConfig: vscode.DebugConfiguration = {
                 type: "swift-lldb",
                 request: "attach",
                 name: "Attach",
-                pid: selected.pid,
+                pid: picked.pid,
             };
             await vscode.debug.startDebugging(undefined, debugConfig);
-        });
-    } catch (error) {
-        vscode.window.showErrorMessage(`Failed to run LLDB: ${getErrorDescription(error)}`);
+        }
     }
 }
diff --git a/src/commands/switchPlatform.ts b/src/commands/switchPlatform.ts
@@ -13,43 +13,44 @@
 //===----------------------------------------------------------------------===//
 
 import * as vscode from "vscode";
-import { withQuickPick } from "../ui/QuickPick";
 import { DarwinCompatibleTarget, SwiftToolchain } from "../toolchain/toolchain";
 import configuration from "../configuration";
 
 /**
  * Switches the target SDK to the platform selected in a QuickPick UI.
  */
 export async function switchPlatform() {
-    await withQuickPick(
-        "Select a new target",
+    const picked = await vscode.window.showQuickPick(
         [
             { value: undefined, label: "macOS" },
             { value: DarwinCompatibleTarget.iOS, label: "iOS" },
             { value: DarwinCompatibleTarget.tvOS, label: "tvOS" },
             { value: DarwinCompatibleTarget.watchOS, label: "watchOS" },
             { value: DarwinCompatibleTarget.visionOS, label: "visionOS" },
         ],
-        async picked => {
-            try {
-                const sdkForTarget = picked.value
-                    ? await SwiftToolchain.getSDKForTarget(picked.value)
-                    : "";
-                if (sdkForTarget !== undefined) {
-                    if (sdkForTarget !== "") {
-                        configuration.sdk = sdkForTarget;
-                        vscode.window.showWarningMessage(
-                            `Selecting the ${picked.label} SDK will provide code editing support, but compiling with this SDK will have undefined results.`
-                        );
-                    } else {
-                        configuration.sdk = undefined;
-                    }
+        {
+            placeHolder: "Select a new target",
+        }
+    );
+    if (picked) {
+        try {
+            const sdkForTarget = picked.value
+                ? await SwiftToolchain.getSDKForTarget(picked.value)
+                : "";
+            if (sdkForTarget !== undefined) {
+                if (sdkForTarget !== "") {
+                    configuration.sdk = sdkForTarget;
+                    vscode.window.showWarningMessage(
+                        `Selecting the ${picked.label} SDK will provide code editing support, but compiling with this SDK will have undefined results.`
+                    );
                 } else {
-                    vscode.window.showErrorMessage("Unable to obtain requested SDK path");
+                    configuration.sdk = undefined;
                 }
-            } catch {
+            } else {
                 vscode.window.showErrorMessage("Unable to obtain requested SDK path");
             }
+        } catch {
+            vscode.window.showErrorMessage("Unable to obtain requested SDK path");
         }
-    );
+    }
 }
diff --git a/src/debugger/lldb.ts b/src/debugger/lldb.ts
@@ -17,7 +17,9 @@
 
 import * as path from "path";
 import * as fs from "fs/promises";
-import { execFile } from "../utilities/utilities";
+import * as vscode from "vscode";
+import { WorkspaceContext } from "../WorkspaceContext";
+import { execFile, getErrorDescription } from "../utilities/utilities";
 import { Result } from "../utilities/result";
 import { SwiftToolchain } from "../toolchain/toolchain";
 
@@ -103,3 +105,43 @@ async function findFileByPattern(path: string, pattern: RegExp): Promise<string
     }
     return null;
 }
+
+/**
+ * Retrieves a list of LLDB processes from the system using LLDB.
+ *
+ * This function executes an LLDB command to list all processes on the system,
+ * including their arguments, and returns them in an array of objects where each
+ * object contains the `pid` and a `label` describing the process.
+ *
+ * @param {WorkspaceContext} ctx - The workspace context, which includes the toolchain needed to run LLDB.
+ * @returns {Promise<Array<{ pid: number; label: string }> | undefined>}
+ * A promise that resolves to an array of processes, where each process is represented by an object with a `pid` and a `label`.
+ * If an error occurs or no processes are found, it returns `undefined`.
+ *
+ * @throws Will display an error message in VS Code if the LLDB command fails.
+ */
+export async function getLldbProcess(
+    ctx: WorkspaceContext
+): Promise<Array<{ pid: number; label: string }> | undefined> {
+    try {
+        // use LLDB to get list of processes
+        const lldb = await ctx.toolchain.getLLDB();
+        const { stdout } = await execFile(lldb, [
+            "--batch",
+            "--no-lldbinit",
+            "--one-line",
+            "platform process list --show-args --all-users",
+        ]);
+        const entries = stdout.split("\n");
+        return entries.flatMap(line => {
+            const match = /^(\d+)\s+\d+\s+\S+\s+\S+\s+(.+)$/.exec(line);
+            if (match) {
+                return [{ pid: parseInt(match[1]), label: `${match[1]}: ${match[2]}` }];
+            } else {
+                return [];
+            }
+        });
+    } catch (error) {
+        vscode.window.showErrorMessage(`Failed to run LLDB: ${getErrorDescription(error)}`);
+    }
+}
diff --git a/src/ui/QuickPick.ts b/src/ui/QuickPick.ts
diff --git a/test/suite/commands/attachDebugger.test.ts b/test/suite/commands/attachDebugger.test.ts
@@ -0,0 +1,16 @@
+import * as assert from "assert";
+import { getLldbProcess } from "../../../src/debugger/lldb";
+import { SwiftToolchain } from "../../../src/toolchain/toolchain";
+import { WorkspaceContext } from "../../../src/WorkspaceContext";
+import { SwiftOutputChannel } from "../../../src/ui/SwiftOutputChannel";
+
+suite("getLldbProcess Contract Test Suite", () => {
+    test("happy path, make sure lldb call returns proper output", async () => {
+        const toolchain = await SwiftToolchain.create();
+        const workspaceContext = await WorkspaceContext.create(
+            new SwiftOutputChannel("Swift"),
+            toolchain
+        );
+        assert.notStrictEqual(await getLldbProcess(workspaceContext), []);
+    });
+});
diff --git a/test/unit-tests/debugger/attachDebugger.test.ts b/test/unit-tests/debugger/attachDebugger.test.ts
@@ -0,0 +1,74 @@
+//===----------------------------------------------------------------------===//
+//
+// This source file is part of the VS Code Swift open source project
+//
+// Copyright (c) 2021-2024 the VS Code Swift project authors
+// Licensed under Apache License v2.0
+//
+// See LICENSE.txt for license information
+// See CONTRIBUTORS.txt for the list of VS Code Swift project authors
+//
+// SPDX-License-Identifier: Apache-2.0
+//
+//===----------------------------------------------------------------------===//
+
+import * as vscode from "vscode";
+import * as lldb from "../../../src/debugger/lldb";
+import { attachDebugger } from "../../../src/commands/attachDebugger";
+import { mockNamespace } from "../MockUtils";
+import {
+    mock,
+    instance,
+    when,
+    spy,
+    verify,
+    anything,
+    deepEqual,
+    objectContaining,
+} from "ts-mockito";
+import { SwiftToolchain } from "../../../src/toolchain/toolchain";
+import { WorkspaceContext } from "../../../src/WorkspaceContext";
+import { registerLLDBDebugAdapter } from "../../../src/debugger/debugAdapterFactory";
+
+suite("attachDebugger Unit Test Suite", () => {
+    const lldbSpy = spy(lldb);
+    const mockContext = mock(WorkspaceContext);
+    const mockToolchain = mock(SwiftToolchain);
+    const windowMock = mockNamespace(vscode, "window");
+    const debugMock = mockNamespace(vscode, "debug");
+
+    setup(() => {
+        when(mockContext.toolchain).thenReturn(instance(mockToolchain));
+    });
+
+    test("should call startDebugging with correct debugConfig", async () => {
+        // Setup fake debug adapter
+        registerLLDBDebugAdapter(instance(mockContext));
+
+        // Mock the list of processes returned by getLldbProcess
+        const processPickItems = [
+            { pid: 1234, label: "1234: Process1" },
+            { pid: 2345, label: "2345: Process2" },
+        ];
+        when(lldbSpy.getLldbProcess(anything())).thenResolve(processPickItems);
+
+        // Mock showQuickPick to return a selected process.
+        // It's unfortunate that anthing will match the wrong function, so we have to hard code which makes the test more brittle.
+        // So just change here when the test starts failing.
+        when(
+            windowMock.showQuickPick(
+                deepEqual(processPickItems),
+                deepEqual({ placeHolder: "Select Process" })
+            ) as Promise<(typeof processPickItems)[0]>
+        ).thenResolve(processPickItems[0]);
+
+        // Call attachDebugger
+        await attachDebugger(instance(mockContext));
+
+        // Verify startDebugging was called with the right pid.
+        // Integration level check needed: actual config return a fulfilled promise.
+        verify(
+            debugMock.startDebugging(undefined, objectContaining(processPickItems[0].pid))
+        ).once();
+    });
+});
diff --git a/test/unit-tests/debugger/getLldbProcess.test.ts b/test/unit-tests/debugger/getLldbProcess.test.ts
