Setup Your Local Environment for Testing An Alexa Skill
Sattwik Pati Aug 29, 2019
Share:
Advanced Node.js Tutorial
Blog_Header_Post_Img

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.

Copied to clipboard
$ ./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.

Copied to clipboard
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.00

Copy 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 Blog
Alexa Blog

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:

Copied to clipboard
{
    "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.

Alexa Blog

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.

Alexa Blog
Copied to clipboard
$ ask clone -s 

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:

Copied to clipboard
$ ask new

Then, download a copy of the local-debugger.js script to the root of your skill project.

Copied to clipboard
$ 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.

Copied to clipboard
$ ./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.

Copied to clipboard
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.00

To 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:

Copied to clipboard
{
  "manifest": {
    "publishingInformation": {
     ...
    },
    "apis": {
      "custom": {
        "endpoint": {
          "sourceDir": "lambda/custom",
          "uri": "https://abc123.ngrok.io",
          "sslCertificateType": "Wildcard"
        }
      }
    },
    "manifestVersion": "1.0"
  }
}

Next, deploy your skill to Alexa:

Copied to clipboard
$ ask deploy --target skill

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

Copied to clipboard
$ ask deploy --target model

3) 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:

code snippt

Finally, you can now start a dialog with Alexa using the ASK CLI’s dialog command or from the developer console as outlined above:

Copied to clipboard
$ ask dialog --locale en-US

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

Alexa Blog

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.

Related Content

  1. Cake Time Alexa Skill Course
  2. Alexa Skills Kit for Node.js SDK Documentation
  3. Quick Start ASK CLI
  4. How to Debug Your Alexa Skill Using DynamoDB with the New Alexa Skills Kit SDK Helpers in Python