Document new "debug test" feature

docs/docs/how_to/debugger/debugging_with_the_repl.md

@@ -14,7 +14,7 @@ sidebar_position: 1
 
 #### Pre-requisites
 
-In order to use the REPL debugger, first you need to install recent enough versions of Nargo and vscode-noir. 
+In order to use the REPL debugger, first you need to install recent enough versions of Nargo and vscode-noir.
 
 ## Debugging a simple circuit
 
@@ -162,3 +162,44 @@ Finished execution
 Upon quitting the debugger after a solved circuit, the resulting circuit witness gets saved, equivalent to what would happen if we had run the same circuit with `nargo execute`.
 
 We just went through the basics of debugging using Noir REPL debugger. For a comprehensive reference, check out [the reference page](../../reference/debugger/debugger_repl.md).
+
+## Debugging a test function
+
+Let's debug a simple circuit:
+
+```rust
+#[noir]
+fn test_simple_equal() {
+    let x = 2;
+    let y = 1 + 1;
+    assert(x == y, "should be equal");
+}
+```
+
+To start the REPL debugger for a test function, using a terminal, go to a Noir circuit's home directory. Then invoke the `debug` command setting the `--test-name` argument.
+
+```bash
+nargo debug --test-name test_simple_equal
+```
+
+After that, the debugger has started and works the same as debugging a main function, you can use any of the above explained commands to control the execution of the test function.
+
+### Test result
+
+The debugger does not end the session automatically. Once you finish debugging the execution of the test function you will notice that the debugger remain in the `Execution finished` state. If you are done debugging the test function you should exit the debugger by using the `quit` command. Once you finish the debugging session you should see the test result.
+
+```text
+$ nargo debug --test-name test_simple_equal
+
+[simple_noir_project] Starting debugger
+At opcode 0:0 :: BRILLIG CALL func 0: inputs: [], outputs: []
+
+> continue
+(Continuing execution...)
+Finished execution
+
+> quit
+[simple_noir_project] Circuit witness successfully solved
+[simple_noir_project] Testing test_simple_equal... ok
+[simple_noir_project] 1 test passed
+```

docs/docs/how_to/debugger/debugging_with_vs_code.md

@@ -23,9 +23,15 @@ This guide will show you how to use VS Code with the vscode-noir extension to de
 
 ## Running the debugger
 
-The easiest way to start debugging is to open the file you want to debug, and press `F5`. This will cause the debugger to launch, using your `Prover.toml` file as input.
+The easiest way to start debugging is to open the file you want to debug, and click on `Debug` codelens over main functions or `Debug test` over `#[test]` functions
 
-You should see something like this:
+If you don't see the codelens options `Compile|Info|..|Debug` over the `main` function or `Run test| Debug test` over a test function then you probably have the codelens feature disabled. For enabling it head to the extension configuration and turn on the `Enable Code Lens` setting.
+
+![Debugger codelens](@site/static/img/debugger/debugger-codelens.png)
+
+Another way of starting the debugger is to press `F5` on the file you want to debug. This will cause the debugger to launch, using your `Prover.toml` file as input.
+
+Once the debugger has started you should see something like this:
 
 ![Debugger launched](@site/static/img/debugger/1-started.png)
 
@@ -65,4 +71,4 @@ We just need to click the to the right of the line number 18. Once the breakpoin
 
 Now we are debugging the `keccak256` function, notice the _Call Stack pane_ at the lower right. This lets us inspect the current call stack of our process.
 
-That covers most of the current debugger functionalities. Check out [the reference](../../reference/debugger/debugger_vscode.md) for more details on how to configure the debugger.
+That covers most of the current debugger functionalities. Check out [the reference](../../reference/debugger/debugger_vscode.md) for more details on how to configure the debugger.

docs/docs/reference/debugger/debugger_repl.md

@@ -20,17 +20,23 @@ Runs the Noir REPL debugger. If a `WITNESS_NAME` is provided the debugger writes
 
 ### Options
 
-| Option                | Description                                                  |
-| --------------------- | ------------------------------------------------------------ |
+| Option                            | Description                                                                         |
+| --------------------------------- | ----------------------------------------------------------------------------------- |
 | `-p, --prover-name <PROVER_NAME>` | The name of the toml file which contains the inputs for the prover [default: Prover]|
-| `--package <PACKAGE>` | The name of the package to debug                             |
-| `--print-acir`        | Display the ACIR for compiled circuit                        |
-| `--deny-warnings`     | Treat all warnings as errors                                 |
-| `--silence-warnings`  | Suppress warnings                                            |
-| `-h, --help`          | Print help                                                   |
+| `--package <PACKAGE>`             | The name of the package to debug                                                    |
+| `--print-acir`                    | Display the ACIR for compiled circuit                                               |
+| `--deny-warnings`                 | Treat all warnings as errors                                                        |
+| `--silence-warnings`              | Suppress warnings                                                                   |
+| `--test-name` <TEST_NAME>         | The name of the test function to debug - which name contains this string            |
+| `-h, --help`                      | Print help                                                                          |
 
 None of these options are required.
 
+:::note
+If the `--test-name` option is provided the debugger will debug the matching function instead of the package `main` function.
+This argument must only match one function. If the given name matches with more than one test function the debugger will not start.
+:::
+
 :::note
 Since the debugger starts by compiling the target package, all Noir compiler options are also available. Check out the [compiler reference](../nargo_commands.md#nargo-compile) to learn more about the compiler options.
 :::
@@ -357,4 +363,4 @@ Update a memory cell with the given value. For example:
 
 :::note
 This command is only functional while the debugger is executing unconstrained code.
-:::
+:::

docs/docs/reference/debugger/debugger_vscode.md

@@ -17,8 +17,7 @@ sidebar_position: 0
 
 The Noir debugger enabled by the vscode-noir extension ships with default settings such that the most common scenario should run without any additional configuration steps.
 
-These defaults can nevertheless be overridden by defining a launch configuration file. This page provides a reference for the properties you can override via a launch configuration file, as well as documenting the Nargo `dap` command, which is a dependency of the VS Code Noir debugger. 
-
+These defaults can nevertheless be overridden by defining a launch configuration file. This page provides a reference for the properties you can override via a launch configuration file, as well as documenting the Nargo `dap` command, which is a dependency of the VS Code Noir debugger.
 
 ## Creating and editing launch configuration files
 
@@ -47,7 +46,7 @@ Name of the prover input to use. Defaults to `Prover`, which looks for a file na
 _Boolean, optional._
 
 If true, generate ACIR opcodes instead of unconstrained opcodes which will be closer to release binaries but less convenient for debugging. Defaults to `false`.
-                
+
 #### skipInstrumentation
 
 _Boolean, optional._
@@ -60,9 +59,9 @@ Skipping instrumentation causes the debugger to be unable to inspect local varia
 
 ## `nargo dap [OPTIONS]`
 
-When run without any option flags, it starts the Nargo Debug Adapter Protocol server, which acts as the debugging backend for the VS Code Noir Debugger. 
+When run without any option flags, it starts the Nargo Debug Adapter Protocol server, which acts as the debugging backend for the VS Code Noir Debugger.
 
-All option flags are related to preflight checks. The Debug Adapter Protocol specifies how errors are to be informed from a running DAP server, but it doesn't specify mechanisms to communicate server initialization errors between the DAP server and its client IDE. 
+All option flags are related to preflight checks. The Debug Adapter Protocol specifies how errors are to be informed from a running DAP server, but it doesn't specify mechanisms to communicate server initialization errors between the DAP server and its client IDE.
 
 Thus `nargo dap` ships with a _preflight check_ mode. If flag `--preflight-check` and the rest of the `--preflight-*` flags are provided, Nargo will run the same initialization routine except it will not start the DAP server.
 
@@ -72,11 +71,12 @@ If the preflight check succeeds, `vscode-noir` proceeds to start the DAP server
 
 ### Options
 
-| Option                                  | Description                                                                         |
-| --------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
-| `--preflight-check`                     | If present, dap runs in preflight check mode.                               |
-| `--preflight-project-folder <PREFLIGHT_PROJECT_FOLDER>`   | Absolute path to the project to debug for preflight check.                        |
-| `--preflight-prover-name <PREFLIGHT_PROVER_NAME>`       | Name of prover file to use for preflight check                              |
-| `--preflight-generate-acir`                 | Optional. If present, compile in ACIR mode while running preflight check.                                 |
-| `--preflight-skip-instrumentation`            | Optional. If present, compile without introducing debug instrumentation while running preflight check.  |
-| `-h, --help`                            | Print help.                                               |
+| Option                                        | Description                                                                 |
+| --------------------------------------------- | --------------------------------------------------------------------------- |
+| `--preflight-check`                           | If present, dap runs in preflight check mode.                               |
+| `--preflight-project-folder <PREFLIGHT_PROJECT_FOLDER>`   | Absolute path to the project to debug for preflight check.      |
+| `--preflight-prover-name <PREFLIGHT_PROVER_NAME>`       | Name of prover file to use for preflight check                    |
+| `--preflight-generate-acir`                   | Optional. If present, compile in ACIR mode while running preflight check.   |
+| `--preflight-skip-instrumentation`            | Optional. If present, compile without introducing debug instrumentation while running preflight check. |
+| `--preflight-test-name <PREFLIGHT_TEST_NAME>` | Optional. If present, debug matching test function instead of main function |
+| `-h, --help`                                  | Print help.                                                                 |

tooling/nargo_cli/src/cli/debug_cmd.rs

@@ -57,7 +57,7 @@ pub(crate) struct DebugCommand {
     #[clap(long)]
     acir_mode: bool,
 
-    /// Only run tests that match exactly
+    /// The name of the test function to debug - which name contains this string
     #[clap(long)]
     test_name: Option<String>,