Debug Your Plugin

We recommend that you use Visual Studio Code's (VS Code) built-in debugger to debug your plugin because the plugin generated from sf dev generate plugin already includes debugging configuration settings for VS Code.

VS Code has two core debugging modes: launch and attach. See Launch versus attach configurations for more info. We show how to use use both modes in this section.

Debug a Command

Debugging a command involves passing different arguments or flags during a debug session. For this use case, we recommend you use the attach debug mode in VS Code for a better experience.

For the attach mode, the Node.js process must be listening for a debugging client. Because oclif plugins use bin/dev as the main executable, set the NODE_OPTIONS environment variable to pass options to it like this:

For bash or zsh:

export NODE_OPTIONS='--inspect-brk'

For PowerShell:

$Env:NODE_OPTIONS = '--inspect-brk'

Now let's debug the hello world command that's included in the plugin generated with sf dev generate plugin and see how the hello message is created.

NOTE: We provide line numbers to help you find specific parts of the code. But the line numbers are for a freshly-generated file from sf dev generate plugin. If you've updated the hello world files since generating the plugin, then the line numbers will be different.

1. In VS Code, open the top-level directory of your plugin.

2. Open src/commands/hello/world.ts and set a breakpoint on the line with code const time = new Date().toDateString(); (line 40, in the run() method) by clicking on the editor margin or using F9 on the line:

   

3. In a terminal, run the hello world command using bin/dev, the process now waits for a debugger to continue the execution; be sure you've set the NODE_OPTIONS env variable as described above:

   ./bin/dev hello world
   Debugger listening on ws://127.0.0.1:9229/22bc83d3-0b97-4dbb-b228-1697d0a0878a
   For help, see: https://nodejs.org/en/docs/inspector
   

4. Now attach the VS Code debugger to the CLI process from the previous step, to do that select the Run and Debug icon in the Activity Bar on the side of VS Code:

then select the configuration named Attach using the Configuration dropdown in the Run and Debug view and press F5 to start a debug session.

Once the debugger is attached it will jump to line 3 of bin/dev as that's where the process start, you can continue the execution by pressing Continue in the Debug toolbar or F5

5. After continuing with the execution you should see the debugger stop at the breakpoint set in step 2, if you look at the VARIABLES section you can see value of the local variables like flags and time:

At this point the message variable is still undefined, that's because the debugger stopped right at line 40 which is where the variable is defined and initialized.

You can also set breakpoints after the debug session started. Try setting one at line 41 and press F5, the debugger will now stop at the next breakpoint. If you hover over message on line 41 while the debugger is waiting you can see it holds the message to print:

If you want to dig into a function or method call, you can click on the Step Into option in the Debug Toolbar while on the line and the debugger jump to its definition.

To continue debugging over the next lines press Step Over in the Debug Toolbar or F10, after you are done press Continue or F5 to continue with the execution or Disconnect to deattach VS Code from the process.

6. After you finished a debug session make sure to unset the NODE_OPTIONS environment variable:

bash/zsh:

unset NODE_OPTIONS

PowerShell

$Env:NODE_OPTIONS = ''

Debug a Test

Unlike debugging a command, you don't need to pass any options to a test as those are already in code. For this case we will use the launch debug mode in VS Code to debug the hello world command unit test.

1. Open test/commands/hello/world.test.ts and set a breakpoint on line 24:

2. Select the configuration named Run Current Test using the Configuration dropdown in the Run and Debug view and press F5 to start a debug session.

3. In this mode VS Code starts the Node.js process to run the current open test file, then the execution stopped right at the first breakpoint. Try hovering over the result object on line 24 to see the JSON output the command in the test case returned:

To continue debugging over the next lines press Step Over in the Debug Toolbar or F10, after you are done press Continue or F5 to continue with the execution or Stop to finish the Node.js process.