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; be sure you've set the NODE_OPTIONS env variable as described above:

   ./bin/dev hello world
   

   You should see output similar to this, indicating that the CLI process is waiting for a debugger to continue the execution:

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

4. Click the Run and Debug icon in the Activity Bar on the left to attach the VS Code debugger to the CLI process you started in the previous step:

   

   The Debug section opens, with information about variables, breakpoints, and more.

5. Select the configuration named Attach using the Configuration dropdown in the Run and Debug view. Then click the green arrow or F5 to start a debug session.

   As soon as the debugger is attached, it jumps to line 3 of bin/dev because that's where we started the CLI process.

6. Click Continue in the Debug Toolbar at the top, or F5, to continue the execution. The debugger stops at the breakpoint you set in Step 2:

   

   The VARIABLES section shows the values of local variables like flags and name. The time variable is still undefined, because the debugger stopped right at line 40, which is where the variable is defined and initialized.

7. You can set breakpoints after the debug session started. Try setting one at line 41 (the line with code this.log(messages.getMessage('info.hello', [flags.name, time]));), then click Continue or F5. The debugger stops at this new breakpoint. And you now see that the time variable contains today's date.

8. To dig into a function or method call, click on the Step Into option in the Debug Toolbar (or F11) while on the line. The debugger jumps to the function or method definition. Click Step Over (or F10) to continue debugging over the next lines.

   Click Continue (or F5) to continue the execution, or Disconnect to detach VS Code from the process.

9. When you finish the debug session, be sure to unset the NODE_OPTIONS environment variable:

   For bash or zsh:

   unset NODE_OPTIONS

   For PowerShell:

   $Env:NODE_OPTIONS = ''

Debug a Test

Unlike debugging a command, you don't need to pass any options to a test because those are already in the code. This section shows how to 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 Run Current Test configuration from the Configuration dropdown in the Run and Debug view and press the green arrow, or F5, to start a debug session.

   

3. In this mode, VS Code starts the Node.js process to run the currently-open test file. The execution stops 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:

   

4. Click Step Over in the Debug Toolbar on top (or F10) to continue debugging over the next lines.

   To continue with the execution, click Continue (or F5). Click Stop to finish the Node.js process.