Editor’s Note: You can now perform local debugging using Visual Studio Code with the Alexa Skills Toolkit. Please see our docs for more information. If you use a different IDE or editor, please check out the ASK SDK local debug package for Node.js.
Editor’s Note 2: We have changed the name of the Alexa skill in our beginner tutorial from Cake Walk to Cake Time given the term’s racially insensitive history.
If you’re hosting your Alexa skill on AWS Lambda, debugging can be time-consuming and require log parsing. In this blog post, we’ll demonstrate how you can speed up your development process by setting up a local debugging workflow with our provided scripts and other proxy solutions. With local debugging, you can debug your skill in the same environment you develop, enabling you to iterate on and deliver improvements to your skill much more quickly.
This guide provides instruction for Node.js. For debugging in other languages, please visit the guide for debugging with Python and the guide for debugging for Java.
Set up Your Local Debugging Workflow
If this is your first time building a skill, learn how to get started with our beginner training course.
If you’ve already started building your skill and are using Alexa-hosted skills, follow the steps below in our Set up Your Local Debugging Workflow with the ASK CLI instead.
1) Download the debug run script
To invoke your skill code in your local environment, you’ll need to utilize our debug run script. Downloading a copy of the script for Node.js and place this script in the root of your skill’s project directory.
2) Forward Alexa requests to your skill
Alexa typically sends requests to skill code that is hosted on a service such as AWS Lambda. However, in order to debug your skill in a local environment, you’ll need to route Alexa requests to your local machine. To achieve this, we’ll be using a proxy service. There are many proxy options available. In this blog post, we’ll be using a third-party service called ngrok, which you can download directly from their website.
Once you’ve downloaded ngrok, start a connection to the ngrok proxy on an open port. We've chosen to use port 3001 for this example.
$ ./ngrok http 3001
NOTE: Unless you’ve registered for one of ngrok’s paid plans, sessions will expire after 8 hours and you will need to restart the ngrok process above.
Next, copy the https forwarding address provided in the ngrok output.
ngrok by @inconshreveable (Ctrl+C to quit)
Session Status online
Session Expires 7 hours, 59 minutes
Update update available (version 2.3.34, Ctrl-U to update
Version 2.3.29
Region United States (us)
Web Interface http://127.0.0.1:4040
Forwarding http://abc123.ngrok.io -> http://localhost:3001
Forwarding https://abc123.ngrok.io -> http://localhost:3001
Connections ttl opn rt1 rt5 p50 p90
0 0 0.00 0.00 0.00 0.00Copy and paste the URL to the Default Region field under Endpoint within the Build tab. Ensure the SSL certificate type is set to “My development endpoint is a sub-domain of a domain that has a wildcard certificate”.
Alexa’s requests will now be forwarded through ngrok to your local environment.
3) Start your debugger
To start debugging your skill with VSCode, you’ll need to add a launch configuration to your skill project. You can do this from the menu by selecting Debug > “Add Configuration...”. Copy and paste the below into your configuration. Be sure to update the program path to the local-debugger.js file and the skillEntryFile to your Lambda handler file:
{
"version": "0.2.0",
"configurations": [
{
"type": "node",
"request": "launch",
"name": "Launch Program",
"program": "${workspaceRoot}/local-debugger.js",
"args": [
"--portNumber", "3001",
"--skillEntryFile", "Path/To/index.js",
"--lambdaHandler", "handler"
],
}
]
}You can now set breakpoints throughout your skill code. When you’re ready to start debugging, start the debugger from the menu by selecting Debug > Start Debugging.
4) Invoke your skill and debug
To invoke your skill, head on over to the developer console and select the Test tab. Enable your skill for testing by setting the test environment to Development if you haven’t already.
Set up Your Local Debugging Workflow with the ASK CLI
If this is your first time creating a skill using the ASK CLI, review our beginner training guide for the CLI.
1) Download debug run script
If you’re hosting your skill with Alexa-hosted skills, you’ll first need to use the ASK CLI to clone your skill down to your local environment. Your skill’s ID can be found in the developer console under Endpoint.
$ ask clone -s <SKILL_ID>If you’re creating a skill for the very first time using the CLI, just run the following command and follow the on-screen prompts:
$ ask newThen, download a copy of the local-debugger.js script to the root of your skill project.
$ curl https://raw.githubusercontent.com/alexa/alexa-cookbook/master/tools/LocalDebugger/nodejs/local-debugger.js > Path/To/MySkillProject/local-debugger.js 2) Forward Alexa requests to your skill
We’ll be using ngrok as we did in the previous workflow. You can follow the same steps outlined above in 2) Forward Alexa Requests to Your Skill to download and set up ngrok.
$ ./ngrok http 3001NOTE: Unless you’ve registered for one of ngrok’s paid plans, sessions will expire after 8 hours and you will need to restart the ngrok process above.
Next, copy the https forwarding address provided in the ngrok output.
ngrok by @inconshreveable (Ctrl+C to quit)
Session Status online
Session Expires 7 hours, 59 minutes
Update update available (version 2.3.34, Ctrl-U to update
Version 2.3.29
Region United States (us)
Web Interface http://127.0.0.1:4040
Forwarding http://abc123.ngrok.io -> http://localhost:3001
Forwarding https://abc123.ngrok.io -> http://localhost:3001
Connections ttl opn rt1 rt5 p50 p90
0 0 0.00 0.00 0.00 0.00To forward requests from Alexa through ngrok to your local machine, you’ll need to add a uri attribute with your ngrok URL, and a sslCertificateType attribute set to Wildcard in your skill.json file:
{
"manifest": {
"publishingInformation": {
...
},
"apis": {
"custom": {
"endpoint": {
"sourceDir": "lambda/custom",
"uri": "https://abc123.ngrok.io",
"sslCertificateType": "Wildcard"
}
}
},
"manifestVersion": "1.0"
}
}Next, deploy your skill to Alexa:
$ ask deploy --target skillIf you’re creating this skill for the first time, make sure your skill’s model has been built. This can also be done from the developer console.
$ ask deploy --target model3) Start your debugger
Using VSCode, you can follow the previous steps and configuration outlined above in Set up Your Local Debugging Workflow.
4) Invoke your skill and debug
You will first need to enable your skill for testing if you haven’t done so before:
Finally, you can now start a dialog with Alexa using the ASK CLI’s dialog command or from the developer console as outlined above:
$ ask dialog --locale en-US5) Revert to Alexa-hosted Lambda
If you’re using Alexa-hosted skills, you’ll need revert your endpoint back to its original value before publishing your skill. This can be done from the Code tab in the developer console.
Conclusion
By incorporating a local debugging workflow into our skill development process, we’ve significantly reduced the amount of time required to debug our skills. We no longer need to wait for code to deploy in order to test our changes or parse output logs to find out where things went wrong. We can now debug in the same environment we write our skills, allowing us to iterate much more quickly and focus our efforts on building even better skill experiences.