Test your service on Sonos

Overview

This document explains how you can test Sonos on your system while developing. It also goes over the automated self-test you must perform before we can begin validating your service for inclusion on Sonos. The sections below describe:

  • Adding your service to a player and performing tests by using the Sonos app and SoapUI. See Test your service on your Sonos system and Test your service manually for details.
  • Using the automated tests in the Python Self-Test Suite. We need partners to run these tests on their SMAPI implementation and you must include a clean run with your submission. See Run the automated self-test before submitting your service for details. 
  • Reading the self-test output files and finding out what went wrong, as well as a list of known issues with the self-test. Read the known issues before testing, especially if you plan to use a Mac computer for testing. See Debugging the self-test and known issues  for details.

Use CustomSD to Test your service on your Sonos system

Use the custom service descriptor page on a player (customSD.htm) to add your SMAPI service to your Sonos system for testing. The capabilities on this form mirror the capabilities that you can make for your service in the Technical Configuration & Test Setup section of your service application in the Version Manager. See Capabilities for details.

To add your service to your Sonos system:

  1. Find the IP address of one of your players. See Check my Sonos ID and which version my Sonos system is running for details.
  2. Enter this URL into a web browser:
    http://{IP address of Sonos player}:1400/customsd.htm
  3. Fill out the form with information that is relevant to your service and click Submit (see below for details).
  4. On your Sonos app, select Add Music Services and add your service.

General items

General items on the Custom SD page.

Form field Description
SID An internal identifier for Sonos firmware. Valid values are 240-253, and 255 inclusive.
Service Name The name of your service. This name gets on the Add Music Services menu, when browsing, and in the universal search results.
Endpoint URL The non-SSL endpoint for your SMAPI service. Sonos players and apps send requests to this endpoint as well as the secure endpoint. See the SMAPI reference overview for details.
Secure Endpoint URL The SSL endpoint for your SMAPI service. http is required. See TLS/SSL Security Overview for details.
Polling Interval The number of seconds between each Sonos poll request. Sonos firmware leverages the polling technique to check for updates in browse content. See getLastUpdate for details.

Authentication SOAP header policy

Sonos no longer supports new implementations using Session ID or Device Link for authentication. If your implementation currently uses these, you can still choose these options. For example, you may be testing an upgrade to your current service. If you're creating a new service, choose anonymous or application link authentication. The authentication methods are summarized below. See Implementing authentication for details.

Authentication method Description
Session ID Not recommended. Use Application Link for more secure authentication. Session ID enables your service to grant Sonos a session ID, which Sonos then passes back to your service for validation.
Anonymous Sonos will not use any authentication method to access your service, thereby allowing any user access.
Device link This method has been replaced by browser authentication. Choose Application Link and configure browser authentication to enable users to enter their credentials in a web page.
Application link Sonos uses your mobile app or a browser to authenticate the user and authorizes Sonos to use their account in their household.

Strings table

The XML file to use for custom strings and localization. See Strings and Localization for details.

Form field Description
Version The version number of your strings table XML file, which should start at 1. When testing with customSD, you must increment this number for Sonos apps to pick up changes made to your strings table XML file. In production, let your Sonos representative know that we must increment this number.
Uri The URL where your strings.xml file is hosted.

Presentation map

The XML file to use for content display in Sonos apps. Required if you enabled the search capability. See Presentation Map for details.

Form field Description
Version The version number of your presentation map XML file, which should start at 1. When testing with customSD, you must increment this number for Sonos apps to pick up changes made to your presentation map XML file. In production, let your Sonos representative know that we must increment this number.
Uri The URL where your presentation map XML file is hosted. 
Container type The location where the Sonos app displays your service in the Add Music Services menu. If you select “Music Service,” the Sonos app display your SMAPI Service in the top-level list of services in the Add Services wizard.
If you select “Sonos Sound Lab”, the Sonos app for desktop computers displays your service one level below the top-level Add Music Services list in a container called Sound Labs. In the Sonos app for mobile devices, this adds a beta label to your logo in the Service Catalog.

Capabilities

See Capabilities for descriptions of the capabilities.

Test your service manually

Manual tests use the Sonos app to verify portions of your implementation. Perform these tests after adding your service to your Sonos system. You can also use a tool like SoapUI to see the metadata exchange between your service and the Sonos app. We recommend that you run these tests before submitting your implementation. To run them, you will need a Sonos app on a Mac, PC, Android, or iOS device, and at least one Sonos player, such as a PLAY:1. The tests are arranged by feature. Only run the tests that are applicable to your service.

Account management

  • Add a trial account.
  • Add supported accounts.
  • Add an unsupported account.
  • Add a deleted account.
  • Add a supported account that is expired.

Search

  • Verify search in all applicable containers.
  • Verify multi-library search (if applicable).
  • Verify incremental search functionality in all applicable containers. Every new character entered should process a new search.
  • Verify search functionality using special characters and accented characters in all applicable containers.
  • Verify any error messages returned in search results.
  • Verify artwork returned in search results.
  • Verify metadata returned in search results.

Browse

  • Click through to the end of each container. Successful completion requires no browse errors, timeouts, or corrupted data.
  • Verify that browsing happens within a reasonable timeframe.
  • Verify that the metadata returned within the browse containers is correct and includes album art URIs where applicable.
  • Verify that all content, including artists, album, track, and playlists match your app and website.
  • Verify the artwork renders correctly in browse containers.
  • Verify that all appropriate nodes are generated in a container.
  • Verify that pagination works in large containers.

Playlist editing using the Sonos app

  • Create a playlist from an album, track, or playlist.
  • Edit a playlist.
  • Remove a playlist.
  • Reorder a playlist.

Favorites

  • Add a favorite track.
  • Remove a favorite track.
  • Add a favorite album.
  • Remove a favorite album.
  • Check that favorites added or removed via your app or website are represented.
  • Ensure that updates happen in a reasonable timeframe.

Ratings

  • Verify selecting the positive rating button rates the content successfully.
  • Verify selecting the negative rating button rates the content successfully.
  • Verify the correct success message is shown when selecting the positive ratings button.
  • Verify the correct success message is shown when selecting the negative ratings button.

Dynamic ratings

  • Verify rating a track causes the ratings icon to change to match the rating.
  • Verify that re-rating a track causes the rating icon to update to match the new rating state.
  • Verify a previously rated track shows the current ratings state on the Now Playing screen when replayed.
  • Verify the correct messaging is shown when a track receives a positive rating.
  • Verify the correct messaging is shown when a track receives a negative rating.

Custom error handling

  • Verify the service is returning a custom error code when a specific error condition is met. Use a tool like SoapUI to do this verification.
  • Verify the Sonos app shows the correct custom error message when a specific error is met.