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

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

  1. Sign in to the Alexa developer console with the developer account for the Smart Home skill you want to test.
  2. Open the Customer Details page and note your customer ID. You need your customer ID, not your vendor ID.
  3. Open the Alexa Developer Contact Us.
  4. For Type, choose Alexa Skill Building.
  5. For Category, choose Testing & Simulation.
  6. For Subject, enter Requesting access to the state reporting test tool.
  7. 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

  1. Log into the web-based Alexa app for your region. The following is the list of regions and the corresponding URLs:

  2. In the app, locate your skill.
    1. Choose Skills, and choose Your Skills in the upper right corner of the skills page.
    2. Scroll to DEV SKILLS and find your skill.
  3. 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

  1. In the Alexa app, choose Smart Home and then Devices.

  2. 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 a StateReport, False if the value was last set by a proactive report such as a ChangeReport

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 a ChangeReport to populate the cache.

  • Make sure you set proactivelyReported to true for all of your device's properties, and that you report all properties in your ChangeReport events.

  • If you implement the EndpointHealth interface, include the connectivity property in your StateReport and ChangeReport 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 that DeepQuery: False and that the expected property values appear.

  • If you implement the EndpointHealth interface, verify that you are reporting the connectivity property correctly in your ChangeReport 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.

  • 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 sending ChangeReport events for each Amazon account.

  • 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.

Amazon Alexa
Amazon Appstore
Amazon Web Services
Amazon Dash Replenishment