How to automatically push Cucumber test results into a Zephyr test cycle

This article explains how to push a JSON result file into a Zephyr test cycle.

This article assumes that:

  • Your Jira project contains a Zephyr test cycle with BDD scenarios

  • The BDD scenarios are automated with Cucumber Open

  • The BDD scenarios have been executed from the features files downloaded from the test cycle

  • The test results are stored into a JSON result file named results.json

Instructions

The Zephyr Cloud REST API allows users to push JSON formatted test results. In this tutorial, we will use curl to execute the request but you are free to use any HTTP client.

Endpoint description

POST endpoint

https://prod-api.zephyr4jiracloud.com/connect/public/rest/api/1.0/bdd/results/import

Headers

  • Content-Type: application/json

  • Authorization: JWT <JWT Token>

  • zapiAccessKey: <ZAPI Access Key>

Parameters

  • projectId: Jira project id

  • cycleId: test cycle id

  • versionId: test cycle version id

  • bddresult: JSON test result file

ZAPI keys

To obtain your ZAPI Keys, the ZAPI app should be installed on your Jira. Install this application on Jira like any other application.

Once ZAPI is installed, go to the ZAPI Key Administration page in Jira settings.

Click on the copy button next to the Access Key and the Secret key to copy them.

More documentation about ZAPI app here.

JWT Token

Zephyr Cloud uses a technology called JWT (JSON Web Token) to authenticate API requests. JSON Web Tokens (JWT) are a standard way of representing security claims.

To generate the JWT token, you need:

  • ZAPI access key

  • ZAPI secret key

  • Atlassian Account Id

 

You can use this pseudocode to generate a JWT token:

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 // A function to build Query String Hash // See: https://developer.atlassian.com/cloud/jira/platform/understanding-jwt/#qsh function QSH(url) retrun qsh_of_url // Use a JWT library to encode and sign the claim import JWTEncode from JWT // Declare the ZAPI access key, secret key and the account Id zapi_access_key = your Zapi access key zapi_secret_key = your Zapi secret key account_id = your account id // Declare Zephyr results API URL api_url = https://prod-api.zephyr4jiracloud.com/connect/public/rest/api/1.0/bdd/results/import // Build Query String Hash of the API URL api_url_qsh = QSH(api_url) // Build your JWT claim claim = a hashmap with the following iss: zapi_access_key, iat: NumericDate of now, exp: NumericDate of now + 1 minute, qsh: api_url_qsh, sub: account_id // Encode and sign your claim token = JWTEncode(claim, zapi_secret_key) // Print token or use it to set the Authorization header print token

More information on how to generate JWT tokens can be found here.

Jira Project Id

There are many ways to find the Jira project Id. You can, for example, use the Jira API but the easier way is to go into the project setting page and to look at in the page URL.

Zephyr Test Cycle Id and Version Id

To obtain the Test Cycle Id and the Version Id:

  1. Select the Zephyr menu → Select the Cycle Summary menu → Select your test cycle

  2. Click on the Detail view

  3. In the breadcrumb, select your test cycle

     

  4. Look at the page URL to find the ids

Curl command

Run this Curl command next to the results.json file.

1 2 3 4 5 6 7 curl -X POST 'https://prod-api.zephyr4jiracloud.com/connect/public/rest/api/1.0/bdd/results/import' \ -H 'Authorization: JWT $jwt_token' \ -H 'ZapiAccessKey: $zapi_access_token' \ -F 'projectId=$project_id' \ -F 'cycleId=$cycle_id' \ -F 'versionId=$version_id' \ -F bddresult=@results.json

You can now see the test results directly into your test cycle.