Test Your Skill

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

Options for testing your skill

You have multiple options for testing a new skill in development:

  • Utterance profiles – Use utterance profiles to test your custom interaction model. You can enter utterances and see how they resolve to the intents and slots before you write the code for your service.
  • Skill simulator – Use the simulator provided on the Test page in the developer console. This gives you access to most Alexa Skills Kit features without a device. Interact with Alexa with either your voice or text.
  • Alexa device – Test with an Alexa-enabled device.
  • Alexa app – You can test your skill with the Alexa app for Android/iOS.
  • ASK Command Line Interface (CLI) – Use the ASK CLI to test the skill from the command line. You can test your skill by using ASK CLI commands such as invoke-skill and simulate-skill. For more details about managing skills from the command line, see ASK CLI Quick Start.
  • Skill Management API – Use the skill testing features of the Skill Management API.

Minimum skill configuration

To enable your skill for testing, complete the minimum required configuration for the interaction model included in your skill. 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 aren't required to configure an endpoint for this testing.

For full end-to-end testing, complete the following configuration:

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 can't use this configuration when you publish the skill to users.

Depending on your the testing requirements for your skill, fill out the appropriate sections on the Build page:

  • Custom > Interfaces: If your skill uses any of the device interfaces, enable them on the Build page.
  • Account Linking: If your skill uses account linking, configure it here.

    Note that the full account linking configuration isn't required to test intents that don't require authentication. However, you must 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: Provide a valid AWS Lambda ARN endpoint. At a minimum, fill in the Default Region field.
  • Account Linking: Complete all required fields on the page.
  • Permissions: Enable Send Alexa Events permission, if your skill uses this permission.

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

Video

  • Video > Video Skill Service Endpoint: Provide a valid AWS Lambda ARN endpoint. At a minimum, fill in the Default Region field.
  • Account Linking: Complete all required fields on the page.

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: Your service is an RSS or JSON feed. For more details, 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 you haven't enabled testing for this skill, locate the Test is disabled for this skill option with the drop-down selection set to Off. From the drop-down list, select either Development or Live as your skill testing stage.

  • If you have already enabled testing, from the Skill testing is enabled in: list, select either Development or Live as your skill testing stage, or select Off to disable testing.

A skill can only be in one stage at any time. For example, enabling your skill for testing in the Live stage correspondingly disables your development skill for testing, and your live skill continues 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 redirects to the live stage URL and resets all session and context information. If you have any information you want to preserve, save it before proceeding. This activity generates 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, this stage of enablement uses that live version.

You can use the Test page to test most functionality in a skill, including multi-turn interactions, 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 the simulator 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 manual JSON to enter a JSON request directly and see the JSON response your skill returns.

This option doesn't maintain the skill session and is similar to testing a JSON request in the Lambda console.

Note that the Device Display and Device Log options aren't 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

Enter plain text or [SSML][ssml_ref] 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 doesn't 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 doesn't time out the way a device would, to give you more time to enter your responses during 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 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. For details about testing APL skills in the simulator, see Test APL Skills in the Developer Console Simulator.

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 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 details, 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.5"
            }
          }
        }
      }
    }
  }
}

Test on different devices with screens

You can use the simulator to test skills that display content on devices with screens. For details, see Test APL Skills in the developer console Simulator.

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 doesn't render the audio playback, but the Skill I/O section shows the AudioPlayer directives sent from your skill.

Because the playback doesn't occur, you can't test AudioPlayer requests that are triggered by events in the playback, such as PlaybackNearlyFinished.

AMAZON.DATE slot values

When you type test utterances, don't use date abbreviations, such as "4/15/2019." Instead, write out the date as you would say it.

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", don't resolve 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 a user 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 might look on different devices. However, this doesn't show how your responses would display on any other devices, such as Fire TV.

Flash briefing skills

The Alexa Simulator doesn't support testing Flash Briefing skills.

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

Alexa sends these requests to a skill when a user interacts with controls, such as a remote control. You can't test these requests with the Alexa Simulator.

Progressive responses

The simulator plays the progressive response and the full response in the same audio stream when the full response is ready. This means that you hear the progressive response followed by the full response.

Alexa Reminders API

The simulator doesn't provide the reminders expected from the skill.

Alexa Timers API

The Timers API isn't supported through the simulator.

Reprompt

The simulator doesn't re-prompt 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 Alexa settings for a user. However, if you attempt to query the Alexa Settings API by using the deviceId and apiAccessToken values generated by the Alexa simulator, you can only retrieve the time zone value. If you attempt to retrieve the distance measurement unit or the temperature measurement unit, Alex returns 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 details, see Debug Your Smart Home Skill.

VideoApp directives

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

Web API for Games

The Alexa Simulator doesn't support testing the Alexa.Presentation.HTML interface and the Alexa Web API for Games.

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

You can test the skill, but the Alexa Simulator doesn't 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 to list the intents that Alexa 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 your skill on an Alexa device with your developer account

To test your skill with an Alexa-enabled device (such as an Amazon Echo), register the device with the same email address you used to sign up for your developer account on the Amazon Developer Portal. Make sure that the locale of your device matches at least one of the locales available for your skill. You can then invoke your skill with the wake word and your invocation name: "Alexa, open <invocation name>."

If you configure your device 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][echo_household] feature.

Test with the Alexa app

Another testing option is to use the Alexa app installed on your iOS or Android mobile device to test your skill.

Make sure that the locale of your Alexa app matches at least one of the locales available for your skill. For example, if your skill has the en-US locale, set your Alexa app to English (United States).

To set the locale for your Alexa app

  1. Open the Alexa app on your mobile device.
  2. Navigate to More > Settings > Alexa on This Phone.
  3. Set the language under Language to the locale for your skill.

Custom skills:

Flash briefing:

Smart home:

Video:

Developer console: