You can integrate any Testing framework with Sealights to capture Tests Events like Start and End of Test Stage, Tests results, etc using the API described on this page.
This API includes getting the list of tests recommended to be skipped by Sealights for Test Optimization (TIA) and forcing a Full-Run on the next execution of a Test Stage.

For your reference, you’ll find a few sample integrations with various Testing frameworks listed on our dedicated documentation page.

This API requires an Agent Token.

Creating Test Session

Create a test session with a specific Labid and test stage, if there is no labId - use BSId instead

Calling this request to create a new test session for the current run

POST /sl-api/v1/test-sessions
CODE

Request details

Request body

Parameter

Description

Default value

Is mandatory?

labId

Lab Id

 

:flag_on:

testStage

Test Stage

 

:flag_on:

bsid

Build Session Id

 

 

sessionTimeout

Session Timeout (seconds)

14,400 (4 hours)

 

Request Samples

POST /sl-api/v1/test-sessions HTTP/1.1
Authorization: Bearer {sealights-agent-token}
Content-Type: application/json
{
  "labId": "LabId",
  "testStage": "Unit Tests",
  "bsid": "bsId",
  "sessionTimeout": 10000
}

HTTP/1.1 200 OK
HTTP/1.1 404 NOT_FOUND
HTTP/1.1 500 BAD_REQUEST
CODE

Response Sample

{
  "data": {
    "testSessionId": "341dc795-71a8-4253-b686-27ff09f04468"
  }
}
CODE

Sample Shell command and response:

Linux 

curl -X POST "https://$DOMAIN/sl-api/v1/test-sessions"
  -H "Authorization: Bearer $SEALIGHTS_AGENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"labId\":\"LabId\",\"testStage\":\"UnitTests\",\"bsid\":\"bsId\",\"sessionTimeout\":10000}"

200 OK
404 NOT_FOUND
500 BAD_REQUEST
CODE

Powershell

Invoke-RestMethod -Uri "https://$SL_DOMAIN/sl-api/v1/test-sessions" -Method 'Post' \
  -Headers @{'Authorization'="Bearer $SEALIGHTS_AGENT_TOKEN";'Content-Type'='application/json'} 
  -Body @{'testStage'='Automation Tests';'bsid'='123'}
CODE

 

Get Exclude Tests

Getting a list of tests that should be excluded

Test Optimization must be turned on for the Test Stage in order to receive a non-empty response.

Calling this request to get a list of test names that should be excluded in the current run (by default with test names)

GET /sl-api/v1/test-sessions/{testSessionId}/exclude-tests
CODE

You can specify to get only the External Tests IDs (instead of Test Names) to be returned in the response

GET /sl-api/v1/test-sessions/{testSessionId}/exclude-tests?type=externalId
CODE

Request details

Request parameters

Parameter

Description

Is mandatory?

testSessionId

Test Session ID

:flag_on:

type

enum:

  • name - Default type if not specific.

  • externalId

Request/Response Samples

Sample

Request

Response

Default (using test names)

GET /sl-api/v1/test-sessions/{testSessionId}/exclude-tests
Authorization: Bearer {sealights-agent-token}
Content-Type: application/json

HTTP/1.1 200 OK
HTTP/1.1 404 NOT_FOUND
HTTP/1.1 500 BAD_REQUEST
CODE 
{
  "data":[
    "Test1",
    "Test2"
    ]
}
CODE

externalId

GET /sl-api/v1/test-sessions/{testSessionId}/exclude-tests?type=externalId
Authorization: Bearer {sealights-agent-token}
Content-Type: application/json

HTTP/1.1 200 OK
HTTP/1.1 404 NOT_FOUND
HTTP/1.1 500 BAD_REQUEST
CODE 
{
  "data":[
    "123-456",
    "adg-457"
    ]
}
CODE

Sample Shell command and response:

curl -X GET "https://$DOMAIN/sl-api/v1/test-sessions/$TESTSESSIONID/exclude-tests" \
  -H "Authorization: Bearer $SEALIGHTS_AGENT_TOKEN" \
  -H "Content-Type: application/json"

200 OK
404 NOT_FOUND
500 BAD_REQUEST
CODE

Sending Test Events

Sending test events with status

Calling this request for reporting SeaLights test event result. 

POST /sl-api/v2/test-sessions/{testSessionId}
CODE

  • This API must be called before closing/deleting the session.

  • Please notice this specific endpoint uses a v2 URL

This API can be called several times during a session to report tests in bulk.

Request details

Request parameters

Parameter

Description

Is mandatory?

testSessionId

Test Session ID

:flag_on:

Request Body

  • The tests skipped per the recommendation (GetExcluded Tests API above) must be explicitly included in the results of the test sent to Sealights (with the status skipped)

  • Skipped tests must be provided with start and end parameters, as well. We recommend providing them with start = end = now() value.

Parameter

Description

Is mandatory?

body

Array of Test run events (even for a single test)

 :flag_on:

Test run event

 

 

name

Test Name

:flag_on:

externalId

(Optional) Test ID from the Test Management platform/framework .
This identifier must be Unique and a string long up to 48 characters.

start

Starting time of the test (milliseconds since epoch)

:flag_on:

end

Ending time of the test (milliseconds since epoch)

:flag_on:

status

Test status: passed, failed or skipped

:flag_on:

In case of Invalid parameters, API will return an Error code 400 INVALID. For example, if the timestamps are not sent in milliseconds format, API will return with code 400 and a message Invalid timestamp

Request Samples

POST /sl-api/v2/test-sessions/{testSessionId}
Authorization: Bearer {sealights-agent-token}
Content-Type: application/json
[
  {
    "name": "TestToRun1",
    "start": 1619341754996,
    "end": 1619341754998,
    "status": "passed"
  }
]

HTTP/1.1 200 OK
HTTP/1.1 400 INVALID
HTTP/1.1 404 NOT_FOUND
HTTP/1.1 500 BAD_REQUEST
CODE

Sample Shell command and response:

curl -X POST "https://$DOMAIN/sl-api/v2/test-sessions/$TESTSESSIONID" \
  -H "Authorization: Bearer $SEALIGHTS_AGENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d "[{\"name\":\"TestToRun1\",\"start\":1619341754996,\"end\":1619341754998,\"status\":\"passed\"}]"

200 OK
400 INVALID
404 NOT_FOUND
500 BAD_REQUEST
CODE

 

Delete Test Session

Delete test session when sending of test events has been done.

Calling this request will close the test session and update the coverage.

DELETE /sl-api/v1/test-sessions/{testSessionId}
CODE

Request details

Request parameters

Parameter

Description

Is mandatory?

testSessionId

Test Session ID

:flag_on:

Request Samples

DELETE /sl-api/v1/test-sessions/{testSessionId}
Authorization: Bearer {sealights-agent-token}
Content-Type: application/json

HTTP/1.1 200 OK
HTTP/1.1 404 NOT_FOUND
HTTP/1.1 500 BAD_REQUEST
CODE

Sample Shell command and response:

curl -X DELETE "https://$DOMAIN/sl-api/v1/test-sessions/$TESTSESSIONID" \
  -H "Authorization: Bearer $SEALIGHTS_AGENT_TOKEN" \
  -H "Content-Type: application/json" 

200 OK
404 NOT_FOUND
500 BAD_REQUEST
CODE

Force “Full-Run” on a Test Stage

Calling this request will schedule a full run for the next execution of a specified Test Stage.

 PUT /sl-api/v1/tia/apps/{appName}/branches/{branchName}/testStages/{testStage}/full-run
CODE

This API call should be executed BEFORE creating the test session.

Request details

Request parameters

Parameter

Description

Is mandatory?

appName

App to schedule full run for

:flag_on:

branchName

Branch to schedule full run for

:flag_on:

testStage

Test Stage to schedule full run for

:flag_on:

Request Body

Parameter

Description

Is mandatory?

enable

Boolean indicator, indicates if next run will be full run or not

:flag_on:

Request Samples

PUT /sl-api/v1/tia/apps/{appName}/branches/{branchName}/testStages/{testStage}/full-run
Authorization: Bearer {sealights-agent-token}
Content-Type: application/json
{
    "enable": true
}

HTTP/1.1 200 OK
HTTP/1.1 400 NOT_FOUND
HTTP/1.1 500 BAD_REQUEST
CODE

Sample Shell command and response:

curl -X PUT "https://$DOMAIN/sl-api/v1/tia/apps/$APPNAME/branches/$BRANCHNAME/testStages/$TESTSTAGE/full-run" \
  -H "Authorization: Bearer $SEALIGHTS_AGENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"enable\":true}"

200 OK
404 NOT_FOUND
500 BAD_REQUEST
CODE

Get Executions Status List

Calling this request will respond with a status of all executions that are suitable for the request.

GET /sl-api/v1/executions
CODE

This API provides you the ability to handle unexpected end of the execution of your tests that may not trigger the graceful closure of the test session to Sealights (via delete Session API call).
If the Timeout set at the creation of the execution is not sufficient to ensure automatic closure, you can use this API to list the executions left open and close them one by one gracefully before opening new sessions.

Request details

Request parameters

You must provide LabId or/and BuildSessionID (bsid)

Parameter

Description

Is mandatory?

bsid

Build session Id

:flag_on:

labId

Lab Id

:flag_on:

testStage

Test Stage

status

enum:

  • created

  • pendingDelete / deleting

  • ended

Request Samples

GET /sl-api/v1/executions?bsid={bsid}&status={status}&testStage={testStage}
Authorization: Bearer {sealights-agent-token}
Content-Type: application/json

HTTP/1.1 200 OK
HTTP/1.1 500 BAD_REQUEST
CODE

Response Sample

{
  "data": {
    "total": 3,
    "list": [
      {
        "executionId": "executionId1",
        "bsId": "buildSessionId1",
        "labId": "labId1",
        "creationTime": 226978745454,
        "ttl": 3000,
        "testStage": "unit",
        "status": "created"
      }
    ]
  }
}
CODE

Sample Shell command and response:

curl -X GET "https://$DOMAIN/sl-api/v1/executions?bsid=$bsid" \
  -H "Authorization: Bearer $SEALIGHTS_AGENT_TOKEN" \
  -H "Content-Type: application/json" 

200 OK
500 BAD_REQUEST
CODE