Documentation | 2025.1

# 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: 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. 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
    }

Your search for returned results