Test and Debug Your Custom Skill

Follow these recommendations to test custom skills. Before you start testing, complete the steps to verify the minimum configuration and deploy your skill.

General testing recommendations

  • Test your invocation name. Make sure it's easy to say and consistently recognized by Alexa. Consider changing the name if Alexa frequently fails to recognize it. For details about invocation names, see Choose Your Invocation Name.

  • Test all the different sample utterances in your voice interface.

  • Test variations of the sample utterances with different slot values and slightly different phrases. Pay extra attention to sample utterances that are very similar.

  • Make sure your service responds properly to the different types of requests sent by Alexa:

    • LaunchRequest
    • IntentRequest
    • SessionEndedRequest

  • Make sure that all your intents can be correctly triggered from your sample phrases and variations on those phrases. For details about defining your intents and sample utterances, see:

  • If your skill includes visual and touch interactions, make sure that the display appears correctly and that each touch interaction invokes the desired intent.
  • Review the detail page for the skill in the Alexa app (under the Skills option). Make sure the icon, description, example phrases, and other fields provide meaningful information to help users understand the capabilities you're adding to Alexa.
  • If you can observe other users during testing, note the phrases that they speak to invoke each intent and update the sample utterances accordingly.
  • Specifically test the example phrases that you provided in the developer portal. These phrases are the ones that new users try first. You want to be sure that they work well.

For detailed testing you should do before submitting the skill for certification, see Skill Certification Testing.

Test your interaction model

After you save and build your custom voice interaction model, you can test and improve your custom voice interaction model with the utterance profiler. You aren't required to configure an endpoint or complete minimum configuration to use the utterance profiler.

Verify the minimum configuration

To test the end-to-end flow of your custom skill, you must complete the minimum configuration for a skill that uses a custom voice interaction model. Use the left-hand navigation of the Build page in the developer console to navigate to the configuration item.

Build page menu item Skill requirements

CUSTOM

A valid custom voice interaction model. You must define the following items for your interaction model:

  • An invocation name specified in Invocations > Skill Invocation Name
  • At least one intent with sample utterances defined in Interaction Model > Intents
  • If any of your custom intents include slots, define slot types in Assets > Slot Types

The model must build without errors.

CUSTOM > Endpoint

A valid AWS Lambda ARN or HTTPS endpoint. You must define the following items for your endpoint:

CUSTOM > Interfaces

(Optional) Enable the device interfaces that your skill uses, if any.

ACCOUNT LINKING

(Optional) If your skill uses account linking, configure it here.

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

(Optional) If your skill requires permissions, enable them here.

Deploy your skill code

After you verify the minimum configuration for the skill in the developer console, deploy your skill code for your cloud-based service. You can do either of the following:

Enable your skill in the developer console

Complete the steps to enable your skill for testing in the developer console.

Test slots for user errors

For intents that include slot values, test different permutations, such as missing or incorrect values. If you use any of the built-in slot types, such as AMAZON.DATE, AMAZON.NUMBER, or AMAZON.DURATION, verify that your code responds appropriately if the words that the user says for those slots can't be converted to the specified data type.

For example, a skill that adds two numbers provided by the user might have an intent that defines two AMAZON.NUMBER slots and a sample utterance similar to this:

NumberAddIntent add {xValue} and {yValue}

Test this phrase with non-numeric words for the xValue and yValue slots. Verify that your skill provides an appropriate response, such as a response letting the user know that the device didn't hear numeric data.

Similarly, if a slot should always contain a value from a fixed set of values, verify that your skill responds correctly if the slot provided by the user isn't in this set. For example, "Daily Horoscopes" might expect a valid Zodiac sign in the Sign slot. Verify that your skill provides a user-friendly error message if the Sign slot contains a value that doesn't match any Zodiac signs.

For recommendations about how to respond to unexpected input and dialog errors, see the section on errors in the Alexa Design Guide.

Use the Alexa app when testing

The Alexa app is a companion app available for Fire OS, Android, iOS, and web browsers (http://alexa.amazon.com/). This app provides two different tools that can be useful when testing:

  • The home page "cards". These are normally used to give users a visual response in addition to the spoken response from an Alexa skill. For example, when a user asks Alexa for the weather, the detailed forecast is provided on a visual card.
  • The Alexa history. This records every spoken interaction with Alexa, regardless of whether the correct intent was triggered. The history can be useful for seeing exactly how Alexa interpreted an utterance and for tracking down problems in your voice interface.

Note that you must log in to the Alexa app with the same account to which your device is registered:

  • For Fire OS devices, the Alexa app is automatically logged in to the same Amazon account to which the device is registered.
  • For iOS, non-Amazon Android devices, and web browsers, Amazon prompts you to log in the first time you launch the app. To switch between accounts, click Settings, then Log Out.

Alexa app cards

To see the cards, open the Alexa app, and then open the main menu. From the menu, navigate to Activity.

You have control over the home page cards returned by your service. During the early stages of development, you might want to send back these cards from all LaunchRequest and IntentRequest requests. You can include basic debugging information, such as the name of the triggered intent, to help you see how your service is working. Later, as you prepare your skill for end users, you can return cards that are more relevant to a normal end user's experience.

In addition to the cards you control, Alexa sends back cards in response to errors communicating with your service. Some common errors (note that this is not a complete list):

Error Card Possible Causes
Unexpected Communication Issue Occurs if Alexa cannot connect to your service to send a request. This can happen for many reasons:

The endpoint specified in the configuration on the developer portal is incorrect.
The web service is not online.
The endpoint is not configured to accept traffic over port 443.
SSL Handshake Failed Occurs if SSL is configured incorrectly. For example, when you use a self-signed certificate, if the public key in the certificate presented by your endpoint does not match the key provided in the configuration in the developer portal, this error occurs.
Protocol Violation Occurs if your service's response did not conform to the specification. Often this is due to an error in your code – for example, if your service throws an unhandled exception and exits, the response received by Alexa will not be correct.
Hostname verification failed Occurs if the domain name specified for the DNS.1 setting in your certificate does not match the domain name of your endpoint.

Make sure the domain name specified in the configuration file for your certificate matches exactly. Do not include the protocol (https://) or any trailing slash marks.

For example, if your service's endpoint is at https://wiseguy.mywebserver.com/wiseguy, the DNS.1 entry for your certificate should be set to

wiseguy.mywebserver.com
Unrecognized Name while starting SSL handshake Occurs when using an older version Apache HTTP Server to host your web service and the server is not configured with a ServerName or ServerAlias.

To resolve this, either upgrade to 2.4.10 or later, or add ServerName / ServerAlias to your server's configuration file.

Alexa app history

The Alexa app also provides a complete history of a user's interactions. Each history item shows the text that resulted from the user's speech.

To see the history, open the Alexa app and open the main menu. From the menu, navigate to Settings > Alexa Account > History.

Viewing how Alexa converted the speech to text is especially useful when your service doesn't respond as expected, for example:

  • Your service didn't receive any request because Alexa misunderstood the invocation name.
  • The intent sent to your service wasn't what you expected.
  • The intent sent to your service is correct, but contains unexpected slot data.
  • No intent was sent to your service because Alexa misunderstood the user's command.

Other testing and debugging tools

Log files are another useful option when testing, especially for catching problems that prevent your service from sending a response.

Was this page helpful?

Last updated: Sep 10, 2024