Test and Debug Your Smart Home Add-on

---

Use the following methods and tools to help you test and debug state and other events as you build your smart home add-ons.

• Alexa Automated Testing Service – Create test plans using natural language rather than complex JSON definitions. You can choose pre-built templates or build custom test plans that meet your specific requirements.

• View Device State – View the current values of all properties of smart home devices that associated with your add-on and your developer account, and whether the current value came from a StateReport request or proactive state update, such as ChangeReport.

• Smart Home Debugger – View the ChangeReport, AddOrUpdateReport, and DeleteReport events that Alexa receives from your add-on, including your JSON, and any processing errors.

• Smart Home Debugger for WebRTC Add-ons – If you implement the Alexa.RTCSessionController interface in your Alexa add-on, use the Smart Home debugger to see logs from your WebRTC sessions in real-time.

• Smart Home Test Tool – Run automated tests that send directives to your add-on and verify that you set the state correctly. Available for the most common Alexa capability interfaces.

• Alexa Simulator – Test your add-on without a device by using the Alexa simulator in the Alexa developer console.

• Smart Home Evaluation REST API Reference – Use the Smart Home Evaluation REST API to start evaluations and get evaluation results programmatically.

• Alexa Skills Kit (ASK) Command Line Interface (CLI) – Use the create-smarthome-capability-evaluation command to create and start a capability evaluation.

Verify the minimum configuration

To test the end-to-end flow of your add-on, you must complete the minimum configuration for a smart home add-on. Use the left-hand navigation of the Build page in the developer console to navigate to the configuration item.

• In SMART HOME, you must define the following items for your smart home add-on:
  • Version v3 of the Smart Home API
  • A valid AWS Lambda ARN service endpoint
    A smart home add-on can include multiple models. Specify the endpoint for the custom and smart home models.
• In ACCOUNT LINKING, configure the required fields.
• If your skill supports events, such as ChangeReport, in PERMISSIONS, enable Send Alexa Events.

To test and publish your skill, you need an account configured for your device cloud and discoverable devices for that account.

Deploy your add-on code

After you verify the minimum configuration for the skill in the developer console, deploy your skill code Lambda function. For details, see Add a Lambda Function.

Make sure that you deploy your Lambda function in the AWS region associated with the skill language and locale. Otherwise, device discovery might succeed for one language version of the skill and fail for another language. For more details, see Deploy your Lambda function to multiple regions.

Enable your add-on in the developer console

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

Enable your add-on in the Alexa app

Complete the following steps to enable your add-on in the Alexa app installed on your iOS or Android mobile device.

To enable your add-on and discover devices

1. Sign in to the Alexa app with the same credentials as your developer account.
2. If you have Alexa+, follow these instructions to find your add-on in the Alexa app.
   1. Tap the three lines menu.
   2. Under More, tap Alexa+ Store.
   3. Scroll down, and then tap Browse Alexa Skills and Games.
3. Or, if you have the standard version of the Alexa app, follow these instructions to find your skill in the Alexa app.
   1. Tap the three lines menu.
   2. Tap Skills and Games.
4. Scroll the skill types to the right, and then tap Dev.
5. Scroll to find your add-on.
6. Tap on your add-on name, and then tap ENABLE TO USE.
7. Follow the prompts to enter your credentials for your device cloud account.
8. To allow access to the add-on, tap Allow, and then tap CLOSE.
   Note: If you're unable to complete account linking, make sure that you use valid credentials for your device cloud account. Otherwise, there might be an issue with the account-linking information that you provided in the developer console. For help with account-linking issues, see Troubleshooting Account Linking.
9. After the add-on is enabled and linked, Alexa sends a Discover request to your add-on to learn about the connected devices. Your add-on returns the discovery response with details about the devices.
10. If Alexa can't discover your device, check the logs for your Lambda function. Use the logs to troubleshoot the issue. Common issues include incorrectly formatted discovery responses.

If you make changes to the account linking configuration or your discovery response, disable your skill in Your Skills.

Related topics

• Test your skills behind a firewall
• Test Skills in the Alexa Developer Console
• Skills Beta Testing for Alexa Skills
• Define Skill Store Details for Publication
• Steps to Build Smart Home Add-ons
• Works with Alexa Overview

---

---

Last updated: May 13, 2026