Getting started with Alexa: Setting up a development environment for your Alexa Skill
For the second blog post of our series "Getting started with Alexa,” Mav Peri, a senior solutions architect for Alexa guides you through setting up the Alexa Development Environment using Visual Studio Code. This is part of our ongoing effort to provide you with best practices and tips from technical experts at Amazon.
Mav is a senior solutions architect for Amazon Alexa and a disability advocate who is also a single parent of two amazing boys. Prior to joining the Alexa team, he spent four years as a Senior Solution Architect at AWS.
In the blog post below, Peri talks about the best practices on using a development environment that simplifies the process of building an Alexa skill. With the aim of reducing the the amount of new information to learn, Peri recommends using Visual Studio Code for coding, Git for source control and deployment pipeline, and Jest for unit tests.
Below are Peri’s instructions on setting up a development environment for building your Alexa Skill.
Set up the development environment to build your Alexa Skill
I use Visual Studio Code, a free and open-source IDE that can be used on both Windows and macOS.
To begin, download and set up Visual Studio Code (VSC). Then, download the Alexa Visual Studio Toolkit - a VSC extension that simplifies the process of creating, testing, and deploying Alexa skills.
To install the Alexa Skills Toolkit in Visual Studio Code, follow these steps:
1. Open the View menu and select Extensions.
2. In the search box, type "Alexa Skills Kit".
3. Choose the option that says "Alexa Skills Kit (ASK) Toolkit" and click on the Install button.
4. The language code for the output is EN-US. Learn more about the Alexa Skills Toolkit for Visual Studio Code here. You will have to sign in to your Amazon Developer Account within VSC.
To access the ASK toolkit from Alexa for VSC, click on the Alexa Icon.
After installing the ASK Toolkit extension, you will be able to create new skills or work on existing ones.
It's time to use the ASK toolkit in Visual Studio Code to create a new skill for Alexa.
To create your skill, click on "Create a skill," and assign it the name:” dev-env-blog-post". Choose your language. Also choose Alexa hosted, which provides free hosting of AWS Lambda, DynamoDB, and Amazon S3 storage.
Select your runtime, and finally the local working directory for your skill. Click on the "Create skill" button on the bottom right of the screen.
When the skill creation is complete, Visual Studio Code might ask if you trust the authors of the files in the folder.
Let's take a quick look at the folders and files that have been created so far in our working folder:
- /lambdaFolder containing the backend code files for the skill.
- /lambda/index.js, This file is our main lambda function which will handle all skill requests. When someone interacts with our skill on an Alexa-enabled device, the request is passed as a JSON payload to this lambda function. The lambda function needs to be capable of handling all requests defined in the /skill-package/interactionModels/custom/en-AU.json file.
- /skill-package folder, It contains the definition of the skill and interaction models.
- /skill-package/interactionModels/custom/en-AU.json file. This file includes the language model definition of our skill in JSON format. Specifically, it comprises the invocation name for our hello world skill (i.e., what a user says to launch the skill) and several intents (such as help, cancel, or hello world).
- /ask-resources.json file, contains a JSON object with the skill ID.
Deploy your code
Open the /skill-package/interactionModels/custom/en-AU.json file. For the use case specified in this article, I changed the invocation name from "change me" to "blog post demo," before saving my changes.
The toolkit for ASK and the Alexa Developer console use a Git repository to manage files and deployments. You can see from the figure below that there are three pending changes.
After completing the commit, VS Code will prompt you to sync the changes. The "Sync Changes" button pushes my local Git changes to the Alexa-hosted Git remote endpoint.
Test the changes
To check if the changes have been deployed and the new invocation name works, open the Alexa Developer Console in your browser, and select your new skill.
To confirm that your skill can be activated, access the Invocations and Skill Invocation Name options from the left-hand menu on the console.
Test your invocation name by clicking on the Test button located at the top of the developer console.
To ensure successful testing, confirm that the locale you are testing (such as EN-AU) matches the locale(s) you designated when developing the skill (located in the /skill-package/interactionModels/custom/ folder.)
If you test on a different locale than what your skill is programmed for, Alexa won't be able to direct the request to your skill, resulting in an error message.
There’s one other scenario to consider. When the user's new skill is launched, the Lambda function's LaunchRequestHandler is triggered and the simulator responds with a voice message that offers two options: "Hello" or "Help."
For the skill described in this article, after typing "Hello" into the simulator and pressing enter, the simulator responds with "Hello world!" This happens because the lambda function's HelloWorldIntentHandler is triggered with a default response of "Hello".
My skill uses the definition we gave in /skill-package/interactionModels/custom/en-AU.json to determine which intent to trigger. When the user says "hello," it will activate the HelloWorldIntentHandler because it is part of the HelloWorldIntent.
Creating unit tests
Use the terminal to navigate to the Lambda folder.
cd lambda
Then, run the npm command to install the test framework Jest.
npm install --save-dev jest
Once jest is installed, edit lambda/package.json.
"scripts": {
"test": "echo \"Error: no test specified\" && exit 1"
},
to
"scripts": {
"test": "jest --coverage"
},
Check the setup to ensure that everything is functional.
npm test
After preparing your test setup, you can proceed to refactor the code to test one of the handlers. This blog post only covers one handler for now, and a more detailed explanation of testing will be available in a future post.
I have created a folder named "lambda/test" to store all the unit tests.
The LaunchRequestHandler code is moved from lambda/index.js and pasted into a new file named lambda/handlers/LaunchRequestHandler.js:
const Alexa = require('ask-sdk-core');
const LaunchRequestHandler = {
canHandle(handlerInput) {
return Alexa.getRequestType(handlerInput.requestEnvelope) === 'LaunchRequest';
},
handle(handlerInput) {
const speakOutput = 'Welcome, you can say Hello or Help. Which would you like to try?';
return handlerInput.responseBuilder
.speak(speakOutput)
.reprompt(speakOutput)
.getResponse();
}
};
module.exports = LaunchRequestHandler;
At the top of Index.js (and after importingask-sdk-core) , you can add an import for the new file.
const LaunchRequestHandler = require('./handlers/LaunchRequestHandler.js');
For the skill described in our article, I have created a new unit test for the LaunchRequestHandler in the lambda/test/LaunchRequestHandler.test.js file.
Our simple unit test checks that it can handle the intent, and the speech output matches what we expect Alexa to say when the skill is launched:
const LaunchRequestHandler = require('../handlers/LaunchRequestHandler.js');
describe('LaunchRequestHandler', () => {
let speak = jest.fn(() => handlerInput.responseBuilder);
let getResponse = jest.fn(() => handlerInput.responseBuilder);
let handlerInput = {
responseBuilder: {
speak: speak,
reprompt: speak,
getResponse: getResponse
},
requestEnvelope: {
request: {
type: 'LaunchRequest',
}
}
};
it('Process handlerInput object', () => {
expect(LaunchRequestHandler.canHandle(handlerInput)).toEqual(true);
});
it('Check for launch intent message', () => {
LaunchRequestHandler.handle(handlerInput);
expect(handlerInput.responseBuilder.speak).toHaveBeenCalledWith('Welcome, you can say Hello or Help. Which would you like to try?');
});
});
To run the test suite, use the command "npm test" in the terminal. Confirm that the handler is capable of processing the object as the test successfully passed.
Final thoughts
It is possible to switch between Visual Studio & ASK Toolkit and the Alexa Developer Console to make changes to your skill, but it is advisable to choose a preferred development method to avoid confusing error messages.
When developing for Alexa, it's important to note that the developer console uses the development branch of the Git repository, while the ASK toolkit uses the master branch. If switching between these two environments during development, there may be error messages if either branch is not updated. Should this happen, you can pull the latest changes and merge the branches to bring them up to date.
Sticking to a consistent development environment can increase your productivity by eliminating the need to deal with source control issues.
Getting started with Alexa: Integrating documents created in the APL authoring tool or APL Ninja with your Lambda function
Grow your business on Alexa
