Test Your Skill

This document describes the steps to test your skill during development.

Ways to Test an Alexa Skill

During development, there are multiple options for testing a new skill:

Regardless of how you test, you need to provide the minimum configuration data and deploy your skill service.

Minimum Skill Configuration

To enable your skill for testing, you need to complete the minimum required configuration for the interaction model included in your skill. All of these settings are available on the Build page.

Custom Model Minimum Configuration

You can test your custom interaction model with the utterance profiler after you successfully save and build your model. You do not need to configure an endpoint for this testing.

For full end-to-end testing, complete the configuration described below.

Section Requirement

Custom > Interaction Model

The interaction model must have:

  • An invocation name specified in Invocation > Skill Invocation Name
  • At least one intent with sample utterances defined in Intents
  • Slot Types (if any of your custom intents include slots)

The model must build without errors.

Custom > Endpoint

A valid AWS Lambda ARN or HTTPS endpoint.

  • At a minimum, fill in the Default Region field.
  • For HTTPS, be sure to indicate the SSL certificate type. For testing purposes, you can use a self-signed certificate, although you cannot use this configuration when you publish the skill to users.

Depending on your skill and what you need to test, you may also need to fill out these sections on the Build page:

  • Custom > Interfaces: If your skill uses any of the device interfaces, enable them on this page.

  • Account Linking: If your skill uses account linking, configure it here.

    Note that the full account linking configuration is not required to test intents that do not require authentication. However, it is required to test any intent that returns a LinkAccountCard or that requires authentication.

  • Permissions: If your skill uses any permissions (such as for the Device Address API), enable them here.

Pre-built Model Minimum Configuration

Model Required Fields

Flash Briefing
  • Flash Briefing > Custom Error Message
  • Flash Briefing: All required fields for at least one feed must be complete:
    • Preamble
    • Name
    • Content update frequency
    • Content type
    • Content genre
    • Feed
    • Feed icon

Smart Home
  • Smart Home > Smart Home Service Endpoint: A valid AWS Lambda ARN endpoint must be provided. At a minimum, fill in the Default Region field.
  • Account Linking: All required fields on this page must be complete.
  • Permissions: If your skill uses Send Alexa Events permission, it must be enabled on the Permissions page.

You also need an account configured for your device cloud and discoverable devices for that account.

Video
  • Video > Video Skill Service Endpoint: A valid AWS Lambda ARN endpoint must be provided. At a minimum, fill in the Default Region field.
  • Account Linking: All required fields on this page must be complete.

Deploy Your Skill Code

Before you can test your skill, you must configure the minimum required data for the skill in the developer console and deploy the code for your cloud-based service. How you deploy your service depends on the interaction model included in the skill:

Model Skill Service Hosting Options

Custom

You can do either of the following:

Flash Briefing

N/A: In this case, your service is an RSS or JSON feed. See Flash Briefing Skill API Feed Reference.

Smart Home

You must use an AWS Lambda function. See the Add a Lambda Function section in Steps to Build a Smart Home Skill.

Video

You must use an AWS Lambda function. See the Add a Lambda Function section in Steps to Create a Video Skill.

Test Your Skill in the Developer Console

The Test page includes a simulator that lets you test your skill without a device. When you are ready to test the skill, navigate to the Test page.

If testing has not been enabled for this skill, then you will see Test is disabled for this skill, with the drop-down selection set to Off. From the drop-down list, select the desired skill testing stage, which will be either Development or Live.

If testing has been enabled already, then from the Skill testing is enabled in: list, select the desired skill testing stage, which will be either Development or Live, or select Off to disable testing.

A skill can only be in one stage at any time. For example, if you enable your skill for testing in the Live stage, your development skill will be disabled for testing, and your live skill will continue to be available in the developer console, SMAPI, ASK CLI and your devices that are signed in to your developer account. As part of this enablement in the developer console, the page will be redirected to the live stage URL and all session and context information will be reset. If you have any information you want to preserve, save it before proceeding. This activity will also generate a new User ID and can be used to simulate a first-time user experience. If your live skill is configured with a live lambda version, that live version will be used as part of this stage enablement.

You can use the Test page to test most functionality in a skill, including dialogs, progressive responses (with limitations), and entity resolution.

The page provides three tabs on the left for different types of testing.

Tab Description

Alexa Simulator

(Custom skills and smart home skills)

Use this to interact with a custom or smart home skill with either text or your voice. The simulator maintains the skill session with your skill just as a device would, so you can test the dialog flow. The simulator also sends any cards that your skill returns to the Alexa app the same way a device would. If your skill supports multiple languages, select the language you want to test from the drop-down list.

For more details, see later sections:

Manual JSON

(Custom skills only)

Use this to enter a JSON request directly and see the JSON response your skill returns.

This option does not maintain the skill session. This is very similar to testing a JSON request in the Lambda console.

Note that the Device Display and Device Log options are not supported for Manual JSON.

If your skill supports multiple region-specific endpoints, you can select the endpoint to test from the list near the bottom of the page.

Voice & Tone

Use this to enter plain text or SSML and hear how Alexa speaks the text. Select the language you want to hear from the list at the bottom. All supported languages are available in this list, even if your skill does not support them.

Use the Alexa simulator with custom and smart home skills

You can interact with the simulator with either text or voice. Note that the skill session does not time out the way a device would, to give you more time to enter your responses while testing. If your skill keeps the session open, you can close it with "Alexa, stop."

Enable Skill I/O to see the JSON sent to your skill and the JSON returned to Alexa for each turn of the conversation. Note that the JSON is only available for custom skills. Click on a speech bubble to see the JSON related to that turn.

Enable Device Display to see an approximation of how the skill displays on devices with screens. See Test on different devices with screens, later for more details.

Enable Device Log to see the events sent to Alexa and the directives sent to the device during the skill interactions. See Intent Debugging.

Enable Echo Buttons to display and interact with simulated Echo Buttons. This option is only available to skills that support the GameEngine interface, the GadgetController interface, or both. For more information, see How to Test an Echo Button Skill.

Enable Alexa Smart Home (Beta) to see the ChangeReport events that the skill sends to the Alexa event gateway. This option is only available to smart home skills. For more information, see Understand State and Change Reporting and Debug Your Smart Home Skill.

When you test a custom skill with the simulator, the context.System.device.supportedInterfaces property reflects the interfaces you have selected on the Custom > Interfaces page. For example, if you selected AudioPlayer and Alexa Presentation Language, a request sent to your skill from the simulator includes this context object, indicating that the request came from a device that supports both of these interfaces (full set of properties excluded for brevity):

{
  "context": {
    "System": {
      "device": {
        "deviceId": "amzn1.ask.device.1",
        "supportedInterfaces": {
          "AudioPlayer": {},
          "Alexa.Presentation.APL": {
            "runtime": {
              "maxVersion": "1.3"
            }
          }
        }
      }
    }
  }
}

Test on different devices with screens

You can select different types of devices from the drop-down list below the Skill I/O section. The selected device determines the data provided in the context.Viewport property in the request sent to your skill.

Test how an APL skill looks on a medium hub
Test how an APL skill looks on a medium hub

The available devices correspond to the viewport profiles available in the viewport profiles package for use in an Alexa Presentation Language (APL) document:

  • Small Hub (Round)
  • Small Hub (Landscape)
  • Medium Hub
  • Large Hub
  • Extra Large TV

For more about the properties of these viewports, see Alexa Viewport Profiles Package.

You can also create custom device profile for testing. This is useful for testing how your skill looks on other types of devices. You can also use a custom profile to test how your skill works on a device with a screen that does not support video playback.

To create a custom device:

  1. Click the drop-down list to open the list of standard viewports.
  2. Scroll to the bottom of the list and click Add Custom Device.
  3. Change the properties of the viewport that you want to view. You can set the Shape, Pixel Width, Pixel Height, and Pixel Density. You can also select the specific Video Codecs the device supports, or Disallow Video to create a device that does not support video playback at all.
  4. Click Apply.

The custom device remains available during your current browser session. If you close the browser and then later re-open the authoring tool, you need to re-create the custom device.

Alexa Simulator limitations

The following limitations apply to voice and text testing on the Alexa Simulator tab.

Feature Alexa Simulator Support

AudioPlayer interface

The Alexa Simulator does not render the audio playback, but the Skill I/O section shows the AudioPlayer directives sent from your skill.

Since the playback does not occur, you cannot test AudioPlayer requests that are triggered by events in the playback, such as PlaybackNearlyFinished.

AMAZON.DATE slot values

When you type test utterances, do not use date abbreviations such as "4/15/2019." Instead, write out the date as it would be spoken.

For example, the following phrases generate a valid date in a date slot:

  • "April 15 2019"
  • "15 of April 2019"
  • "April fifteenth"

Typed values such as "2019-04-15", "4/15/2019", and "4/15" do not resolve correctly to dates.

For more examples of the spoken forms that AMAZON.DATE expects, see AMAZON.DATE. Note that you can use either numerals ("25") or write out numbers ("twenty-five" or "twenty-fifth") when you type utterances to test.

Device Address API

The Device Address API lets you request address information associated with the user's device. When testing with the Alexa Simulator, your skill can call the Device Address API and get back a non-error response. You can also test the flow when the user has not provided the device address permission.

However, note that the address fields in the response are set to null and the postal code field is set to a default US postal code.

The Test page cannot be configured as a full device in the Alexa app.

Display interface

You can test skills that use the Display interface, and you can enable the Device Display option to see an approximation of how your responses will look on different devices. However, this does not show how your responses would display on any other devices, such as Fire TV.

Flash briefing skills

The Alexa Simulator does not support testing flash briefing skills.

GadgetController interface
GameEngine interface

The following limitations apply to Echo Button support in the Alexa Simulator:

  • Skill I/O is available for simulated voice requests and launch requests only.
  • Echo Button colors in the Alexa Simulator might not match the colors rendered on physical Echo Buttons. We recommend that you test colors on physical Echo Buttons before publishing your skill.

Location Services

With Location Services, your skill can request dynamic location information associated with the user's device. When testing with the Alexa Simulator, your skill can test the flow when the user has not provided location services permission.

However, the simulator cannot test the case where the customer has granted permission.

The Test page cannot be configured as a full device in the Alexa app.

PlaybackController interface

These requests are sent to a skill when a user interacts with controls such as a remote control. These requests cannot be tested with the Alexa Simulator.

Progressive responses

The progressive response and the full response are played in the simulator in the same audio stream once the full response is ready. This means you will hear the progressive response immediately followed by the full response.

Alexa Reminders API

The simulator will not provide the reminders expected from the skill.

Alexa Timers API

The Timers API is not supported through the simulator.

Reprompt

The simulator will not reprompt the user after the interaction is over, as Alexa devices do.

Alexa Settings API

In general, Alexa Settings API allows you to retrieve the time zone, distance measurement unit, and temperature measurement unit from the customer's Alexa settings. However, if you attempt to query the Alexa Settings API using the deviceId and apiAccessToken values generated by the Alexa simulator, you will only be able to retrieve the time zone value. If you attempt to retrieve the distance measurement unit or the temperature measurement unit, you will get an "Error 204 No Content" error message.

Smart home live debugger

The smart home live debugger is in beta and is subject to change at any time without notice. For more information, see Debug Your Smart Home Skill.

VideoApp directives

The Alexa Simulator does not render the video playback, but the Skill I/O section shows the VideoApp directives sent from your skill.

Devices with character displays (such as the Echo Dot with clock)

You can test the skill, but the Alexa Simulator does not show how the response would look on a character display.

Intent Debugging

In the Alexa Simulator, the Device Log shows the consideredIntents returned in the JSON response, so you can see the intents that were considered and discarded. You can use this information to perform intent debugging and determine how to use additional samples to train your model to resolve utterances to their intended intents and slots.

Test on an Alexa Device with Your Developer Account

To test with an Alexa-enabled device (such as an Amazon Echo), register the device with the same e-mail address you used to sign up for your developer account on the Amazon Developer Portal. You can then invoke your skill with the wake word and your invocation name: "Alexa, open <invocation name>."

If your device is set up with an account other than your developer account, reset the device and then re-register it with your developer account. See the help for your specific device for details:

If you want to add back a non-developer account as a user of the device, you can do so by using the Household feature.

Custom:

Flash briefing:

Smart home:

Video:

Developer console:

Amazon Alexa
Amazon Appstore
Amazon Web Services
Amazon Dash Replenishment