TestingBot API Documentation

With our REST API you can access and modify all your data in a simple and secure (HTTPs) way.
The API requires authentication with the key and secret you obtained when you signed up.


All API responses are in JSON format.
The current version of our API is 1. (updated 2012-05-15)


There are currently 2 libraries available to easily interact with our API:


Authentication

You can authenticate to our TestingBot API by providing your API key and API secret which you can obtain in the member area.


Authentication to the API needs to happen via HTTP Basic Auth.


All requests must be made to our endpoint via HTTP. You must authenticate for all API requests.

List of browsers

This call will return a list of browsers our grid currently supports. 

				curl https://api.testingbot.com/v1/browsers
Optional Arguments:
  • type (string) webdriver or rc

Response: 
				[{"selenium_name":"IE8","name":"iexplore","version":8,"platform":"WINDOWS"},
				 {"selenium_name":"FF7","name":"firefox","version":7,"platform":"WINDOWS"}]

Access your user info

This call will return the data associated to your account.
You can edit this data by issueing a PUT request to our API. 

					curl -u key:secret https://api.testingbot.com/v1/user
Arguments:
None required

Response: 
				{ 
					"first_name": "Steven",
				  	"last_name": "King",
				  	"seconds": 17745,
				  	"last_login" : "2011-08-06T16:47:04Z",
				  	"plan" : "small"
				}

Edit your user info

This call will return the data associated to your account.
You can edit this data by issueing a PUT request to our API. 

					curl -u key:secret https://api.testingbot.com/v1/user -X PUT -d "user[first_name]=new"
Arguments:
  • first_name (string)
  • last_name (string)
  • email (string)

Response: 
				{
					"success" : true,
					"user" : {
						"first_name": "new",
					  	"last_name": "King",
					  	"seconds": 17745,
					  	"last_login" : "2011-08-06T16:47:04Z"
					}
				}

Retrieve your tests

Will return all the tests you have created together with details for every test.
You can use the offset and count parameters to paginate your tests. 

					curl -u key:secret "https://api.testingbot.com/v1/tests?offset=2&count=3"
Arguments:
  • offset (int) | optional - paginate tests starting from this number
  • count (int) | optional - number of tests to fetch

Response: 
				{
					"data":[
					{
						"created_at":"2011-07-30T23:21:23Z",
						"extra":null,
						"id":3,
						"name":"MyTest::testTitle",
						"session_id":"f7903f9e93e74fe1b0e924bf9d2ce9fc",
						"status_message":"Failed asserting that 1 equals 0.",
						"success":false,
						"test_environment_id":1,
						"thumbs":[],
						"video":"https://s3.amazonaws.com/rectestingbot/sample.flv",
						"groups":["testingbot.com"],
						"browser":"IE8",
						"os":"WINDOWS"
					}],
					"meta":
					{
						"offset":2,
						"count":3,
						"total":789
					}
				}

Specific test info

This call will return info for one of your tests.
In the example below, the response will contain info for a test with id 3.

You can also look up tests by using the Selenium session id.
Your tests will always the know the session id, so using this id to query our API should be a lot easier.

You can fetch all the various test ids that belong to you by fetching your tests. 

					curl -u key:secret https://api.testingbot.com/v1/tests/3
Arguments:
  • testid (int) | a unique number identifying your test or the test session id

Response: 
				{
					"created_at":"2011-07-30T23:21:23Z",
					"extra":null,
					"id":3,
					"name":"MyTest::testTitle",
					"session_id":"f7903f9e93e74fe1b0e924bf9d2ce9fc",
					"status_message":"Failed asserting that 1 equals 0.",
					"success":false,
					"thumbs":["https://s3.amazonaws.com/thumbtestingbot/3_f93782fji.jpg"],
					"video":"https://s3.amazonaws.com/rectestingbot/sample.flv",
					"groups":["testingbot.com"],
					"browser":"IE8",
					"os":"WINDOWS"
				}
Possible errors:
  • 404 Not found - test not found

Update a test

This call will update a test.
You can use this call to update the success status, add a name or extra data, ...

To update a specific test, pass its unique test ID or its Selenium session ID. 

					curl -u key:secret https://api.testingbot.com/v1/tests/e6206205bdff5539f2cbefdd879809c -X PUT -d "test[success]=1"
Arguments:
  • testid (int) | a unique number identifying your test or the test session id
  • test[success] boolean | indicating if the test was successful
  • test[status_message] string | the status/error message of your test
  • test[name] string | the name of your test
  • test[extra] string | extra data for this test
  • groups string | a comma-seperated list of groups this test belongs to

Response: 
				{
					"success" : true
				}
Possible errors:
  • 404 Not found - test not found

Delete test

Will delete a specific test, together with possible thumbnails.
In the example below, we'll delete a test with id 3.

You can fetch all the various test ids that belong to you by fetching your tests. 

					curl -u key:secret https://api.testingbot.com/v1/tests/3 -X DELETE
Arguments:
  • testid (int) | a unique number identifying your test

Response: 
				{
					"success":true
				}
Possible errors:
  • 404 Not found - test not found

List Lab tests

Will return a list with all the tests in our TestLab.
In our TestLab you can upload Selenium tests, which you can then execute with a cron or by creating an API request. 

					curl -u key:secret https://api.testingbot.com/v1/lab

Response: 
				{
					"data":[
					{ "id":215,
					  "enabled":false,
					  "alerts":[],
					  "url":"http://testingbot.com/",
					  "name":"testingbot",
					  "created_at":"2012-03-12T20:03:45Z",
					  "updated_at":"2012-03-13T20:26:43Z",
					  "last_run":"2012-03-13T06:50:48Z",
					  "cron":"0 0 * * *",
					  "browsers":[
					  	{"name":"firefox","version":10,"os":"LINUX"}
					  ]
					}],
					"meta":
					{
						"offset":2,
						"count":3,
						"total":25
					}
				}

Specific Lab test info

This call will return info for a specific TestLab test.
In the example below, the response will contain info for a test with id 215. 

					curl -u key:secret https://api.testingbot.com/v1/lab/215
Arguments:
  • testid (int) | a unique number identifying your test in the TestLab

Response: 
				{ 
					"id":215,
					"enabled":false,
					"alerts":[],
					"url":"http://testingbot.com/",
					"name":"testingbot",
					"created_at":"2012-03-12T20:03:45Z",
					"updated_at":"2012-03-13T20:26:43Z",
					"last_run":"2012-03-13T06:50:48Z",
					"cron":"0 0 * * *",
					"browsers":[
						{"name":"firefox","version":10,"os":"LINUX"}
					]
				}
Possible errors:
  • 404 Not found - lab test not found

Delete Lab test

This call will delete a specific TestLab test. 

					curl -u key:secret https://api.testingbot.com/v1/lab/215 -X DELETE
Arguments:
  • testid (int) | a unique number identifying your test in the TestLab

Response: 
				{ 
					"success":true
				}
Possible errors:
  • 404 Not found - lab test not found

Update Lab test

This call will update a specific TestLab test. 

					curl -u key:secret https://api.testingbot.com/v1/lab/215 -X PUT -d "test[cron]=* * * * *"
Arguments:
  • testid (int) | a unique number identifying your test in the TestLab
  • url (string)
  • name (string)
  • cron (string)
  • enabled (boolean)

Response: 
				{ 
					"success":true
				}
Possible errors:
  • 404 Not found - lab test not found

Run a specific Lab test

This call will run a specific TestLab test on our grid.
Upload a Selenium test in our TestLab, indicate on which browsers you want it to run and then run the test with this API call.


You could use this call to run tests when you wish, for example before/after deployment of your code.
Since this call is asynchronously (test takes too long to be processed during the API call), you need to specify an API callback page in the alert section of your TestLab test.


This call will return a success state and a job_id, which you can use to query the progress of the test. 

					curl -u key:secret https://api.testingbot.com/v1/lab/215/trigger -X POST -d ""
Arguments:
  • testid (int) | a unique number identifying your test in the TestLab

Response: 
				{ 
					"success":true,
					"job_id" : 14
				}
Possible errors:
  • 404 Not found - lab test not found

Run all Lab tests

This call will run all TestLab tests on our grid.


This call will return a success state and a job_id, which you can use to query the progress of the tests. 

					curl -u key:secret https://api.testingbot.com/v1/lab/trigger_all -X POST -d ""

Response: 
				{ 
					"success":true,
					"job_id" : 14
				}

Test Job

This call will return the status of a running test, initiated by an API call. 


					curl -u key:secret https://api.testingbot.com/v1/jobs/11
Arguments:
  • job (int) | a unique number identifying your job

Response: 
				{
					"status":"FINISHED",
					"created_at":"2012-03-13T20:35:54Z",
					"updated_at":"2012-03-13T20:36:54Z"
				}

The various states are: WAITING, RUNNING and FINISHED.

Possible errors:
  • 404 Not found - job not found

API Callback

If you initiated an API call running one or all tests, you will want to know the results of the test(s).


We post the result of the test(s) back to the location you specified in our TestLab (alerts section).


Sample post data: 
				{
					"success":"false",
					"errors":[
						{ 
						  "msg" : "word Not found", 
						  "step" : "verifyTextPresent", 
						  "browser" : { 
						    "name" : "iexplore", 
						    "version" : "8", 
						    "os" : "WINDOWS"
						   },
						   "time" : "2012-03-13 20:34:59 UTC", 
						   "test_id" : "48586",
						   "job_id": 17,
						   "lab_id" : 133
						}
					]  
				}
				

				{
					"success":"true",
					"test_ids":[48586, 48587]  
				}

TestingBot Tunnel

Starts or retrieves a private TestingBot Tunnel.


Returns a readystate and IP address.
If a tunnel did not exist before this call, one will be created and its state will be PENDING.
After about 45 seconds the tunnel will be ready, the response will return a READY state together with an IP address. 


					curl -u key:secret https://api.testingbot.com/v1/tunnel

Response: 
				{ 
					"state":"READY",
					"version":"1.8",
					"ip":"x.x.x.x"
				}

TestingBot Tunnel List

List of currently active TestingBot Tunnels for your account.


You can have up to 8 simultaneous tunnels running with your account.
By issueing a DELETE request you can delete/stop any of your tunnels. 


					curl -u key:secret https://api.testingbot.com/v1/tunnel/list

Response: 
				[{ 
					"ip":"xx",
					"private_ip":"xx",
					"state":"READY",
					"id":1,
					"requested_at"=>"2013-04-23 01:34:23"
				}]

TestingBot Tunnel Delete

Delete an active TestingBot Tunnel in your account.


Usually the tunnel jar will issue this call automatically when you gracefully exit the jar.
You can also use this API call, which destroys the tunnel VM. 


					curl -u key:secret https://api.testingbot.com/v1/tunnel/:id -X DELETE

Response: 
				{ 
					"success":true
				}

Share Test Result

You can easily share a single test result with someone in a safe way, without the other person needing an account.


To share a test result, you'll need to create the following url:
http://testingbot.com/tests/sessionId?auth=authentication-hash


The sessionId is the ID assigned by the Selenium grid to identify a single test.
You can find this sessionId in your logs when running a test.


The authentication hash is created with md5 in the following format: 

					Digest::MD5.hexdigest("#{client_key}:#{client_secret}:#{session_id}")


An example link would then be:
http://testingbot.com/tests/9jf392fj3j2f3ojid8?auth=230i439uf3fojf