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.

Tip

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.

Tip

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:

  • url for URL Encoded: POST parameters are parsed into name=value pairs. This is the default.
  • json for JSON Encoded: parameters are passed raw in the POST body.
  • xml for XML Encoded: parameters are passed in XML format in the POST body.

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.

Note

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:

  • true: other Swarm users can use this test.
  • false or not or not specified: other Swarm users will not be able to see or use this test.

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:

  • true: creates a separate test run for each branch and project the review is associated with. The details generated by the {projects} and {branches} arguments in the URL or Body are used in the test name displayed in the Tests dropdown on the review page.
  • false or not or not specified: only one test will be run for the review, even if multiple branches and projects are associated with the review.

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>:

    400 one of the following:

    • 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.

HTTP/1.1 <response error code>		

{
  "error": <error code>,
  "messages": [{
    "code" : "<code string>",
    "text" : "<error message>"
  }],
  "data" : null
}