Test Skills in Visual Studio Code

Note: Sign in to the developer console to build or publish your skill.

You can use the Alexa Skills Kit (ASK) Toolkit for Visual Studio Code (VS Code) to test your skill code locally against your skill invocations. You can test the code by routing requests to an Alexa proxy on your developer computer. Local testing enables you to verify changes to skill code without deploying skill code to Amazon Web Services (AWS) Lambda. You can test your skill without leaving VS Code by using the VS Code Alexa simulator page. You can also test your local skill by using other methods, such as the Alexa simulator in the Alexa developer console and the ASK Command Line Interface (CLI).

For prerequisites and installation instructions, see Get Started with the ASK Toolkit for VS Code.

Note: You can only test the development stage of your skill locally.

Prerequisites

Before you can invoke your local skill, add ask-sdk-local-debug to your skill project. Follow the instructions for your SDK language to add ask-sdk-local-debug to your skill:

Set up the test environment

Before you test your skill in VS Code, you must add configuration to enable your skill to connect to the Alexa proxy. To enable audio output and Alexa Presentation Language (APL) touch events in the simulator, you must register a virtual Alexa device.

Add Alexa debugger configuration

In this step, add Alexa debugger configuration to enable your skill to connect to the Alexa proxy.

To add Alexa debugger configuration

Create a launch.json file for your skill, if you don't already have one.

Open the Run menu, and then choose Add Configuration….

In the Select Environment dialog box, choose your programming language, Node.js or Python.
This action adds the launch.json file to your project and opens the file in the editor. You should see code similar to the following example.

{
    "version": "0.2.0",
    "configurations": [
        {
            "type": "node",
            "request": "launch",
            "name": "Launch Program",
            "skipFiles": [
                "<node_internals>/**"
            ],
            "program": "${file}"
        }
    ]
}

Add the Alexa debugger configurations to your launch.json file, if you haven't already.

Open the Run menu, and then choose Add Configuration…

From the list of options, choose ASK: Alexa Skills Debugger (Node.js) or ASK: Alexa Skills Debugger (Python).
This action adds configuration code to the launch.json file. You should see code similar to the following example.

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Debug Alexa Skill (Node.js)",
            "type": "node",
            "request": "launch",
            "program": "${command:ask.debugAdapterPath}",
            "args": [
                "--accessToken",
                "${command:ask.accessToken}",
                "--skillId",
                "${command:ask.skillIdFromWorkspace}",
                "--handlerName",
                "handler",
                "--skillEntryFile",
                "${workspaceFolder}/lambda/index.js"
            ]
        },
        {
            "type": "node",
            "request": "launch",
            "name": "Launch Program",
            "skipFiles": [
                "<node_internals>/**"
            ],
            "program": "${file}"
        }
    ]
}

Save the changes to the launch.json file.

In the Alexa debugger configurations, specify the Alexa region where your developer account resides .
The valid regions are Europe (EU), the Far East (FE), or North America (NA). The default region is North America.

Find the Alexa region corresponding to the marketplace for your developer account by using the table at Hosting your skill resources in different AWS Regions.
Open the launch.json file.

Add or edit the region entry in the args array.
Valid values for region are EU, FE, and NA. Your code should look like the following example.

Important: Don't forget to add a comma at the end of the previous line.

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Debug Alexa Skill (Node.js)",
            "type": "node",
            "request": "launch",
            "program": "${command:ask.debugAdapterPath}",
            "args": [
                "--accessToken",
                "${command:ask.accessToken}",
                "--skillId",
                "${command:ask.skillIdFromWorkspace}",
                "--handlerName",
                "handler",
                "--skillEntryFile",
                "${workspaceFolder}/lambda/index.js",
                "--region",
                "FE"
            ]
        },
        {
            "type": "node",
            "request": "launch",
            "name": "Launch Program",
            "skipFiles": [
                "<node_internals>/**"
            ],
            "program": "${file}"
        }
    ]
}

Save the changes to the launch.json file.

Register a virtual Alexa device (Beta)

To enable audio output and Alexa Presentation Language (APL) touch events in the simulator, follow the steps to set up a virtual Alexa device, and then register the device with your Amazon account. You must have a registered product before you can create the virtual device. For details, see Register a Product with Alexa Voice Service (AVS).

Note: Simulator support for speech output and APL touch input is offered as a beta and might change as we receive feedback and iterate on the feature.

Navigate to the AVS dashboard and select a Product Name to gather information about the product you want to use to register your device.

To create a virtual Alexa device

In the activity bar, click the Alexa icon.
Navigate to SKILLS MANAGEMENT, click the ellipsis (…) for More Actions, and then choose Register device.
Or, expand SKILLS, expand Alexa Presentation Language (APL), and then select Preview. Click the APL preview window, and then in the pop-up, click Register Device.
For Product ID, enter your AVS Product ID.
For Client ID, enter the client ID associated with the selected product ID.
For details, see Set up your AVS security profile.
For Client secret, enter the client secret associated with the selected product.
For Region, select the region where you created your Amazon developer account.
To create the device, click Submit.

To register the device with your Amazon account

In the blue box, copy the device ID.
Note: The code is valid for 10 minutes. If the code expires, click the refresh icon to generate a new code.
To open the device registration page in your browser, click the Amazon account linking link.
You might have to sign in to your Amazon developer account.
For Register Your Device, enter the 6-digit code, and then click Continue.
To register the device with your Amazon account, click Continue.
Or, to cancel registration, click Cancel.
If prompted, click Allow to enable the registration.
Close the browser window.

To apply the device setting

In VS Code, return to the Device registry page.
To use your registered device for testing, choose Apply.
Or, to cancel registration, choose Cancel.

When you choose Apply, the simulator restarts and applies the setting to use the virtual device as default for audio output and APL touch events. You're ready to test your skill in the simulator.

Delete the registered device (Beta)

You can delete the registered device and continue to use the simulator without audio output and APL touch events.

To delete the registered device

In the activity bar, click the Alexa icon.
On the ALEXA SKILLS TOOLKIT sidebar, navigate to SKILLS MANAGEMENT, click the ellipsis (…) for More Actions, and then choose Delete device.
In the pop-up box, to delete the device and update the simulator, choose Yes. Or, to cancel device deletion, choose No.

Test your local Alexa skill

Before you complete this procedure, complete the procedures in Prerequisites and Set up the test environment.

To test your local Alexa skill in VS Code

Open the Run menu, and then choose Start Debugging.

Your skill code starts and VS Code establishes a Web Socket connection from your computer to the Alexa proxy service. Requests to your skill are now routed directly to your local skill code as long as the connection with the Alexa proxy service is open. The connection remains open for one hour. You can't create more than one connection to a skill.
Test your skill by using one of the following methods:
- The Alexa simulator in VS Code. For details see Test your skill in the VS Code Alexa simulator.
- The Alexa simulator in the developer console. For details, see Test Your Skill in the Developer Console.
- An Alexa device, such as an Echo Show or the Alexa app.
- ASK CLI.
- SMAPI REST API.

To stop testing your Alexa local skill

Open the Run menu, and then choose Stop Debugging.
This action closes the connection to the Alexa proxy service. Alexa reverts to invoking the endpoint configured for your skill instead of your local skill.

Test your skill in the VS Code Alexa simulator

You can test your skill by using the Skill Simulation page in VS Code. By using the skill simulator, you can send utterances to Alexa and receive responses without leaving VS Code.

Important: Make sure you have deployed your skill before you use the simulator.
The VS Code Alexa simulator doesn't support skill events or audio input. The VS Code Alexa simulator (beta) supports audio output and touch events. To use these beta features, you must register a virtual Alexa device.

The following screenshot shows the Skill Simulation page in VS Code:

To test your local skill in the VS Code Alexa simulator

In the activity bar, click the Alexa icon.
On the ALEXA SKILLS TOOLKIT sidebar, click Skills, and then click to open your skill.
Click Test skill, and then choose Open simulator.
On the Skill Simulation page, in the Talk to Alexa section, for Skill stage, choose Development.
This action enables your skill for testing, and activates the utterance text box at the end of the page.
For Locale, choose the language and locale that you want to test.
Your skill must contain an interaction model for the language and locale that you select. For details, see Interaction Model.
In the text box at the end of the page enter an utterance, and then click Send.
The simulator sends your request to Alexa, and the response appears.
After you receive the response, you can perform the following actions:
- To view the JSON for the most recent request and response, select the Skill I/O tab.
- To view information, such as considered intents, select the Execution Info tab.
- To see how the response from your skill appears on a device screen, select the Device Preview tab.
  - To choose from round, small, medium, large, or full-screen TV views, use Change viewport.
  - To select an item in the display, click the item you want.
Repeat the previous step, as needed.
You can enter new utterances, or use the up and down arrows on your keyboard to enter previous utterances quickly. You can't enter a new utterance until Alexa has responded to the previous request. If you registered a virtual device, Alexa plays audio responses.
At any time, to clear the utterances and responses in the Talk to Alexa section, click the Reset button.
To disable your skill for testing and end your testing session, enter exit in the text box, and then click Send.

Save and replay sessions in the VS Code Alexa simulator

When you test your skill, you might want to send the same utterances to Alexa repeatedly. You can save the utterances that you enter during a test session, and then replay them later.

To save and replay a test session in the VS Code Alexa simulator

To save a session, click the Export button.
The simulator saves your utterances as a json file, and then asks you for a location to save the file.
To replay a session, on the ALEXA SKILLS TOOLKIT sidebar, click Skills, and then click to open your skill.
Click Test skill, and then choose Replay session.
The simulator asks you for the location of a file that you saved previously. After you specify the file, the utterances replay in the simulator.
To disable your skill for testing and end your testing session, enter exit in the text box, and then click Send.

Last updated: Mar 23, 2023