OpenTest server Web API

Contents

The OpenTest server provides a number of HTTP APIs that can be used to control OpenTest from a continuous integration pipeline with CI servers like Jenkins, TeamCity, Travis CI and others.

There are more APIs than the ones described here, but it is advisable that you don’t use any undocumented APIs, as they may change in the future. If you need an API that you can’t find in here, please raise a GitHub issue to describe your use case.

Creating a test session

This API allows creating a new test session by specifying all the properties of the new test session, a template file to read the properties from or a combination between the two.

URL: /api/session

Method: POST

Request payload (JSON):

{
    "actorTags": [],
    "environment": null,
    "maxIterations": 1,
    "sessionLabel": "Test session 1",
    "template": {
        "path": ".",
        "name": "Template 1"
    },
    "tests": [
        {
            "path": ".",
            "name": "Test 1"
        },
        {
            "path": "web",
            "name": "Web test 1"
        },
        {
            "path": "api",
            "name": "API test 1"
        }
    ]
}

Property

Description

actorTags

This is an array of strings that can be used to target a specific actor when running a test session. The sync server will try to acquire test actors of the type that was specified in the test files, but which are also tagged with all the tags specified in the actorTags array. Default: [].

environment

The environment to target when running the test session. Default: null.

maxIterations

The number of times to retry execution of a failed test. This is used for alleviating the problem caused by flaky, non-deterministic tests. Default: 1.

sessionLabel

The human-readable label that will be used for the test session to make it easily identifiable in the web UI.

template

A test session template to use for populating the test session details. A test session can be started successfully by just specifying this one property, as all the others will be populated from the template file itself. However, if the other properties are present, they will take priority and override the values in the template file. The template property is an object with two properties: path and name. The path property represents the path to the template file relative to the templates subdirectory in the test repo. The name property represents the name of the template file without the extension. The template property’s default value is null.

tests

An array of tests to include in the test session. Each test is represented as an object with two properties: path and name. The path property represents the path to the test file relative to the tests subdirectory in the test repo. The name property represents the name of the test file without the extension. The tests property is mandatory (unless the template property was specified).

The properties in the JSON payload are mirroring the details that are passed when starting a test session using the OpenTest server UI. The optional properties actorTags, environment, maxIterations, sessionLabel and template can be skipped.

Here is an example of valid JSON payload to create a test session purely based on a template file:

{
    "template": {
        "path": ".",
        "name": "Template 1"
    }
}

To override the session label defined in the template file, we can specify it in the payload, like this:

{
    "sessionLabel": "My custom session label",
    "template": {
            "path": ".",
            "name": "Template 1"
    }
}

To create a test session in the prod environment that runs two tests:

{
    "environment": "prod",
    "sessionLabel": "Run two Web tests in production",
    "tests": [
        {
            "path": "web",
            "name": "Web test 1"
        },
        {
            "path": "web",
            "name": "Web test 2"
        }
    ]
}

Response status code: 201

Response payload (JSON):

{
    "sessionId": 1535683213
}

The response will contain the session ID for the newly created test session.

Getting the test session log

This API returns the complete log data for a test session.

Method: GET

URL: /api/session/<SESSION_ID>/log?format=<FORMAT>

Query parameters:

Parameter

Description

format

Optional parameter that controls the format of the data returned in the response. Possible values:

  • pretty: the call will return human-readable log data.

  • json: the call will return a JSON array, where each entry in the array is an object that represents one log entry.

The default format is pretty.

Response status code: 200

Response payload (JSON):

The API call returns the contents of the log file, in human-readable or JSON format, depending on the value of the format parameter.

Getting the test session details

This API returns detailed information about a test session like its status (completed/pending/etc.), its result (passed/failed), the time the session was created/started/ended and many other.

Method: GET

URL: /api/session/<SESSION_ID>

Response status code: 200

Response payload (JSON, simplified sample):

{
    "id": 1532439129,
    "label": "Smoke tests",
    "result": "passed",
    "status": "completed",
    "tests": [
        {
            "actions": [],
            "isDataDriven": false,
            "name": "Find the React repo on GitHub's website",
            "path": "web",
            "result": "passed",
            "status": "completed",
            "tags": [],
            "timeStarted": 1532439129907,
            "timeCompleted": 1532439143716
        }
    ],
    "timeCreated": 1532439128914,
    "timeStarted": 1532439129907,
    "timeCompleted": 1532439159338,
    "lastActivity": 1532439159337,
    "actorTags": [],
    "environment": "",
    "testCounts": {
        "cancelled": 0,
        "completed": 1,
        "failed": 0,
        "passed": 1,
        "pending": 0,
        "skipped": 0,
        "total": 1
    }
}

Downloading a screenshot

This API allows downloading a screenshot image file.

Screenshots captured by test actors during test execution are uploaded asynchronously to the OpenTest server into the "uploads/screenshots" subdirectory of the server’s working directory. Each screenshot is given a unique file name that incorporates the session ID, test actor type, test index, test segment index and the test step index (e.g. SID1535813400_WEB_T01_SG01_ST04_error.png).

The exact names of the screenshot files can be taken from the JSON output of the GET /api/session/<SESSION_ID> API. The ability to download the screenshot image files can be useful when integrating OpenTest with a custom reporting solution.

Method: GET

URL: /api/screenshot/<SCREENSHOT_FILE_NAME>

Response status code: 200

Response payload:

The call will return the requested image file.