Test your service

You can use the Sandbox in your Dev Portal dashboard to test your service integration during development.

Learn how to add your service to a specific player and perform tests by using the Sonos app and SoapUI. You can also use our list of suggested tests for evaluation using the Sonos app or the SoapUI tool.

Use Sandbox to test your service

Use the Integration Sandbox to add your SMAPI service to your Sonos system for testing. You will be able to view and test the sandbox integration on selected Sonos apps.

Setting up your Sandbox

While on developer.sonos.com, select Dashboard in the top navigation. This will bring you to your Integrations page.
Click the + New Content Integration button. This will open a separate window.
Under the Content Integration (Sandbox) option, click Create Integration.
Fill out the integration form.

To convert your Sandbox integration to Production, see Converting your integration.

In order to activate your Sandbox, you must, at minimum, fill out the following fields:

Form Section	Fields
General Information	Service Name Availability Sonos Content Integration Agreement Home Page
Sonos Music API	Integration ID Configuration Label SMAPI Endpoint Authentication Method Polling Interval
Brand Assets	Service Logo Full Logo Badge
Localization Resources	Localization File or Service Description and Service Promo
Service Deployment Settings	Sonos ID

🚧
Be sure to Save after editing each field section.

Activate your Sandbox service

After filling out the fields listed above:

Navigate to the Service Deployment Settings section.
Under Sonos IDs, add the Sonos ID of the device you wish to test on.
Be sure to Save your changes.
Navigate to the Service Configuration section.
Click Refresh to ensure that all the information in the Request Body field is up-to-date.
Then, click Send to forward the updates to Sonos. This process will take up to 10 minutes to take effect. Be sure to re-send after you make any additional changes.

🚧
Configuration errors
If there are any resulting errors upon sending, they will be described in the Server Response field.

Check the Sonos app associated with the Sonos ID(s) you entered to view your Sandbox service. Note that the Sandbox service is only visible on the apps specified by the Sonos IDs added.

Authentication SOAP header policy

When creating a service, choose anonymous or OAuth authentication in the Sonos Music API section of the integration form. The authentication methods are summarized below. See Add authentication for details.

Authentication method	Description
Anonymous	Sonos will not use any authentication method to access your service, thereby allowing any user access.
OAuth	Sonos uses your mobile app or a browser to authenticate the user and authorize them to use their account in their household.

Run tests with the Sonos app

Use the Sonos app to manually test and verify portions of your implementation. We recommend that you run these tests before submitting your integration. See submit your content service for details. To run these tests, you need a Sonos app on a Mac, PC, Android, or iOS device, and at least one Sonos player, such as a Play:1.

📘
To test Universal Search (USS), use cURL. Sandbox does not currently support USS. For more information, see Testing your search categories.

The following is a list of some of the tests you can run. The tests are arranged by feature, so only run the tests that are applicable to your service.

Features	Associated Tests
Account management	Add a trial account. Add supported accounts. Add an unsupported account. Add a deleted account. Add a supported account that is expired.
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.
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.
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.
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.
Playlist editing using the Sonos app	Create a playlist from an album, track, or playlist. Edit a playlist. Remove a playlist. Reorder a playlist.
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.

Use SOAPUI to test your service

You can also use a tool like SoapUI to see the metadata exchange between your service and the Sonos app.

The following example uses SoapUI, but you can use any tool that can send a SOAP request and get a response.

Create an initial project by importing the Sonos WSDL. This creates a list of Sonos SOAP actions such as search, getMediaMetadata, and getMetadata. Download the WSDL from SOAP requests and responses.
Use the log file to identify the SOAP action type of the request in the Body (identified as <ns0:Body>). See the example log below.
Copy the complete XML section starting with <?xml> and ending with </SOAP-ENV:Envelope>.
Locate the SOAP action in SoapUI and paste the XML request from the previous step.
Enter your test SMAPI endpoint in SoapUI.
Set a user-agent in the HTTP header, such as:
User-Agent: Linux UPnP/1.0 Sonos/24.0-69180 (Self-Test)

Send the SOAP request and wait for the response:

2016-12-16 18:04:29,040 [DEBUG] SONOS.suds.client - sending to (SERVICE_ENDPOINT) with timeout (30), message:
 
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:ns0="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="http://www.sonos.com/Services/1.1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:tns="http://www.sonos.com/Services/1.1" xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
  <SOAP-ENV:Header>
    <tns:credentials>
      <tns:deviceId>00-00-00-00-00-00:Z</tns:deviceId>
      <tns:deviceProvider>Sonos</tns:deviceProvider>
      </tns:credentials>
  </SOAP-ENV:Header>
  <ns0:Body>
    <ns1:getMediaMetadata>
      <ns1:id>SONG_TRACK_ID</ns1:id>
    </ns1:getMediaMetadata>
  </ns0:Body>
</SOAP-ENV:Envelope>