Use the State Reporting Test Tool
You can use the State Reporting Test Tool to test and debug your Smart Home skill. By using the state reporting test tool, you can view the current values of all properties of Smart Home devices that are associated with your skill and your developer account. You can see where each state value came from, such as a response to a StateReport
request or a proactive ChangeReport
. For more information about other test tools, see Test and Debug Your Smart Home Skill.
Alexa sends a ReportState
directive to request information about the state of an endpoint. When Alexa sends a ReportState
directive, you send a StateReport
event in response. You also proactively report state to Alexa in ChangeReport
events, directive response events, and in error response events. You identify the properties that you proactively report in your discovery response. For more information about state reporting, see Understand State and Change Reporting.
- Prerequisites
- Get access to the state reporting test tool
- Enable your skill in the Alexa app
- View state information
- Troubleshoot change reporting problems
- Additional scenario testing
- Related topics
Prerequisites
To use the state reporting test tool, your Smart Home skill must send ChangeReport
events to Alexa when the properties of your smart device change. Your discovery response must set proactivelyReported
to true
for all properties defined by the interfaces that your device supports. If your skill supports proactive reporting for only a subset of properties, then you cannot use the state reporting test tool.
Get access to the state reporting test tool
Before you can access the state reporting test tool, you must request access from the Alexa team.
To get access to the state reporting test tool
- Sign in to the Alexa developer console with the developer account for the Smart Home skill you want to test.
- Open the Customer Details page and note your customer ID. You need your customer ID, not your vendor ID.
- Open the Alexa Developer Contact Us.
- For Type, choose Alexa Skill Building.
- For Category, choose Testing & Simulation.
- For Subject, enter
Requesting access to the state reporting test tool
. - For Desciption, enter
Requesting access to the state reporting test tool for customer ID <your customer ID>
.
Alexa contacts you when you are granted access to the tool, or for more information.
There are some scenarios, such as households with multiple members, where users control the same device from their separate Amazon accounts. To test that you send ChangeReport
events for all Amazon accounts that enable your skill for the same device, you need multiple test accounts. Repeat the above procedure to request access for a second account to test this scenario.
Enable your skill in the Alexa app
The state reporting test tool is an add-on to the existing web-based Alexa app. Make sure to use the Alexa app for your region, and sign in with the same developer account that you used to request access to the tool.
To enable your skill in the Alexa app
-
Log into the web-based Alexa app for your region. The following is the list of regions and the corresponding URLs:
- United States: alexa.amazon.com
- United Kingdom: alexa.amazon.co.uk
- Germany: alexa.amazon.de
- Japan: alexa.amazon.co.jp
- Canada: alexa.amazon.ca
- Australia: alexa.amazon.com.au
- India: alexa.amazon.in
- Spain: alexa.amazon.es
- France: alexa.amazon.fr
- Italy: alexa.amazon.it
- In the app, locate your skill.
- Choose Skills, and choose Your Skills in the upper right corner of the skills page.
- Scroll to DEV SKILLS and find your skill.
- Choose ENABLE to enable the skill. You are directed to account-link the skill to a device cloud account. If you want to remove account linking later, disable your skill in the Skills tab.
View state information
To view state information
- In the Alexa app, choose Smart Home and then Devices.
-
For each device, you see extended debugging information. The information looks like the following.
Each Capability states line represents a smart device capability interface property. Each line contains the following information:
- Property name and current value of the property
- The timestamp for the current value of the property
- The uncertainty in milliseconds for the current timestamp
- DeepQuery -
True
if the value was last set by aStateReport
,False
if the value was last set by a proactive report such as aChangeReport
Troubleshoot change reporting problems
If you implement change reporting in your skill, you should see DeepQuery: False
for properties in the state reporting test tool to indicate that the values were last set by a ChangeReport
.
If you believe you have properly implemented change reporting, but you see DeepQuery: True
, check the following:
-
If you are working with a newly-discovered device, Alexa's state cache might be empty. Try refreshing the Alexa app in your browser. If you do not send
StateReport
events, send aChangeReport
to populate the cache. -
Make sure you set
proactivelyReported
totrue
for all of your device's properties, and that you report all properties in yourChangeReport
events. -
If you implement the EndpointHealth interface, include the
connectivity
property in yourStateReport
andChangeReport
events. -
Make sure you only report properties that are defined by the interfaces that you support. Do not, for example, report directive parameters as properties. For more information, see the documentation for each interface that your device supports.
-
For skills that implement the ThermostatController interface, cycle through the thermostat modes that your device supports so that Alexa can cache the data.
Additional scenario testing
After you confirm that all of your device's properties appear with DeepQuery: False
, test all of the scenarios for your device that trigger ChangeReport
events. For each scenario, make sure that the expected property values appear in the state reporting test tool.
The following are examples of some scenarios that you could test.
-
Change your device state without using Alexa. For example, use another application or the physical device controls to turn a device on or off, or change its settings. This should cause your skill to send one or more
ChangeReport
events to Alexa. In your browser, refresh the Alexa app to confirm thatDeepQuery: False
and that the expected property values appear. -
If you implement the EndpointHealth interface, verify that you are reporting the
connectivity
property correctly in yourChangeReport
events. Remove the power or power source from your device and wait for the device's health polling or heartbeat interval to pass. When your skill reports that the connectivity has changed, refresh your browser and check the Alexa app. Then restore power to the device and check the Alexa app again.Note: There is a known issue with the tool that occurs when you are testingEndpointHealth
and the skill response is an error. When the tool receives anErrorResponse
, it displays Failed to retrieve state with no additional information. Until this issue is resolved, you should validate this scenario by checking your logs to make sure you are sending the appropriate JSON response and error codes. -
Make sure that you send
ChangeReport
events for all Amazon accounts that have enabled and account-linked your skill, not just the first, or most recent accounts. Commonly, customers in the same household share Smart Home devices but have their own Amazon accounts associated with the skills for those devices.The state reporting test tool enables you to see information about the Smart Home devices associated with your skill only in the Amazon account that you use to sign in to the Alexa developer console. The tool doesn't show information from other Amazon accounts. To test this scenario, enable and account-link the skill from different Amazon accounts using the same device credentials. Then change the state of the device without using Alexa. Sign in with each Amazon account, then use the state reporting test tool to confirm that the property states are accurate and that
DeepQuery: False
. This helps confirm that your skill is correctly sendingChangeReport
events for each Amazon account.Note: If you receive a403 Forbidden
response when you send aChangeReport
event to Alexa, this indicates that the user has disabled your skill and you can stop sending messages for that user. -
Inspect your log responses to make sure that you are sending
ChangeReport
events to Alexa correctly.
If you encounter problems with the state reporting test tool, use the Alexa Developer Contact Us page to let us know.