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.
- 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
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
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:
- 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 -
Trueif the value was last set by a
Falseif the value was last set by a proactive report such as a
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
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
StateReportevents, send a
ChangeReportto populate the cache.
Make sure you set
truefor all of your device's properties, and that you report all properties in your
If you implement the EndpointHealth interface, include the
connectivityproperty in your
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.
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
ChangeReportevents to Alexa. In your browser, refresh the Alexa app to confirm that
DeepQuery: Falseand that the expected property values appear.
If you implement the EndpointHealth interface, verify that you are reporting the
connectivityproperty correctly in your
ChangeReportevents. 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 testing
EndpointHealthand the skill response is an error. When the tool receives an
ErrorResponse, 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
ChangeReportevents 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 sending
ChangeReportevents for each Amazon account.Note: If you receive a
403 Forbiddenresponse when you send a
ChangeReportevent 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
ChangeReportevents to Alexa correctly.
If you encounter problems with the state reporting test tool, use the Alexa Developer Contact Us page to let us know.