Spec Files

API Reference - Spec Files resource

This resource represents the spec files and their performance metrics, computed based on the recorded results.

Querying this resource will fetch all the executions recorded between date_start, date_end with all the filters applied, group the results by spec file name and calculate metrics:

• overallExecutions - overall executions included in the aggregation.

• avgDuration - an average value of the durations for non-failed executions, measured in seconds; set includeFailedInDuration to true to include failed executions in the calculation

• failedExecutions - count of executions with at least 1 failed test.

• flakyExecutions - count of executions with at least 1 flaky test.

• timeoutExecutions - count of executions that were marked as timed out.

• fullyReported - count of executions that were fully reported - i.e. all the known tests fully completed and reported the results

• suiteSize - maximum number of tests across all the included executions

• failureRate - the ratio of failedExecutions / overallExecutions

• timeoutRate - the ratio of timeoutExecutions / overallExecutions

• flakeRate - the ratio of flakyExecutions / overallExecutions

The results will be sorted according to the order parameter. Using this query would allow to programmatically access the data that is available in Test Suite Explorer.

This resource uses Offset Pagination as documented at Pagination

List the spec files associated to your specific organization and project

GET v1/spec-files/:projectId

Path Parameters

Name	Type	Description
projectId*	String	Your project ID

Query Parameters

Name	Type	Description
limit	Number	Pagination limit 1-50. Default: 50
page	Number	Page 0+. Default: 0. See Pagination
date_start*	ISOString	Date start - the test results included within the date range will be included.
date_end*	ISOString	Date end - the test results included within the date range will be included.
tags[]	String[]	List of tags for filtering the included test results. To provide multiple values, use tags[]=valueA&tags[]=valueB
authors[]	String[]	List of authors for filtering the included test results. To provide multiple values, use authors[]=valueA&authors[]=valueB
branches[]	String[]	List of branches for filtering the included test results. To provide multiple values, use branches[]=valueA&branches[]=valueB
includeFailedInDuration	Boolean	Include failed spec files in duration calculation. Default: false.
order	Enum	Defines the attribute to order the spec files list. Default: avgDuration. Valid values: avgDuration, failedExecutions, failureRate, flakeRate, flakyExecutions, fullyReported, overallExecutions, suiteSize, timeoutExecutions, timeoutRate
specNameFilter	String	A string that is included in the spec file name. Default: empty.
dir	Enum	The direction of the spec files list sorting. Default: desc. Options: asc, desc.

200: OK Spec files list

{
    "status": "OK",
    "data": {
        "list": [
            {
                "signature": "326aafb71c1fda3085ebde3671f230f0",
                "spec": "feature.onboarding-25.spec.ts",
                "metrics": {
                    "overallExecutions": 3,
                    "avgDuration": 13184,
                    "failedExecutions": 0,
                    "flakyExecutions": 0,
                    "timeoutExecutions": 0,
                    "suiteSize": 2,
                    "failureRate": 0,
                    "timeoutRate": 0,
                    "flakeRate": 0,
                    "fullyReported": 3
                }
            }
        ],
        "total": 44, // the total number of spec files detected
        "nextPage": number | false // offset pagination hint
    }
}

400: Bad Request Parameters failure

{
    "status": "FAILED",
    "error": "\"date_start\" is mandatory"
}

404: Not Found No project ID defined

{
    "status": "FAILED",
    "error": "Not found"
}