diff --git a/docs/docs/how_to/debugger/debugging_with_the_repl.md b/docs/docs/how_to/debugger/debugging_with_the_repl.md index 09e5bae68ad..6f7159a0f9d 100644 --- a/docs/docs/how_to/debugger/debugging_with_the_repl.md +++ b/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 +``` diff --git a/docs/docs/how_to/debugger/debugging_with_vs_code.md b/docs/docs/how_to/debugger/debugging_with_vs_code.md index a5858c1a5eb..4716398a858 100644 --- a/docs/docs/how_to/debugger/debugging_with_vs_code.md +++ b/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. \ No newline at end of file +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. diff --git a/docs/docs/reference/debugger/debugger_repl.md b/docs/docs/reference/debugger/debugger_repl.md index 46e2011304e..d16d712cde9 100644 --- a/docs/docs/reference/debugger/debugger_repl.md +++ b/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 ` | The name of the toml file which contains the inputs for the prover [default: Prover]| -| `--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 ` | 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` | 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. -::: \ No newline at end of file +::: diff --git a/docs/docs/reference/debugger/debugger_vscode.md b/docs/docs/reference/debugger/debugger_vscode.md index c027332b3b0..673579a3704 100644 --- a/docs/docs/reference/debugger/debugger_vscode.md +++ b/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 ` | Absolute path to the project to debug for preflight check. | -| `--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 ` | Absolute path to the project to debug for preflight check. | +| `--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 ` | Optional. If present, debug matching test function instead of main function | +| `-h, --help` | Print help. | diff --git a/docs/static/img/debugger/debugger-codelens.png b/docs/static/img/debugger/debugger-codelens.png new file mode 100644 index 00000000000..a71f5f02a73 Binary files /dev/null and b/docs/static/img/debugger/debugger-codelens.png differ diff --git a/tooling/nargo_cli/src/cli/debug_cmd.rs b/tooling/nargo_cli/src/cli/debug_cmd.rs index f9781e82fe9..4d1392db559 100644 --- a/tooling/nargo_cli/src/cli/debug_cmd.rs +++ b/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,