Debugging Cards using Visual Studio Code

Debugging can often be seen as a tedious yet necessary part of the development process. Luckily, Digital Assistant was designed to assist debugging without bounding to a particular tool set. This means that you can debug NodeJS applications with ease whilst using your favorite tools. In this guide we're going to learn how to enable debugging and see how Digital Assistant Cards can be debugged using Visual Studio Code. Let's begin!

This guide continues from the previous guide on building a Card with API proxy, therefore it is assumed that you have NodeJS and VS Code pre-installed.

Enable Debug Mode

To start we need to enable the Debug Mode for NodeJS applications running within Digital Assistant. To do that we'll navigate to Settings → Global and select the NodeJs Settings. Here we should enable the Debug Mode as shown in the picture:

Enable the debug mode

Click the check button to save the settings. When enabled the NodeJs Inspector is started and caching of all .js files is disabled. This ensures that all file changes are immediately recognized and that a NodeJs Debugger (like Visual Studio Code) can be used to debug the JavaScript code.

Connecting to VS Code debugger

VS Code has a useful debugging suite which allows to 'attach' to a running Node JS process. This means that you can set breakpoints and inspect your Card during run-time. This can be especially beneficial when dealing with API errors or bugs. For example, let's say your card is not showing the data from an API and you wish to know what information is forwarded to the Card from the API response. You could add a breakpoint in your Card's script.js file and inspect the API response values.

VS Code Launch Configuration

VS Code can have multiple launch configurations that can be used for a multitude of purposes. For example you can have a launch configuration to run a Javascript file, start unit tests or attach to an external process for debugging. The latter is what we're interested in for this guide. We want VS Code to listen to the activity on our NodeJS card, set some breakpoints in the script.js file and then debug it once it's run.

You can learn more about VS Code Launch Configurations here.

When a Digital Assistant Card is created using the 'Basic Card (async NodeJs API proxy)' template it automatically creates .vscode folder containing a launch.json file with all the necessary configurations. Therefore, if Debug Mode is enabled we should be ready to attach to the NodeJS Card process and start debugging.

Attach to the NodeJS process

VS Code can only attach to a Digital Assistant Card if the Card has been started at least once. For example, if it's been displayed in Digital Assistant 'Workplace' or 'Show Now' board. But what if we're just testing the card and don't want to display it yet? In that case we can manually test the script.js file, which will start the Card without displaying it.

We can follow the steps for managing API which will run the script.js file and activate the Card.

Once the Card's active, we'll open the Card's script folder in VS Code:

Open script folder

You can click Ctrl + K followed by Ctrl + O as a shortcut.

Then, go to the Debug window and run the Attach to process launch configuration:

Run launch configuration in VS Code

If you don't see 'Attach to Process' configuration please make sure you open the script folder residing inside your Card's directory as VS Code tries to automatically locate the .vscode folder and creates a new one if it can't.

You should see the following message in the console:

Debugging with inspector protocol because it was detected

Adding breakpoints

Now let's try to debug our card and see how it works. In our current Card we're getting the weather data from an API. Let's add a breakpoint below the response to see all of the data we're receiving. If we send an AJAX request using the REST Test Tool once again it should trigger our breakpoint:

Add a breakpoint and inspect variables

By looking at the variables tab on the left we can conveniently inspect the response object we received from the API. We can also add multiple breakpoints and step through the application, which is useful if we want to test the application step-by-step or observe the flow of the application.