POST/hosts

Applies to QAComplete 14.3, last modified on February 19, 2024

Adds a new test host.

Before an agent can run automated tests on a test host, it needs to register this host in QAComplete. All registered hosts are listed in Test Management > Test Hosts. QAComplete users cannot register hosts manually; instead, each agent instance uses the API to register the host it is running on.

The API registers hosts for the entire department of the authenticating user. The host can be used in all projects that the authenticating user can access.

The operation returns the ID and security token of the added host. You can use these values as the login and password to authenticate other API calls.

Authentication

Basic authentication using a user’s login and password. See Authentication for details.

Security Rights

The authenticating user must belong to a user group that has Read access to Test Hosts.

Request Format

To add a test host, send a POST request to the URL:

http://{server}/rest-api/service/automation/v2/hosts

Use the request body in the following format:

{
  "host_name": "computer name",
  "host_configuration": "hardware and/or software configuration",
  "agents": [
    "TestComplete/TestExecute",
    "JUnit (Selenium)",
    "NUnit (Selenium)",
    "TestNG (Selenium)",
    "ReadyAPI / SoapUI OS"
  ],
  "os": "operating system name and version",
  "is_active": boolean,
  "dept_id": integer,
  "agent_version": "Test Agent binary version"
}

Asterisks (*) indicate required parameters.

You can use both long and short names in the "agents" field. That is, testcomplete for TestComplete or TestExecute, readyapi for ReadyAPI or SoapUI OS, and nunit, junit, TestNG for corresponding Selenium frameworks. The "agents" field is not case-sensitive.

host_name  :  string (max 100 char), required

The host’s computer name.

host_configuration  :  string (max 4000 chars), required

Hardware or software information. Use any format you like, for example, a comma-separated list or key=value pairs separated by new line characters.

agents  :  array of strings, required

A JSON array of the names of test agents installed on the host.

Currently, REST API supports the following agents:

  • TestComplete/TestExecute
  • ReadyAPI / SoapUI OS
  • JUnit (Selenium)
  • TestNG (Selenium)
  • NUnit (Selenium)

os  :  string (max 100 chars), required

The operating system name and version.

is_active  :  boolean, default: true

true (default) means that user can schedule automated tests on this host. false means that the test host is inactive and cannot be used for test runs.

dept_id  :  integer

The department ID to add the host to. Include this parameter only if the authenticating user belongs to multiple departments. To get a user’s departments, use /depts.

agent_version  :  string, required

The version of the Test Agent executable, in the x.xx.xxxx format.

A sample request:

POST http://yourserver.com/rest-api/service/automation/v2/hosts HTTP/1.1
Host: yourserver.com
Connection: keep-alive
Content-Type: application/json
Accept: application/json
Authorization: Basic am9obkBleGFtcGxlLmNvbTpwQHNzd29yZA==
Content-Length: 340

{
  "host_name": "RACK11-W7X64",
  "host_configuration": "x64, net45, firefox, chrome, flash",
  "agents": [
    "TestComplete/TestExecute",
    "JUnit (Selenium)",
    "NUnit (Selenium)",
    "TestNG (Selenium)",
    "ReadyAPI / SoapUI OS"
  ],
  "os": "Windows 7 Ultimate 64-bit SP1",
  "is_active": true,
  "agent_version": "2.10.1607"
}

A sample request made by using cURL:

curl -u [email protected]:p@ssword -X POST -d @host.txt -H "Content-Type: application/json" -H "Accept: application/json" http://yourserver.com/rest-api/service/automation/v2/hosts

Response Format

On success, the operation responds with HTTP status code 200. The response is a JSON object with the POSTed host information, the generated host ID and security token. You will need the ID and security token to authenticate other API calls.

If the operation fails, it returns the appropriate status code and (optionally) the error description in the response body.

A sample response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 443



{
  "id": 143,
  "host_name": "RACK11-W7X64",
  "host_configuration": "x64, net45, firefox, chrome, flash",
  "agents": [
    "TestComplete/TestExecute",
    "JUnit (Selenium)",
    "NUnit (Selenium)",
    "TestNG (Selenium)",
    "ReadyAPI / SoapUI OS"
  ],
  "os": "Windows 7 Ultimate 64-bit SP1",
  "is_active": true,
  "security_token": "d2e1ffd1-3c74-4ccf-738b-10997283e35f",
  "agent_version": "2.10.1607"
}

See Also

QAComplete Test Automation REST API Reference

Highlight search results