Test with the Alexa Simulator

Note: Sign in to the developer console to build or publish your skill.

You can test your skill without a device by using the Alexa simulator in the Alexa developer console. The simulator maintains the skill session with your skill so that you can test the entire skill flow. You can use voice or text to interact with your custom or smart home skill. To preview your Alexa Presentation Language (APL) experiences across a variety of device shapes, use the simulator to render APL responses. You can save the simulator session to a file and reply the session at a later time.

For details about other simulation tools, see the following references:

Prerequisites

Before you test a skill in the simulator, you must meet the following prerequisites:

(For custom skills only) Build your interaction model without errors.
Configure a valid endpoint and deploy your skill code to your endpoint.
Enable your skill for testing.
(For smart home and video skills) Before you start testing, enable the skill in the Alexa app and complete any required information.

Simulator testing options

The following simulator testing options are available:

Skill I/O – (For custom skills only) To view the JSON request and response payloads Alexa sends for each turn of the interaction. Click a speech bubble to see the JSON related to that turn.
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.
Device Log – (For custom skills only) To see the events sent to Alexa and the directives sent to the device during the skill interactions. For details, see Intent Debugging.
Personalization – For custom skills that include personalization features, to create user profiles to test different permission configurations and toggle consent.
Alexa Smart Home (Beta) – (For smart home skills only) To see the ChangeReport events that the skill sends to the Alexa event gateway. For more details, see Debug Your Smart Home Skill.

Use the simulator in the developer console

The simulator is available on the Test page of the developer console. In the simulator pane, you can use voice or text to interact with your skill. In the viewing pane, you can see the results of the simulation based on the testing options that you select.

The following diagram shows a simulation with the Skill I/O and Device Display options selected.

Screenshot of the Test page — Test page on the developer console for a custom skill

Test your skill with the simulator

Complete the following steps to test your skill in the simulator. You can use voice or text to interact with your skill.

To open the developer console simulator

Sign in to the Alexa developer console.
From the skill list, locate your skill, and then, in the dropdown under ACTIONS, select Edit.
Open the Test page.
To test with voice, in the Will you allow developer.amazon.com to use your microphone? pop-up, select Allow.
If you have already enabled testing, the console shows Skill testing is enabled in. From the drop-down list, select Development or Live for your skill testing stage.
To display the simulator, click the Alexa Simulator tab.
Enable the simulator options applicable to your skill type.
To choose the language to test, in the drop down, select the language.
In the simulator pane, type your test utterances.
Or, to use voice, click and hold the microphone, and then speak your test utterances.
If you enabled Skill I/O, you can view the JSON input and output in the Skill Invocations pane.
If you enabled Device Display, to see how the content looks on a device with a screen, scroll down past the Skill Invocations section.
To change the display size, select a device from the drop-down.
If you enabled Device Log, to view the directives and events, scroll down to the Device Log pane.

Note: To give you more time to enter your responses during testing, the skill session doesn't time out the way a device would. To close your skill session, say Alexa, stop.

When you test a custom skill with the simulator, the context.System.device.supportedInterfaces property reflects the interfaces that you 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 the following context object that indicates the request came from a device that supports both interfaces:

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

Simulator limitations

Note: The simulator isn't supported for use in multiple browser tabs at the same time.

The following limitations apply to voice and text testing in the simulator.

Feature	Alexa simulator support
`AudioPlayer` interface	The 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 fifteenth, twenty nineteen" "fifteenth of april, twenty nineteen" "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 Settings API	In general, the Device 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 Device 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 `HTTP 204 No Content` error. In addition, the Device Settings API lets you request address information associated with a user device. When testing with the Alexa Simulator, your skill can call the Device Settings 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 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 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.
Reminders API	The simulator doesn't provide the reminders expected from the skill.
Reprompt	The simulator doesn't re-prompt the user after the interaction is over, as Alexa devices do.
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 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 simulator doesn't support testing the Alexa.Presentation.HTML interface and the Alexa Web API for Games.
Devices with character displays	You can test the skill, but the simulator doesn't show how the response looks on a character display, such as the Echo Dot with clock.

Intent debugging

In the 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.

Troubleshooting simulator issues

Issue: Simulator doesn't return a response

Symptoms

The simulator shows a spinner, but doesn't return a response.

Try this

To resolve the issue, try the following actions, and then retry testing in the simulator:

Clear the cache and cookies in your browser.
Disable your VPN connection, if applicable.
Disable anti-virus software installed on your PC or Mac.

Was this page helpful?

Provide feedback

Last updated: May 01, 2024