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.

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.

Let's debug the hello world command that's included in the plugin generated with sf dev generate plugin as the example in this topic.

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

  1. Set the NODE_OPTIONS environment variable to --inspect-brk. To do this at the command line:

    For bash or zsh:

    For PowerShell:

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

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

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

    VS Code editor open to world.ts Typescript file and a breakpoint set.

  4. In VS Code's integrated terminal, run the hello world command using bin/dev.js.

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

  5. 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:

    VS Code showing run and debug icon highlighted.

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

  6. 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.

    VS Code showing Attach configuration highlighted.

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

  7. 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 time. The time variable is still undefined, because the debugger stopped right at line 28, which is where the variable is defined and initialized.

    VS Code showing the Continue debugger button and the Variables section highlighted.

  8. You can set breakpoints after the debug session started. Try setting one at line 29 (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.

  9. 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.

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

    For bash or zsh:

    For PowerShell:

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 the line expect(result.name).to.equal('World'); (line 29):

    VS Code showing world.test.ts file and breakpoint highlighted.

  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.

    VS Code showing run current test configuration highlighted.

  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:

    VS Code showing the result object JSON output highlighted.

  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.