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:
// 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:
Select the Zephyr menu → Select the Cycle Summary menu → Select your test cycle
Click on the Detail view
In the breadcrumb, select your test cycle
Look at the page URL to find the ids
Curl command
Run this Curl command next to the results.json file.
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.jsonYou can now see the test results directly into your test cycle.