In this page

What is Zephyr?

(supported since Better PDF Exporter 5.5.0)

Zephyr is the most popular test management solution for the Jira platform.

Zephyr integration features

  • As Zephyr tests are regular Jira issues, this enables creating self-containing exports from Zephyr tests with all their details from field values (test details), through attachments and comments, to test steps (instructions).
  • You can export the test executions for any test. Executions are exported with their (customizable) details for a comprehensive report: test cycle, version, status, defects, executor user and execution date.
  • You can export the test step results of the test executions for detailed test reports. In this case, the following (customizable) details are exported for each step: status, defects, comments and execution date.

Tutorial video

Watch this short video to get the gist of exporting Zephyr tests to PDF documents!

Export samples

Zephyr test steps

This example shows the export of the Zephyr test steps (with the corresponding test data and expected result), augmented with regular issue information, from field values through attachments to links.

jira-zephyr-atm-test-steps.pdf

Zephyr test executions

This is very similar to the previous, extending that with the executions of the test.

jira-zephyr-atm-test-executions.pdf

Zephyr test step results

This is the most detailed example, exporting all executions and their step results, also including related defects, executor and execution time.

jira-zephyr-atm-test-step-results.pdf

Configuration

Installing ZAPI

Please note that the Zephyr app itself does not expose any public API. Instead, there exists a separate app called ZAPI (also developed by SmartBear/Zephyr) to provide a REST API for Zephyr tests, test executions and so.

The Zephyr and Better PDF Exporter integration relies on the REST API provided by ZAPI.

Therefore, please install ZAPI as the starting step. (Note: ZAPI is free since version 2.7.1.27107787. Before that, it was a paid app, but even if you need to use an older ZAPI version, a free trial license will be sufficient for evaluation purposes.)

Configuring the Zephyr REST API access

As this integration relies on the Zephyr REST API, you need to configure the login credentials of a valid Jira user account for the REST API calls in the templates:

  1. Go to AdministrationAdd-onsPDF Templates (under Better PDF Exporter).
  2. Open the issue-fo.vm template for editing, and set the username and password to these configuration variables in the top part (don't remove the quotation marks around the string!):
    ## Jira user credentials for REST API calls
    #set($restUserName = "admin") ## Jira username for REST authentication
    #set($restPassword = "admin") ## Jira password for REST authentication
    
  3. Save the changes. (Don't worry about storing passwords here: this file is visible only for Jira administrators, who would have super-user permissions any way.)

Notes:

  • If you are using multiple REST API based integrations in the same template (ex: Gliffy plus Zephyr), then all REST API calls will use with the same user credentials.
  • As a good practice, this is safer to avoid usernames and passwords that contain non-English characters. Albeit our Zephyr script correctly encodes international usernames and passwords, their handling also depends on the configuration of the container that hosts your Jira web application (typically Tomcat). If you're having difficulties, just replace those characters in your username or password with English letters or numbers.

Finally, the following section describes a confusing situation when all REST API calls result in "Server returned HTTP response code: 403" or "401" errors. If you are not affected, you can skip this section.

Why does this happen? As its default behavior, Jira will lock your account and present a CAPTCHA on the login form after a few unsuccessful login attempts. Since the Zephyr integration may send several REST API requests per export, all using the same username and password, the unsuccessful login attempts limit can be reached very quickly if the password is wrong.

How to fix it? You just have to pass the CAPTHCA verification, that's it. First off, be 101% sure that the REST username and password are correct. If those are, but you are still receiving 403's, please open Jira in your browser, logout and login with the same user account which you configured for the REST calls. You will be asked for a CAPTCHA verification, but after answering that and logging in to Jira, the REST calls will also be successfully executed!

Please note that it will never happen again, unless you change the password of the corresponding Jira user account.

If you are an administrator, there is also a quicker solution: go to Administration → User management and clear the failed login attempts counter with one click. Or, you can increase the allowed login attempts or even disable this feature altogether in Jira.

Configuring the PDF templates for Zephyr

The template issue-fo.vm contains the following three configuration parameters in its top part, to enable these features:

## Zephyr
#set($exportZephyrTestSteps = true) ## set to "true" to export Zephyr test steps
#set($exportZephyrTestExecutions = false) ## set to "true" to export Zephyr test executions
#set($exportZephyrTestExecutionDetails = false) ## set to "true" to export Zephyr test step results (only used if $exportZephyrTestExecutions is also true)

For efficiency reasons, the Zephyr REST calls are made only for the issues with the "Test" type. This is a reasonable default and saves quite some computing time in most cases. If you like, you can alter this filtering logic by modifying this line in issue-fo.vm:

## Zephyr test steps
#if($issue.issueTypeObject.name == "Test")
	## ...

Learn more about Zephyr