Helix Swarm Guide (2019.3)

Testruns: Swarm Test Integration

Get testrun details of a review version

Summary

Get the testrun details of a review version.

GET /api/v10/reviews/{reviewId}/testruns

Description

Used to get the testrun details for a review version.

Note

Any users can get test run details for a review version, the user does not need to be authenticated. The test run uuid is not included in the request response.

Parameters

Parameter	Description	Type	Parameter Type	Required
`reviewId`	Review ID	integer	path	Yes
`version`	An optional parameter that enables you to specify the review version you want to return the testrun details for. Omitting this parameter or passing an empty value shows testrun details for the latest version of the review.	string	query	No

Example of usage

Get details for all of the test runs for the latest version of review 12345

curl "https://myswarm.url/api/v10/reviews/12345/testruns"

Swarm responds with the testrun details:

HTTP/1.1 200 OK		

{
  "error": null,
  "messages": [],
  "data" : {
    "testruns" : [
      {
        "id": 706,
        "change": 12345,
        "version": 2,
        "test": "global1",
        "startTime": 1567895432, 
        "completedTime": 1567895562, 
        "status": "pass",
        "messages": [
          "Test completed successfully",
          "another message" 
        ],
        "url": "http://my.jenkins.com/projectx/main/1224"
        "uuid": "FAE4501C-E4BC-73E4-A11A-FF710601BC3F"
      },
      {
        <ids for other testruns of the review, formatted as above>
      }
    ]
  }
}

Get details for all of the test runs for version 2 of review 12345

curl "https://myswarm.url/api/v10/reviews/12345/testruns?version=2"

Swarm responds with the testrun details:

HTTP/1.1 200 OK		

{
  "error": null,
  "messages": [],
  "data" : {
    "testruns" : [
      {
        "id": 706,
        "change": 12345,
        "version": 2,
        "test": "global1",
        "startTime": 1567895432, 
        "completedTime": 1567895562, 
        "status": "pass",
        "messages": [
          "Test completed successfully",
          "another message"
        ],
        "url": "http://my.jenkins.com/projectx/main/1224"
        "uuid": "FAE4501C-E4BC-73E4-A11A-FF710601BC3F"
      },
      {
        <ids for other testruns for version 2 of the review, formatted as above>
      }
    ]
    "status" : "pass"
  }
}

Tip

When you make a GET request for all of the testruns in a specific review version, Swarm includes a "status" for the review version as a whole in the response. This is shown after the individual testruns. This status is calculated from the "status" values of all of the individual testruns for that review version:

If the test "status" for any of the testruns is "running" then the overall result for that version is "running".
If no testruns are "running" and the test "status" of any of the testruns is "fail" the overall result for that version is "fail".
If the test "status" of all of the testruns is "pass" then the overall result for that version is "pass".

If a request fails

HTTP/1.1 <response error code>		

{
  "error": <high level description>,
  "messages": [{"code" : "<code string>", "msg" : "<error message>"}],
  "data" : null
}

Create a testrun for a review version

Summary

Create a testrun for a review

POST /api/v10/review/{reviewid}/testruns

Description

Create a testrun for a review version. After you have created a testrun for a version of a review, you can update the testrun details as the test progresses using the PATCH and PUT API endpoints or the {pass}, {fail} and {update} callback urls.

Important

Only admin users can create a test run for a review.

Parameters

Parameter	Description	Type	Parameter Type	Required	Restriction
reviewid	Review ID.	integer	path	Yes
version	The version of the review the testrun is being run against.	integer	body	Yes
test	Specifies the test used for the testrun and checks that it is a valid name.	string	body	Yes	1 to 32 characters Valid character are -_A-Za-z0-9
startTime	The time the testrun started, expressed as an epoch value.	integer	body	Yes	> 0
completedTime	The time the testrun completed, expressed as an epoch value.	integer	body	No	> 0
status	The status of the testrun, options are: pass, fail, and running	string	body	No	Valid options are pass, fail, and running
messages	An array of one or more messages for the testrun. They should be formatted in JSON in the body of the POST request. You can pass a maximum 10 messages, if you provide more than 10 messages only the first 10 are saved. Each message can contain a maximum of 80 characters, any messages with more than 80 characters will be automatically truncated.	array	body	No
url	The CI system url for the testrun, this is the link to the CI that enables you to view the current testrun results.	string	body	No	1 to 1024 characters
uuid	The uuid for the testrun. Used to enable non-admin users to update the testrun. If the requested uuid does not match the review an error message is returned.	string	body	No	Minimum 32 max 64 characters

Example usage

Append a new testrun to version 2 of review 12345

curl -X POST -H "Content-Type: application/json" -u "username:ticket" -d "@mybodyfilename.txt" "https://myswarm.url/api/v10/review/12345/testruns"

The "mybodyfilename.txt" file contains the testrun details:

{
  "change": 12345,
  "version": 2,
  "test": "mytest",
  "startTime": 1567895432, 
  "status": "running",
  "messages": [
    "Mytest running",
    "another message"
  ]
  "url": "http://my.jenkins.com/projectx/main/1224",
  "uuid": "FAE4501C-E4BC-73E4-A11A-FF710601BC3F"
}

Swarm responds with the testrun details:

HTTP/1.1 200 OK		

{
  "error": null,
  "messages": [],
  "data" : {
    "testruns" : [
      {
        "id": 706,
        "change": 12345,
        "version": 2,
        "test": "mytest",
        "startTime": 1567895432, 
        "completedTime": null, 
        "status": "running",
        "messages": [
          "Mytest running",
          "another message"
        ],
        "url": "http://my.jenkins.com/projectx/main/1224",
        "uuid": "FAE4501C-E4BC-73E4-A11A-FF710601BC3F"
      }
    ]
  }
}

If the request fails

HTTP/1.1 <response error code>		

{
  "error": <high level description>,
  "messages": [{"code" : "<code string>", "msg" : "<error message>"}],
  "data" : null
}

Create a testrun for a review version using a globally defined test

Summary

Create a testrun for a review using a globally defined test

POST /api/v10/review/{reviewid}/testruns/{test}

Description

Create a testrun for a review version using a globally defined test. Globally defined tests are configured in the Swarm config.php file, see Global tests. After you have created a testrun for a version of a review, you can update the testrun details as the test progresses using the PATCH and PUT API endpoints or the {pass}, {fail} and {update} callback urls.

Important

Only admin users can create a test run for a review.

Note

The test parameter must match a test name used in the global test configuration block of the Swarm config.php file, if it doesn't match an error is generated when the API request is made.

Parameters

Parameter	Description	Type	Parameter Type	Required	Restriction
reviewid	Review ID.	integer	path	Yes
version	The version of the review the testrun is being run against.	integer	body	Yes
test	Specifies the global test used for the testrun and checks that it is a valid name. If there is a test name in the body of the request, Swarm will ignore it. If the test parameter is omitted, Swarm uses the test name in the body of the request.	string	path	Yes	1 to 32 characters Valid character are -_A-Za-z0-9
startTime	The time the testrun started, expressed as an epoch value.	integer	body	Yes	> 0
completedTime	The time the testrun completed, expressed as an epoch value.	integer	body	No	> 0
status	The status of the testrun, options are: pass, fail, and running.	string	body	No	Valid options are pass, fail, and running
messages	An array of one or more messages for the testrun. They should be formatted in JSON in the body of the POST request. You can pass a maximum 10 messages, if you provide more than 10 messages only the first 10 are saved. Each message can contain a maximum of 80 characters, any messages with more than 80 characters will be automatically truncated.	array	body	No
url	The CI system url for the testrun, this is the link to the CI that enables you to view the current testrun results.	string	body	No	1 to 1024 characters
uuid	The uuid for the testrun. Used to enable non-admin users to update the testrun. If the requested uuid does not match the review an error message is returned.	string	body	No	Minimum 32 max 64 characters

Append a testrun for a review using global test definition "global1" for version 3 of review 12345

curl -X POST -H "Content-Type: application/json" -u "username:ticket" -d "@mybodyfilename.txt" "https://myswarm.url/api/v10/review/12345/testruns/global1"

The "mybodyfilename.txt" file contains the testrun details:

{
  "change": 12345,
  "version": 3,
  "startTime": 1567895432, 
  "status": "running",
  "messages": [
    "Global test 1 running",
    "another message"
  ],
  "url": "http://my.jenkins.com/projecty/main/1224",
  "uuid": "FAE4501C-E4BC-73E4-A11A-FF710601BC4F"
}

Swarm responds with the testrun details:

HTTP/1.1 200 OK		

{
  "error": null,
  "messages": [],
  "data" : {
    "testruns" : [
      {
        "id": 707,
        "change": 12345,
        "version": 3,
        "test": "global1",
        "startTime": 1567895432, 
        "completedTime": null, 
        "status": "running",
        "messages": [
          "Global test 1 running",
          "another message"
        ],
        "url": "http://my.jenkins.com/projecty/main/1224",
        "uuid": "FAE4501C-E4BC-73E4-A11A-FF710601BC4F"
      }
    ]
  }
}

If the request fails

HTTP/1.1 <response error code>		

{
  "error": <high level description>,
  "messages": [{"code" : "<code string>", "msg" : "<error message>"}],
  "data" : null
}

Update details for a testrun - PATCH

Summary

Update details for a testrun

PATCH /api/v10/review/{reviewid}/testruns/{id}

Description

Update the details for a testrun.

Important

Only admin users can update testrun details for a review.

Parameters

Parameter	Description	Type	Parameter Type	Required	Restriction
Id	Testrun ID, identifies a specific testrun for the review. Automatically generated by Swarm when the testrun is created.	integer	path	Yes
reviewid	Review ID.	integer	path	Yes
version	The version of the review the testrun is being run against.	integer	body	No
test	Specifies the test used for the testrun and checks that it is a valid name.	string	body	No	1 to 32 characters Valid character are -_A-Za-z0-9
startTime	The time the testrun started, expressed as an epoch value.	integer	body	No	> 0
completedTime	The time the testrun completed, expressed as an epoch value.	integer	body	No	> 0
status	The status of the testrun, options are: pass, fail, and running	string	body	No	Valid options are pass, fail, and running
messages	An array of one or more messages for the testrun. They should be formatted in JSON in the body of the POST request. You can pass a maximum 10 messages, if you provide more than 10 messages only the first 10 are saved. Each message can contain a maximum of 80 characters, any messages with more than 80 characters will be automatically truncated.	array	body	No
url	The CI system url for the testrun, this is the link to the CI that enables you to view the current testrun results.	string	body	No	1 to 1024 characters
uuid	The uuid for the testrun. Used to enable non-admin users to update the testrun. If the requested uuid does not match the review an error message is returned.	string	body	No	Minimum 32 max 64 characters

Example usage

Update testrun 706 for review 12345

curl -X PATCH -H "Content-Type: application/json" -u "username:ticket" -d "@mybodyfilename.txt" "https://myswarm.url/api/v10/review/12345/testruns/706"

The "mybodyfilename.txt" file contains the testrun details you want to update.

{
  "completedTime": "1567895562",
  "status": "fail",
  "messages": [
    "Test has failed",
    "yet another message"
  ],
}

Swarm responds with the testrun details:

HTTP/1.1 200 OK		

{
  "error": null,
  "messages": [],
  "data" : {
    "testruns" : [
      {
        "id": 706,
        "change": 12345,
        "version": 2,
        "test": "mytest",
        "startTime": 1567895432, 
        "completedTime": 1567895562, 
        "status": "fail",
        "messages": [
          "Test has failed",
          "yet another message"
        ],
        "url": "http://my.jenkins.com/projectx/main/1224",
        "uuid": "FAE4501C-E4BC-73E4-A11A-FF710601BC3F"
      }
    ]
  }
}

If the request fails

HTTP/1.1 <response error code>		

{
  "error": <high level description>,
  "messages": [{"code" : "<code string>", "msg" : "<error message>"}],
  "data" : null
}

Update details for a testrun - PUT

Summary

Update details for a testrun

PUT /api/v10/review/{reviewid}/testruns/{id}

Description

Update the details for a testrun. All values must be provided in the request.

Important

Only admin users can update testrun details for a review.

Parameters

Parameter	Description	Type	Parameter Type	Required	Restriction
Id	Testrun ID, identifies a specific testrun for the review. Automatically generated by Swarm when the testrun is created.	integer	path	Yes
reviewid	Review ID.	integer	path	Yes
version	The version of the review the testrun is being run against.	integer	body	Yes
test	Specifies the test used for the testrun and checks that it is a valid name.	string	body	Yes	1 to 32 characters Valid character are -_A-Za-z0-9
startTime	The time the testrun started, expressed as an epoch value.	integer	body	Yes	> 0
completedTime	The time the testrun completed, expressed as an epoch value.	integer	body	Yes	> 0
status	The status of the testrun, options are: pass, fail, and running	string	body	Yes	Valid options are pass, fail, and running
messages	An array of one or more messages for the testrun. They should be formatted in JSON in the body of the POST request. You can pass a maximum 10 messages, if you provide more than 10 messages only the first 10 are saved. Each message can contain a maximum of 80 characters, any messages with more than 80 characters will be automatically truncated.	array	body	Yes
url	The CI system url for the testrun, this is the link to the CI that enables you to view the current testrun results.	string	body	Yes	1 to 1024 characters
uuid	The uuid for the testrun. Used to enable non-admin users to update the testrun. If the requested uuid does not match the review an error message is returned.	string	body	Yes	Minimum 32 max 64 characters

Example usage

Update testrun 706 for review 12345

curl -X PUT -H "Content-Type: application/json" -u "username:ticket" -d "@mybodyfilename.txt" "https://myswarm.url/api/v10/review/12345/testruns/706"

The "mybodyfilename.txt" file must contain all of the testrun details:

{
  "id": 706,
  "change": 12345,
  "version": 2,
  "test": "mytest",
  "startTime": 1567895432, 
  "completedTime": 1567895562, 
  "status": "fail",
  "messages": [
    "Test has failed",
    "and another message"
  ],
  "url": "http://my.jenkins.com/projectx/main/1224",
  "uuid": "FAE4501C-E4BC-73E4-A11A-FF710601BC3F"
}

Swarm responds with the testrun details:

HTTP/1.1 200 OK		

{
  "error": null,
  "messages": [],
  "data" : {
    "testruns" : [
      {
        "id": 706,
        "change": 12345,
        "version": 2,
        "test": "mytest",
        "startTime": 1567895432, 
        "completedTime": 1567895562, 
        "status": "fail",
        "messages": [
          "Test has failed",
          "and another message"
        ],
        "url": "http://my.jenkins.com/projectx/main/1224",
        "uuid": "FAE4501C-E4BC-73E4-A11A-FF710601BC3F"
      }
    ]
  }
}

If the request fails

HTTP/1.1 <response error code>		

{
  "error": <high level description>,
  "messages": [{"code" : "<code string>", "msg" : "<error message>"}],
  "data" : null
}

Your search for returned result(s).