In order to enable users and scripts to interface with SoTest deployments, a REST API provides access to different functionality.
Some functionality is only available to users that have logged in first.
API endpoints that require authentication use the basic access authentication method.
This means that there are two ways to authenticate via tools like
The following examples assume that “Aladdin” is the user name and “OpenSesame” is the password.
Username and password can be encoded in the URL when calling an API endpoint:
SoTest login information can be stored in a
This file can either be stored in the user’s home folder as
Refer to the curl documentation
for more detailed information.
# this call allows curl to lookup login information from ~/.netrc curl --netrc https://opensource.sotest.io/path/to/api/endpoint # this call provides a netrc file from elsewhere curl --netrc-file /path/to/netrc-file \ https://opensource.sotest.io/path/to/api/endpoint
The netrc file would contain the following content:
machine opensource.sotest.io login Aladdin password OpenSesame
/api/create - Create a Test Run¶
The POST endpoint for test run creation is
/api/create and requires
This endpoint assumes the following parameters:
boot_files_url: The URL from which SoTest controllers can download the binaries that must be booted in order to execute the tests.
name: Display name of the test run in the web UI.
url: Display URL of the test run in the web UI. This might for example be the URL of a pull request that is tested.
config: The YAML/JSON encoded project configuration as file upload.
priority: Optional integer field that describes the priority of the test run. Higher number means higher priority. Priorities can be negative. Default priority is
If authentication and test run creation were successful, the server returns a HTTP 200 status code and emits just the ID of the new test run.
curl --netrc \ -F 'boot_files_url=https://my.artifacts.server/commit-123.zip' \ -F 'url=https://github.com/my-org/my-project/pull/123' \ -F 'name=Pull request #123' \ -F 'config=@/path/to/project_config.yaml' https://opensource.sotest.io/api/create
/api/query/:id - Query the State of a Test Run¶
The GET endpoint for test run creation is
:id is the
test run ID.
This endpoint assumes no other parameters.
In case the test run exists, this endpoint returns a HTTP 200 status code along with the following JSON document:
<TAG> is one of the following symbols:
UNFINISHED: Test run did not finish, yet.
SUCCESS: Test run finished without any test failures.
FAIL: Test run finished with one or more test failures.
DISABLED: Test run was disabled by user or general infrastructure failures.
ERROR: Unable to find testrun