Report Library CSV file

You can export the content of the Report Library to a comma-seperated values (CSV) file based on the selected filter parameters. This article explains how to export a CSV file using the Perfecto Smart Reporting API.

For information on how to download the file directly from the Perfecto UI and for details on the resulting CSV file, see Export content to a CSV file.

Download report library data via API

A full code code sample is available on GitHub: CsvDownloadCodeSample.java

To download the CSV file via the API, you need to obtain a taskId via the public API, request the CSV file by taskID, and then retrieve the file per the download URL included in the query response.

The following code snippet shows all fields that can be sent in the JSON payload. For example requests, see step 1 in the procedure below.

Copy

JSON payload

{
  "filter": {
    "fields": {
      "startExecutionTime": [<Unix time>],
      "endExecutionTime": [<Unix time>],
      "tags": [<one or more tags>],
      "status": [<one or more statuses - PASSED, FAILED, BLOCKED, UNKNOWN>],
      "os": [<one or more OS - ANDROID, BLACKBERRY, IOS, MAC, WINDOWS, LINUX>],
      "browserType": [<one or more browser type - CHROME, FIREFOX, INTERNET_EXPORER, SAFARI, MICROSOFT_EDGE>],
      "browserVersion": [<one or more browser version>],
      "screenResolution": [<one or more screen resolution represented as <width>x<height>>],
      "deviceType": [<one or more device type - MOBILE, DESKTOP, SIMULATOR>],
      "deviceModel": [<one or more device model>],
      "deviceId": [<one ore more device ID>],
      "jobName": [<one or more CI Job Name>],
      "jobNumber": [<one or more CI Job Number>],
      "jobBranch": [<one or more CI job branch>],
      "projectVersion": [<one or more project version>],
      "projectName": [<one ore more project name>],
      "failureReason": [<one or more failure reason IDs>],
      "cleanException": [<one or more exception summary full texts>]
      "triggerType":[<one or more trigger type - Manual, Scheduled, CI/CD>]
    }
    "excludeFields": {
      "tags": [<one or more tags>],
      "status": [<one or more statuses - PASSED, FAILED, BLOCKED, UNKNOWN>],
      "os": [<one or more OS - ANDROID, BLACKBERRY, IOS, MAC, WINDOWS, LINUX>],
      "browserType": [<one or more browser type - CHROME, FIREFOX, INTERNET_EXPORER, SAFARI, MICROSOFT_EDGE>],
      "browserVersion": [<one or more browser version>],
      "screenResolution": [<one or more screen resolution represented as <width>x<height>>],
      "deviceType": [<one or more device type - MOBILE, DESKTOP, SIMULATOR>],
      "deviceModel": [<one or more device model>],
      "deviceId": [<one ore more device ID>],
      "jobName": [<one or more CI Job Name>],
      "jobNumber": [<one or more CI Job Number>],
      "jobBranch": [<one or more CI job branch>],
      "projectVersion": [<one or more project version>],
      "projectName": [<one ore more project name>],
      "failureReason": [<one or more failure reason IDs>],
      "cleanException": [<one or more exception summary full texts>]
    }
  }
}

Expand a section to view details on the available parameters.

The following table lists some of the JSON payload fields that can be added to the filter object to filter the number of returned executions. All filter parameters are supported in CSV reports and API requests. The results will be sorted by test start time, in ascending order.

Tip: Consider limiting the query as much as possible by using the startExecutionTime field to avoid an overly large file size. If you do not limit the query by time, it will automatically be limited to the last 90 days.
Important: Perfecto uses AND logic between different fields and OR logic within the same field. For example, if you specify more than one tag, then if one of the tags matches, the test will appear in the results. The following query brings up results of test reports that have either a status of Failed or Blocked and are at the same time tagged with tag1 or tag2:
Copy
{
    "filter": {
        "fields": {
            "status": ["BLOCKED", "FAILED"],
            "tags": ["tag1", "tag2"]
        }
    }
}
Name Value Description

startExecutionTime

Array of numbers

The start time, in milliseconds from midnight January 1, 1970 GMT - Epoch/Unix Time. If this parameter is set, Perfecto makes sure that the test start time is greater or equal to the startExecutionTime parameter.

endExecutionTime

Array of numbers

The end time, in milliseconds from midnight January 1, 1970 - GMT Epoch/Unix Time. If this parameter is set, Perfecto makes sure that the test start time is less or equal to the endExecutionTime parameter.

externalId

Array of strings

Filters the data to show reports that match a specific driver execution.

tags

Array of strings

Filters the data to show reports that match a specific tag.

To exclude a tag (or any other field), add it inside the excludeFields field.

status

Array of strings

Filters the data to show reports that match a specific test status

Id

Array of strings

Filters the data to show reports that match a specific test ID

executionId[0] or externalId

Array of strings

Filters the data to show reports that match a specific execution ID

os

Array of strings

Filters the data to show reports that match a specific operating system

browserType

Array of strings

Filters the data to show reports that match a specific browser type

browserVersion

Array of strings

Filters the data to show reports that match a specific browser version. For example:

Copy 
"browserVersion": ["90.0.4430.212"]

screenResolution

Array of strings

Filters the data to show reports that match a specific screen resolution. For example:

Copy 
"screenResolution": ["1024x768"]

deviceType

Array of strings

Filters the data to show reports that match a specific device type

deviceModel

Array of strings

Filters the data to show reports that match a specific mobile device model. For example:

Copy 
"deviceModel": ["iPhone-X"]

deviceId

Array of strings

Filters the data to show reports that match a specific device ID

jobName

Array of strings

Filters the data to show reports that match a specific job name

jobNumber

Array of strings

Filters the data to show reports that match a specific job number

jobBranch

Array of strings

Filters the data to show reports that match a specific job branch

projectVersion

Array of strings

Filters the data to show reports that match a specific project version

projectName

Array of strings

Filters the data to show reports that match a specific project name

failureReason

Array of strings

Filters the data to show reports that match a specific failure reason ID

customField.FIELD_NAME

Array of strings

Filters the data to show reports that match the value of a specific custom field. For example:

Copy 
"customField.myFieldName": ["some-value"]

cleanException

Array of strings

Filters the data to show only reports that match the value of a specific clean exception, which is a cleaned-up version of the exception that occurred. To extract the code of the exception, Perfecto looks for specific strings in the stack trace. In the UI, this field is labeled Exception Summary.

triggerType

Array of Strings

Filters the data to show reports that match a specific trigger type

A request can combine any number of filter parameters (externalId, jobName, jobNumber) to achieve the filtered list.

Add the following header parameters to the request.

Name

Value

Perfecto-Authorization

<Your personal security token>

To download the CSV file via API:

Headers

Add the following header parameters to all requests:

Name

Value

Perfecto-Authorization

<Your personal security token>

  1. Submit a request to generate the CSV report.

    Method

    Endpoint URL

    POST

    https://<reporting-server>/export/api/v3/test-executions/csv

    The following code snippets show an example JSON body for the request to retrieve the taskId and status. The sample request fetches tests filtered by different parameters.

    Copy
    Example filtering by job name, number, and branch as well as 2 tags
    {
        "filter": {
            "fields": {
                "jobName": ["dev-e2e-tests"],
                "jobNumber": ["1245"],
                "jobBranch": ["master"],
                "tags": ["retry-test", "nightly"]
            }
        }
    }
    Copy
    Example filtering by start time, the statuses FAILED and BLOCKED, and the exclusion of 2 tags
    {
        "filter": {
            "fields": {
                "startExecutionTime": [1641795055000],
                "status": ["BLOCKED", "FAILED"]
            },
            "excludeFields": {
                "tags": ["retry-test", "nightly"]
            }
        }
    }

    The format of the response is a JSON structure with the following fields:

    • taskId

    • status: Either IN_PROGRESS or COMPLETE

    • url: The final URL to download the CSV when it is ready

  2. To retrieve the CSV report (download link) and status, append the generated taskId from step 1 to the API URL.
    When the CSV file is ready, the API call returns the status COMPLETE.

    Method

    API

    GET

    https://<reporting-server>/export/api/v3/test-executions/csv/<taskId>

    The following table specifies the required parameters.

    Parameter name

    Value

    Description

    taskId

    <Task ID>

    ID of the task that was returned by the initial API call

    The format of the response is a JSON structure with the following fields:

    • taskId
    • status: Either IN_PROGRESS or COMPLETE
    • url: The final URL to download the CSV file when it is ready

  3. Download the CSV file from the URL specified in the url field of the response.