Testdefinitions: Swarm Test definitions
Get a list of test definitions
Summary
Get a list of test definitions and test fields
GET /api/v11/testdefinitions
Description
Returns a list of test definitions in Swarm that are visible to the current user.
Shared test definitions only display the test url, body, headers, and associated fields if you are the test definition owner. By default, this private data is visible in key data for users with list-level access. To hide key data, see Hiding Swarm storage from regular users.
Example usage
Get a list of Swarm test definitions:
curl -u "username:ticket" "https://my-swarm-host/api/v11/testdefinitions"
Swarm responds with a list of all of its test definitions:
In the example response below, you own testdefinition id1 but you do not own testdefinition id2. The test url, body, headers, and associated fields are not returned for id2 because you do not own that testdefinition.
HTTP/1.1 200 OK
{
"error": null,
"messages": [],
"data" : {
testdefinitions: [
{
"id": 1,
"name": "Main code test",
"headers": {
"BasicAuth": "YWxpY2U6QUJDRDEyMzQ1Njc4Cg=="
},
"encoding": "url",
"body": "status={status}&change={change}&update={update}",
"url": "http://jenkins_host:8080/job/{branches}-review-test/review/build",
"timeout": 20,
"owners": [
"allison"
],
"shared": false,
"description": "Test for main code",
"iterate": true
},
{
"id": 2,
"name": "Doc tests",
"owners": [
"bruno"
],
"shared": true,
"description": "Tests to check that the docs build.",
"iterate": false
}
]
}
}
If the request fails
<error code>:
501 Workflows must be enabled for testdefinitions. To enable workflows, see workflow
HTTP/1.1 <response error code>
{
"error": <error code>,
"messages": [{
"code" : "<code string>",
"text" : "<error message>"
}],
"data" : null
}
Get test definition information
Summary
Get the details of a test definition
GET /api/v11/testdefinitions/{id}
Description
Returns the specified test definition if it is visible to the current user.
Shared test definitions only display the test url, body,headers, and associated fields if you are the test definition owner. By default, this private data is visible in key data for users with list-level access. To hide key data, see Hiding Swarm storage from regular users.
Parameters
Parameter | Description | Type | Parameter Type | Required |
---|---|---|---|---|
id |
Testdefinition ID |
integer |
path |
Yes |
Example usage
Get test definition 1:
curl -u "username:ticket" "https://my-swarm-host/api/v11/testdefinitions/1"
Swarm responds with details for the test definition:
HTTP/1.1 200 OK
{
"error": null,
"messages": [],
"data" : {
testdefinitions: [
{
"id": 1,
"name": "Main code test",
"headers": {
"BasicAuth": "YWxpY2U6QUJDRDEyMzQ1Njc4Cg=="
},
"encoding": "url",
"body": "status={status}&change={change}&update={update}",
"url": "http://jenkins_host:8080/job/{branches}-review-test/review/build",
"timeout": 20,
"owners": [
"allison"
],
"shared": false,
"description": "Test for main code",
"iterate": true
}
]
}
}
If the request fails
<error code>:
- 404 Test definition does not exist or you do not have permission to view it.
- 501 Workflows must be enabled for testdefinitions. To enable workflows, see workflow
HTTP/1.1 <response error code>
{
"error": <error code>,
"messages": [{
"code" : "<code string>",
"text" : "<error message>"
}],
"data" : null
}
Create a test definition
Summary
Create a test definition
POST /api/v11/testdefinitions
Description
Create a test definition.
Parameters
Parameter | Description | Type | Parameter Type | Required |
---|---|---|---|---|
name |
Provide a name for your test. This should be a unique name that is 1 to 32 characters in length. |
string |
body |
Yes |
description |
Provide a description for the test. |
string |
body |
No |
headers |
Specify name=value pairs to pass to the test suite. |
array of strings |
body |
No |
encoding |
Specify the encoding method for the request body parameter:
|
string |
body |
No (required if body parameter used) |
body |
Specify parameters that your test suite requires in the request body parameter. Encoding is set with the encoding parameter. |
string |
body |
No |
url |
Specify the test request URL that will trigger your test suite using the url parameter. 1 to 1024 characters. Special arguments are also available to pass details from Swarm to your test suite, see Pass special arguments to your test suite. Helix Plugin for Jenkins 1.10.11 and later: Swarm must send the parameters for the build to Jenkins as a POST request. To do this, specify the parameters in the body and specify url for encoding. |
string |
body |
Yes |
timeout |
Specify a timeout in seconds. The timeout is used when Swarm connects to your test suite. If a timeout is not set, the http_client_options timeout setting is used. By default, this is 10 seconds. |
integer |
body |
No |
owners |
Specify at least one owner for the test. |
array of strings |
body |
Yes |
shared |
Specify if want other Swarm users to be able to view or use this test definition:
|
boolean |
body |
No |
iterate |
Specify if you want Swarm to create a separate test run for each branch and project the review is associated with:
|
boolean |
body |
No |
Example usage
Create a test definition
curl -X POST -H "Content-Type: application/json" -u "username:ticket" -d "@mybodyfilename.txt" "https://myswarm.url/api/v11/testdefinitions"
The "mybodyfilename.txt" file contains the test definition details:
{
"name": "My test def",
"description": "My test definition description",
"headers": {
"BasicAuth": "user:password",
"OtherHeader": "OtherValue"
},
"encoding": "json",
"body": "{\"test\":\"{test}\"}",
"url": "http://my-test-host/api/v11/testruns/test?test={test}",
"timeout": 10,
"owners" : ["bruno"],
"shared": true,
"iterate": true
}
Swarm responds with the testdefinition details:
HTTP/1.1 200 OK
{
"error": null,
"messages": [],
"data" : {
"testdefinitions": [
{
"id": 3,
"name": "My test def",
"headers": {
"BasicAuth": "user:password",
"OtherHeader": "OtherValue"
},
"encoding": "json",
"body": "{\"test\":\"{test}\"}",
"url": "http://my-test-host/api/v11/testruns/test?test={test}",
"timeout": 10,
"owners": [
"bruno"
],
"shared": true,
"description": "My test definition description",
"iterate": true
}
]
}
}
If the request fails
<error code>:
- The test definition name parameter is required and must be unique.
- The test definition url and owners parameters are required and cannot be empty.
- The encoding, shared, description, and iterate parameters require a value and cannot be empty.
400 one of the following:
HTTP/1.1 <response error code>
{
"error": <error code>,
"messages": [{
"code" : "<code string>",
"text" : "<error message>"
}],
"data" : null
}