Test Skills in Visual Studio Code
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.
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 thelaunch.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 thelaunch.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 areEU
,FE
, andNA
. 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).
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.
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.
Related topics
- Create and Manage Skills in VS Code
- Manage and Preview APL Documents in VS Code
- Skill Simulation API
- Skill Enablement API
Last updated: Nov 23, 2023