log inhelp

 

RESTful API: Test Set

Test Set Resource 

A test set is the main resource you will need to use in order to interact with the Litmus REST API.
 

Create Test Sets 

POST /test_sets.xml

 
Creates a new test using the options passed in the XML request. If created successfully you will receive a HTTP 201 response code and the location header will contain a link to the unique URL from where this resource can be retrieved. For convenience the API will also include an XML representation of the test set within the response body. For full details of this response, see the the Get Test Set documentation below.
 
XML Structure for a new page test to test on all clients
 
<test_set>
  <test_type>page</test_type> <!-- Specify either page or email -->
  <url>http://url.to.test</url> <!-- Only supply a URL parameter for a new page test -->
</test_set>
 
XML Structure for a new test specifying which clients to test with.
 
<test_set>
  <test_type>page</test_type>
  <url>http://url.to.test</url>
 <results type="array">
   <result>
     <application_code>IE7</application_code>
   </result>
   <result>
      <application_code>IE6</application_code>
   </result>
 </results
</test_set>
 
The application_code field is a unique identifier for a particular testing client, you can obtain a list of available testing application codes for a particular service by reading the documentation for the Testing Application resource.
 

User GUIDs

If you are offering an unlimited testing facility to your users, we need to be able to identify the number of unique users of your application. This is done by setting a user GUID for each test you create. If you are billing your users exclusively on a per-test basis you can ignore this option. Otherwise, read the User GUIDs overview for background information, then use the XML structure below to add a user GUID to a test using the REST API.
 
You can specify your user guid as a string when creating the new test. Here is the XML structure for a new testing when specifying a user GUID parameter:
 
<test_set>
  <test_type>email</test_type>
  <user_guid>myuser1</user_guid>
</test_set>
 

Get Test Set

GET /test_sets/#{id}.xml

 
XML returned for a test set. Note that result images are returned with no leading http or https - all services used to host these images will support either normal HTTP or HTTPS and it is up to your API implementation to decide whether images should be secure, or insecure and faster depending on your customers requirements.
 
Sample XML returned for a page test
 
<test_set>
  <created_at type="datetime">2009-02-12T23:23:10Z</created_at>
  <id type="integer">1</id> <!-- The ID of this test -->
  <updated_at type="datetime">2009-02-12T23:23:12Z</updated_at>
  <name>Blog -Litmus</name>
  <service>page</service> <!-- The service used to perform the test -->
  <state>complete</state> <!-- The overall status of this test -->
  <user_guid></user_guid> <!-- The guid as passed in when creating the test -->
  <url>http://litmusapp.com/blog/</url>
  <title>Blog -Litmus</title>
  <results type="array">
    <result>
      <error_at type="datetime" nil="true"></error_at>
      <finished_at type="datetime">2009-02-12T23:23:35Z</finished_at>
      <started_at type="datetime">2009-02-12T23:23:12Z</started_at>
      <test_code>ie7</test_code>
      <state>complete</state>
      <result_type>page</result_type>
      <testing_application> <!-- Details of the application used to carry out the test -->
        <result_type>page</result_type>
        <popular>true</popular>
        <status>0</status>
        <platform_name>Windows</platform_name>
        <platform_long_name>Microsoft Windows</platform_long_name>
        <application_code>ie7</application_code>
        <application_long_name>Explorer 7.0</application_long_name>
      </testing_application>
      <result_images type="array"> <!-- Array of the screen captures returned -->
        <result_image>
          <image_type>full</image_type>
          <full_image>s3.amazonaws.com/sitevista/71a4d63a-55c7-475e-8c87-c2dbae60d3801769491_IE7-fp.png</full_image>
          <thumbnail_image>s3.amazonaws.com/sitevista/71a4d63a-55c7-475e-8c87-c2dbae60d3801769491_IE7-fp-thumb.png</thumbnail_image>
        </result_image>
        <result_image>
          <image_type>window</image_type>
          <full_image>s3.amazonaws.com/sitevista/71a4d63a-55c7-475e-8c87-c2dbae60d3801769491_IE7.png</full_image>
          <thumbnail_image>s3.amazonaws.com/sitevista/71a4d63a-55c7-475e-8c87-c2dbae60d3801769491_IE7-thumb.png</thumbnail_image>
        </result_image>
      </result_images>
    </result>
    ...
  </results>
</test_set>
 
Sample XML returned from an email test. Note the inbox_guid field which represents the first part of the email address you will need to send an email in order to test it. At the moment the only domain in use with Litmus is emailtests.com - In the case of this example XML, the email address would be 744260a@emailtests.com
 
<test_set>
  <created_at type="datetime">2009-02-23T02:03:22Z</created_at>
  <id type="integer">112294</id>
  <updated_at type="datetime">2009-02-24T15:19:39Z</updated_at>
  <name>Testing rendered HTML</name>
  <service>email</service>
  <state>complete</state>
  <user_guid></user_guid>
  <inbox_guid>744260a</inbox_guid>
  <subject>Testing rendered HTML</subject>
  <results type="array">
    <result>
      <error_at type="datetime" nil="true"></error_at>
      <finished_at type="datetime">2009-02-23T02:06:54Z</finished_at>
      <started_at type="datetime">2009-02-23T02:04:43Z</started_at>
      <test_code>gmail</test_code>
      <state>complete</state>
      <result_type>email</result_type>
      <testing_application>
        <business>false</business>
        <result_type>email</result_type>
        <supports_content_blocking>true</supports_content_blocking>
        <desktop_client>false</desktop_client>
        <status>0</status>
        <platform_name>Web-based</platform_name>
        <platform_long_name>Web-based</platform_long_name>
        <application_code>gmail</application_code>
        <application_long_name>Gmail (Older version)</application_long_name>
      </testing_application>
      <result_images type="array">
        <result_image>
          <image_type>full_off</image_type>
          <full_image>s3.amazonaws.com/sitevista/8365ca4c-d834-493c-bed0-1361769feb49744260a-fp.png</full_image>
          <thumbnail_image>s3.amazonaws.com/sitevista/8365ca4c-d834-493c-bed0-1361769feb49744260a-fp-thumb.png</thumbnail_image>
        </result_image>
        <result_image>
          <image_type>full_on</image_type>
          <full_image>s3.amazonaws.com/sitevista/8365ca4c-d834-493c-bed0-1361769feb49744260a-fp-on.png</full_image>
          <thumbnail_image>s3.amazonaws.com/sitevista/8365ca4c-d834-493c-bed0-1361769feb49744260a-fp-thumb-on.png</thumbnail_image>
        </result_image>
        <result_image>
          <image_type>window_off</image_type>
          <full_image>s3.amazonaws.com/sitevista/8365ca4c-d834-493c-bed0-1361769feb49744260a.png</full_image>
          <thumbnail_image>s3.amazonaws.com/sitevista/8365ca4c-d834-493c-bed0-1361769feb49744260a-thumb.png</thumbnail_image>
        </result_image>
        <result_image>
          <image_type>window_on</image_type>
          <full_image>s3.amazonaws.com/sitevista/8365ca4c-d834-493c-bed0-1361769feb49744260a.png</full_image>
          <thumbnail_image>s3.amazonaws.com/sitevista/8365ca4c-d834-493c-bed0-1361769feb49744260a-thumb.png</thumbnail_image>
        </result_image>
      </result_images>
    </result>
  ...
  </results>
</test_set>
 
For a guide to how to display the various spam header data you receive with an email test, see interpreting and displaying the spam header data.
 

Checking the status of a test 

GET /test_sets/#{id}/poll.xml

 
This method is used to poll the api to check if all results have completed. We recommend that you use this URL until all results have completed, then retrieve the whole resource as documented above. A test is considered completed once it returns "completed" or "error".
 
<test_set>
  <results type="array">
    <result>
      <test_code>ie7</test_code>
      <state>complete</state>
    </result>
    ...
  </results>
</test_set>

 

Printable version