feat: how to debug tests with vscode

how-to/debug-tests-with-visual-studio-code.rst

@@ -0,0 +1,70 @@
+Debug Tests with Visual Studio Code
+===================================================
+
+Debugging Launchpad tests in Visual Studio Code (VS Code) can streamline your
+development process by allowing you to inspect code, set breakpoints, and
+interactively solve problems within your tests. This guide will help you set up
+VS Code for debugging Launchpad tests.
+
+Create the ``launch.json`` File
+-------------------------------
+
+First, you need to set up your debugging environment by creating a
+``launch.json`` file in the ``.vscode`` directory at the root of your project.
+This file will tell VS Code how to launch the debugger for your project's tests.
+Here’s how the ``launch.json`` file should look:
+
+.. code-block:: json
+
+    {
+        "version": "0.2.0",
+        "configurations": [
+            {
+                "name": "Debug Launchpad Tests",
+                "type": "debugpy",
+                "request": "launch",
+                "program": "${workspaceFolder}/bin/test",
+                "console": "integratedTerminal",
+                "args": [
+                    "-vvc", "-t", "${command:pickArgs}"
+                ]
+            }
+        ]
+    }
+
+This configuration uses the Python debugger extension (``debugpy``) and
+specifies that the debugger should start the ``test`` script located in your
+project's ``bin`` directory, with verbose output. The additional test selection
+arguments allow you to specify which test to debug; when you launch the
+debugger, a pop-up window will appear, prompting you to input the test name you
+want to debug using the ``${command:pickArgs}`` command.
+
+Launch the Debugger
+-------------------
+
+After setting up the ``launch.json``, you can start the debugger using one of
+the following methods:
+
+1. **Command Palette:** - Open the Command Palette (``Ctrl+Shift+P`` or
+   ``Cmd+Shift+P`` on macOS) and type 'python debugger'. Select ``Python
+   Debugger: Debug using launch.json``.
+
+2. **Debug Menu in Activity Bar:** - Click on the Debug icon on the left/right
+   Activity Bar (or press ``Ctrl+Shift+D``), select the configuration you wish
+   to launch (which are picked from your ``launch.json`` file), then click the
+   green start icon at the top.
+
+3. **Debug Icon in Tab Bar:** - At the top right, you'll see a debug icon with a
+   dropdown for your debug configurations—select the ``Python Debugger: Debug
+   using launch.json`` option. Select the configuration you wish to launch.
+
+Additional Resources
+--------------------
+
+For more detailed information on debugging with Visual Studio Code, especially
+for Python applications, refer to the `VS Code Python debugging documentation
+<https://code.visualstudio.com/docs/python/debugging>`_.
+
+To customize your debugging experience further, such as using conditional
+breakpoints, logpoints, and more, consult the `VS Code general debugging
+documentation <https://code.visualstudio.com/docs/editor/debugging>`_.