Zephyr Squad Integration

In this page

What is Zephyr Squad?

(supported since Better PDF Exporter 5.5.0)

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

Zephyr Squad integration features

• Zephyr Squad tests are regular Jira issues. This enables creating self-containing PDF exports from Zephyr Squad tests that contain issue field values, attachments, comments and the following test step data: test step instructions, test step data and expected result.
• 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.

(Need more features? Tell us in a support ticket!)

Zephyr Squad integration vs. the Zephyr Squad built-in PDF exports

You may want to ask: if Zephyr Squad has a built-in PDF export feature, why would you use another app for the same?

While the Zephyr Squad built-in PDF exports may be sufficient for basic use cases, the Better PDF Exporter integration is more powerful in, at least, these:

• It supports PDF automation.
  You can export, email and attach PDF files using Automation for Jira (visual automation rules), ScriptRunner (Groovy scripts), or the REST API (use your favorite language!).
• It is extremely customizable.
  Instead of accepting the pre-defined export types in Zephyr Squad, you can define your own types via PDF templates.
• It supports all the powerful PDF features.
  You can use custom calculations in Groovy (sorting, complex math, data integration, etc.), embedded attachments, PDF bookmarks, charts, graphics (in Groovy, SVG, QR codes and barcodes, etc.), among others.
• It is integrated with all the popular Jira apps.
  You can freely combine Zephyr Squad data and other apps' data in the same PDF file.
• It comes with powerful templates optimized for Zephyr Squad.
  You can use those "as is", or customize them to your needs.
• It is well-documented with the customization guide, the Expression Reference Manual, the recipes, and such.

If at least one of these is important for you, give the app a try.

Tutorial video

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

Zephyr Squad PDF export samples

Configuration

Installing ZAPI

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

What does the "or" mean?

• Zephyr Squad versions before 5.6.0 do not provide a public API. Instead, there exists a separate app called ZAPI to provide a REST API for Zephyr Squad tests, test executions and such.
  Notes:
  • ZAPI is also developed by the SmartBear/Zephyr Squad team.
  • 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.
• Zephyr Squad 5.6.0 or newer versions provide a public API. There is no need for ZAPI with these Zephyr Squad versions.

Therefore, when using Zephyr Squad versions earlier than 5.6.0, please install ZAPI as the initial step.

Configuring the Zephyr Squad REST API access

As this integration relies on the Zephyr Squad 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 Administration → Add-ons → PDF 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!):

   ## issue-fo.vm
   
   ## 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 anyway.)

Notes:

• If you are using multiple REST API based integrations in the same template (ex: Git Integration, Gliffy, Zephyr Squad), then all REST API calls will use with the same user credentials.
• It is safer to avoid usernames and passwords that contain non-English characters. Albeit our Zephyr Squad 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.
• Similarly, it is safer to avoid usernames and password that contain special characters (most typically "#" and "$"). These are special control characters in Velocity strings. If you can't avoid those, escape the characters according to the language rules.

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 Squad 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 Zephyr Squad PDF templates

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

## issue-fo.vm

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

Note that the issue-fo.vm template makes the Zephyr Squad REST calls only for the issues that are actual Zephyr Squad tests. It decides whether an issue is a Zephyr Squad test by checking its issue type name (if it is a "Test") and its custom fields (e.g. if it has the "Test Steps" custom field). Therefore, if you rename issue types, you also need to adapt the logic around this part in the template code:

## issue-fo.vm

## test management data
#set($testManagementIssueTypeNames = ['Pre-Condition', 'Test', 'Test Execution', 'Test Plan', ...])
#if($testManagementIssueTypeNames.contains($issue.issueTypeObject.name))
	## ...

Learn more about Zephyr Squad

• Zephyr Squad product information (at its own vendor)
• Zephyr Squad documentation
• Zephyr Squad app page (on the Atlassian Marketplace)