5 Tips For Setting Up Local Debugging for Alexa Skills

I've been livecoding on my Let My People Code Twitch Channel as I build an Alexa game I'm calling Word Fight. It's sort of like "Rock, Paper, Scissors," in the ease of play, but there's enough complexity that strategy comes in at higher levels.

One thing I've been doing is coding locally using Visual Studio Code (VS Code), then running a local Alexa skill server to test my code. I use ngrok to set up a tunnel, and then use the tunnel URL as my skill endpoint in the Alexa skill configuration.

I can test using the simulator in the Alexa developer console or the simulator functions in the ASK CLI (Alexa Skills Kit Command Line Interface).

What are the benefits of local debugging?

For me, it's just fewer steps. I don't have to deploy to a lambda every time I want to test. I just turn on the VS Code debugger when I want to begin testing, then hit a reload button to update with changes when I make them. And I get a bunch of tracking and error information in the VS Code Debugger console panel, instead of having to dig into my Cloudwatch logs.

For me, that's quicker.

I also developed a local persistence adapter so I can store persistent attributes (values that last between sessions) locally. I don't have to go into S3 every time I want to read or delete the persistent attributes for my user. Essentially, I can do everything I want with one window open and skip a number of steps that slow me down.

Don't try to also manually edit your dialog model. I started trying to tool around with my dialog model in a text editor and broke it.

My five tips for debugging Amazon Alexa skills locally

I won't even count this as a tip: this excellent blog post on debugging Alexa skills locally helped me get started.

And here are some tips from my experience getting it set up and using it.

1: Know your relative paths

The VS Code workspace doesn't need to be the exact folder where all your skill code is. My skill code directory is a couple of levels deep from there. When setting up the debug configuration in VS Code, be sure of the relative path from the workspace root to your debugger script and index.js script. For example, my relative path is ${workspaceFolder}\\repo\\lambda\\local-debugger.js.

This is because I have a number of working folders for graphics, sounds, and JS experiments in my workspace root folder. The actual skill is in the "repo" folder which contains the skill package as a local copy of a GitHub repository.

2: Know your tunneling options

I use ngrok, which I pay for, but there's a free level and you can also use localtunnel for free.

If you're going to use sounds or graphics in your skill, you need to host them. One of the reasons I use ngrok is so I can reserve subdomains and keep them consistent (a paid feature). You can request subdomains with localtunnel, but can't grab an exclusive on them.

3: You may need multiple servers

Since I have sounds and graphics I want to use, I also have http-server installed to set up a separate web server I can launch with my "external content" directory as root. You can set up multiple tunnels via ngrok using an ngrok configuration file, which basically gives you two URLs... one for the skill, one for your content server.

4: Abstract your content locations

Be mindful that the first way to break your code the moment it goes to a test server is to not abstract the paths/URLs to the various files that won't live in the skill package itself. I'm having to go back and turn hardcoded links into variables that will be correctly set for my dev, test, and prod environments.

Think of it like localization, but instead of localizing UI strings for spoken languages, you're localizing paths for runtime environments.

5: Level up your error info

Some of the Alexa Samples, like the Node.js first skill tutorial will have an ErrorHandler function that gives you the error message, but no other information:

console.log(`~~~~ Error handled: ${error.message}`);

Where in the code did it happen? That can be frustrating. In the Hello World sample, it has this:

console.log(`~~~~ Error handled: ${JSON.stringify(error)}`);

But in the local debugger, it stringifies the error object to {}, so that's not too helpful either.

There are two good ways to deal with this. In the debugging settings of VS Code, set a breakpoint on all exceptions and go through them for lots of data. Or a more simple option is to put this in the error handler:

    console.log(`~~~~ Error handled: ${error.message}`);
    console.dir(error);

Then in the debug console, you can expand the error object to see more info.

Thanks for reading

If you've got some good tips for using a local debugger when crafting Alexa custom skills, please share in the comments. I might share them on the Let My People Code Twitch Channel and credit you.