TestingBot API documentation


With our rest api you can access and modify all your data in a simple and secure https way
All api responses are in json format


Our API endpoint is https://api.testingbot.com

We have created open source client libraries 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 "https://api.testingbot.com/v1/user" \
-u key:secret
Arguments
None required

Response
{ 
	"first_name": "Steven",
  	"last_name": "King",
  	"seconds": 17745,
  	"last_login" : "2016-05-05 18:00:40 UTC",
  	"plan" : "small",
  	"max_concurrent": 10
}

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 "https://api.testingbot.com/v1/user" \
-X PUT \
-d "user[first_name]=new" \
-u key:secret 
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 "https://api.testingbot.com/v1/tests?offset=2&count=3" \
-u key:secret
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",
		"completed_at":"2011-07-30T23:22:44Z",
		"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
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 "https://api.testingbot.com/v1/tests/3" \
-u key:secret
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",
	"logs": [{"raw":"https://s3-eu-west-1.amazonaws.com/eulogtestingbot/session.txt"}],
	"groups":["testingbot.com"],
	"build": 0,
	"browser":"IE8",
	"os":"VISTA"
}
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

$ curl "https://api.testingbot.com/v1/tests/e6206205bdff5539f2cbefdd879809c" \
-X PUT \
-d "test[success]=1" \
-u key:secret
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 "https://api.testingbot.com/v1/tests/3" \
-X DELETE \
-u key:secret
Arguments
  • testid (int) | a unique number identifying your test

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

Stop test


Will terminate the running test job.
This will end the test and mark the test as completed.
Any test assets and metadata gathered will be available for download.

$ curl "https://api.testingbot.com/v1/tests/3/stop" \
-X PUT \
-u key:secret
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 "https://api.testingbot.com/v1/lab" \
-u key:secret

Response
{
	"data":[
	{ "id":215,
	  "enabled":false,
	  "alerts":[],
	  "url":"https://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 "https://api.testingbot.com/v1/lab/215" \
-u key:secret
Arguments
  • testid (int) | a unique number identifying your test in the TestLab

Response
{ 
	"id":215,
	"enabled":false,
	"alerts":[],
	"url":"https://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 "https://api.testingbot.com/v1/lab/215" \
-X DELETE \
-u key:secret
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 "https://api.testingbot.com/v1/lab/215" \
-X PUT \
-d "test[cron]=* * * * *" \
-u key:secret
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 "https://api.testingbot.com/v1/lab/215/trigger" \
-X POST \
-d "" \
-u key:secret
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 "https://api.testingbot.com/v1/lab/trigger_all" \
-X POST \
-d "" \
-u key:secret

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

Run a specific lab suite


This call will run a specific testlab suite on our grid
Upload a selenium suite in our testlab indicate on which browsers you want it to run and then run the suite with this api call


You could use this call to run suites when you wish for example before after deployment of your code
Since this call is asynchronously suite 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 suite


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

$ curl "https://api.testingbot.com/v1/lab/215/triggersuite" \
-X POST \
-d "" \
-u key:secret
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

Test job


This call will return the status of a running test or suite initiated by an api call


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

Response
{  
   "status":"FINISHED",
   "created_at":"2016-04-15T13:47:39.000Z",
   "updated_at":"2016-04-15T13:49:30.000Z",
   "success":false,
   "test_ids":[  
      6620446
   ],
   "errors":[  
      {  
         "msg":"Actual value 'Google' did not match 'Goooogle'",
         "step":"verifyTitle",
         "browser":{  
            "name":"firefox",
            "version":"43",
            "os":"VISTA"
         },
         "time":"2016-04-15T13:48:25.839Z",
         "test":6620446
      }
   ]
}

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 tests


We post the result of the tests 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
		}
	],
	"job_id":3,
	"test_ids":[48586]
}

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

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 "https://api.testingbot.com/v1/tunnel" \
-u key:secret

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 "https://api.testingbot.com/v1/tunnel/list" \
-u key:secret

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 "https://api.testingbot.com/v1/tunnel/:id" \
-X DELETE \
-u key:secret

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 will need to create the following URL
https://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
https://testingbot.com/tests/9jf392fj3j2f3ojid8?auth=230i439uf3fojf