The Powerful API for Your Mobile App, Game and Web Testing

Integration API for Mobile App Testing

Dear Testdroiders,

Testdroid provides a very powerful and useful API for its users to manage all aspects of mobile development and testing automatically. We’re further improving our capability to serve your needs to instantly access our device farm, manage your projects, your test runs and results, plus many other things that will make your mobile app, game and web testing smoother, faster and less stressful on real Android and iOS devices.

Testdroid APITestdroid API is an easy-to-use gateway for managing your development and testing effort on real Android and iOS devices. As an alternative for an official Testdroid Cloud site, the API provides all infrastructure through different clients (e.g. Java, Python, Ruby) following the RESTful architecture paradigm and returning JSON with appropriate HTTP response codes.

This blog will show you the very basic examples of using the Testdroid API. Full API documentation can be found here.

The Basics – Testdroid Cloud and Testdroid API

In case you are just starting out with API or you don’t have experience with basic HTTP requests and responses, you should start with this article. In a nutshell, HTTP allows for communication between a variety of hosts and clients, and support a variety of network configurations. This makes HTTP a stateless protocol. The communication usually takes place over TCP/IP, but any reliable transport can be used.

HTTP Request - Response
Communication between a host and a client occurs, via a request/response pair. The client initiates an HTTP request message, which is serviced through a HTTP response message in return. We will look at this fundamental message-pair in the next section – with Authentication/Authorization example.

We’re using cURL in the following examples. In case you are not familiar with it, cURL is a software providing a library and command-line tool for transferring data using various protocols. You can download it from here.

Authentication/Authorization – Get Your Cloud Access

Testdroid API uses OAuth 2.0 – an open standard for authorization. The OAuth 2.0 focuses on client developer simplicity while providing specific authorization flows for web apps. As it is seamlessly used with Testdroid API, you can use it to authorize further API calls to our cloud back-end.

OAuth TokenRequest body:

* – Required only when grant_type is password
** – Required only when grant_type is refresh_token

Response of authentication

Example with cURL:

As presented in request body table, our example uses client_id, grant_type, username, and password items in this cURL example:

$ curl -X POST -H "Accept: application/json" -d "client_id=testdroid-cloud-api&grant_type=password&" = your email/account in Testdroid Cloud and XXXXXXXX = your password.

Create a Testdroid project through API (on https cloud testdroid com)

At this stage of the example, you have successfully authorized the access to Testdroid Cloud using the API. In return doing that, you have got an access_token which you should be using in the following examples.


Create a new project


Response for project creation

Now, if project creation goes fine, you’ll HTTP status code 201 and response body illustrated above. If it fails (for any reason), you’ll get this type of response body back:

Failure response body

Example of project creation with cURL:

With the following command line call, you can create yourself a new Testdroid project: (do not forget to use your access_token or refresh_token)

$ curl -X POST -d "name=NewProject" -H "Authorization: Bearer abcdefgh-1234-ijkl-m5n6-opqrstuvxyxz"

Project Listing, Project Details, Test Runs and Device Runs (accept application JSON)

Get list of all your projects:

curl -H "Accept: application/json" -H "Authorization: Bearer abcdefgh-1234-ijkl-m5n6-opqrstuvxyxz"

Get details of a specific project – defined by PROJECT_ID:

curl -H "Accept: application/json" -H "Authorization: Bearer abcdefgh-1234-ijkl-m5n6-opqrstuvxyxz"

Get details of test runs – defined by PROJECT_ID:

curl -H "Accept: application/json" -H "Authorization: Bearer abcdefgh-1234-ijkl-m5n6-opqrstuvxyxz"

Get details of certain device run – defined by PROJECT_ID and RUN_ID:

curl -H "Accept: application/json" -H "Authorization: Bearer abcdefgh-1234-ijkl-m5n6-opqrstuvxyxz"

Example with Python:

The Python sample of using Testdroid API can be found here.


sudo pip install testdroid

Get help / commands listing:

testdroid --help

Note that you can set TESTDROID_USERNAME, TESTDROID_PASSWORD and TESTDROID_URL environment variables!

Example with Ruby:

The Ruby sample of Testdroid API can be found here.


gem "testdroid-api-client"
bundle install

Sample client usage – Authentication:

require 'testdroid-api-client'
client ='admin@localhost', 'admin')

Sample usage – Get projects:

@user = client.authorize
projects = @user.projects.list

Get project by id:

project_id = 123
project123 = @user.projects.get(project_id)
# output project name
p “Project name #{}”

Start project:

test_run =

Check test run status:

p “Project state #{test_run.state}”

Download all logs from test run:

test_run.device_runs.list({:params => {:limit => 100}}).each { |drun| drun.download_logs(“#{}_log”) }

Using device labels:

# Get label for android os version 2.1
lg_android_version_2_1 = client.label_groups.list.detect {|lg| lg.display_name.casecmp(“android version”) == 0 }

os_v2_1 = client.label_groups.get( {|l| l.display_name.casecmp(“2.1”) == 0 }

#get all devices with android os level 2.1
devices = client.label_groups.get(

# get speficic device from devices list
lenovo_a820 = devices.list.detect {|d| d.display_name == “Lenovo A820”}

Device Sessions:

# To create a new device session:
device_session = user.device_sessions.create({:params => {‘deviceModelId’ => ‘1’}})

# To release device session:

Example with Java:

The Java sample of Testdroid API can be found here.

The Ultimate Hands-on Guide to Successful Mobile Web Testing

Learn how to do mobile web testing more efficiently and effectively and reap the benefits of it.


By continuing to use the site, you agree to the use of cookies. more information

The cookie settings on this website are set to "allow cookies" to give you the best browsing experience possible. If you continue to use this website without changing your cookie settings or you click "Accept" below then you are consenting to this.