Zephyr Squad Integration

In this page

What is Zephyr Squad?

(supported since Better Excel Exporter 3.2.0)

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

Zephyr Squad integration features

• You can export the test steps for any test list. Zephyr Squad tests are regular Jira issues. This enables creating Excel files that contain issue field values and the following test step data: test step instructions, test step data and expected result.
• You can export the test executions for any test list. Executions are exported with their details for a comprehensive report: ID, test cycle, version, execution status, assignee, executor user, execution date, execution defects, step defects and comments.
• You can export the test step results of the test executions for detailed test reports. The following details are exported for each step: ID, step instructions, test data, expected result, execution status, and comments.
• Better Excel Exporter offers ready-made report templates to calculate test results by projects, test cycles, versions and testers. It also comes with reports for testers workload and for execution-level and step-level defects. Although these are useful as is, they can also be used as a starting point to create custom Excel reports from Zephyr Squad data.

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

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

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

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

• It supports Excel automation.
  You can export, email and attach Excel 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 Excel templates.
• It supports all the powerful Excel features.
  You can use Excel formulas and functions, custom calculations in Groovy (sorting, complex math, data integration, etc.), charts, pivot tables, pivot charts, Visual Basic macros, 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 Excel 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 Excel reports!

Zephyr Squad Excel export samples

Configuration

Configuring the Zephyr Squad Excel views

Note that the Zephyr Squad custom fields will be available in every Excel view. There are additional views that are specific to Zephyr Squad and are disabled by default. Don't forget to activate those!

Steps:

1. Login to Jira as administrator.
2. Go to Administration → Add-ons → Excel Views (under Better Excel Exporter).
3. Click the view Zephyr Test Steps (All f.).
4. Check the contexts (screens) in which you want this integration be available. (If unsure, check Issue Navigator at least.)
5. Click Save.

Repeat this also for the following views:

• Zephyr Test Steps (Curr. f.)
• Zephyr Executions (All f.)
• Zephyr Executions (Curr. f.)
• Zephyr Step Results (All f.)
• Zephyr Step Results (Curr. f.)
• Zephyr Report (Excel)

Installing ZAPI

The Zephyr Squad and Better Excel 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 → Excel Templates (under Better Excel Exporter).
2. Open the zephyr-tool.groovy 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!):

   // zephyr-tool.groovy
   
   /* Zephyr Squad REST API request parameters. */
   def restUserName = "admin"
   def restPassword = "admin"
   

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:

• 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 Groovy 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.

Troubleshooting

Only the first 1000 Zephyr Squad tests and executions are exported

This is a limit exposed by the Zephyr Squad API for performance reasons. (Their documentation does not mention anything about lifting this limit, so you are encouraged to contact their support team.)

"Executed On" does not include the time part (only the date)

The Zephyr Squad API returns this field as date-only (ex: "29/Aug/17"), albeit this is a complete date-time in the Zephyr Squad web UI (ex: "2017/08/29 10:56").

We consider this a design issue in the Zephyr Squad API and reported this to the Zephyr Squad team.

When exporting step results, "Step", "Test Data", "Expected Result" and "Comment" texts are joined to a single-line string

The Zephyr Squad API returns these fields without line-breaks.

We consider this a design issue in the Zephyr Squad API and reported this to the Zephyr Squad team.

When exporting step results, step defects are not associated with the steps, but with the executions

The Zephyr Squad API returns the defects (including both execution-level and step-level defects) in the format "BUG-1, BUG-2 | BUG-3, BUG-4". In this string the issue keys before the pipe character are execution-level defects, while the ones after the pipe are step-level ones. From this information, one can separate execution-level defects from step-level defects, but cannot know which step the step-level defects are associated with.

We consider this a design issue in the Zephyr Squad API and reported this to Zephyr Squad team.

I am using some older Zephyr Squad version and the export does not work

Our integration party relies on the /execution/export API end-point provided by the Zephyr Squad API. The XML document format generated by this API end-point has been changed multiple times before it reached its current shape. Therefore, our integration works with 3.2.0.32002611 and newer Zephyr Squad versions.

Please note that this is possible to re-configure the zephyr-tool.groovy script for older Zephyr Squad versions if you are restricted to one of those. In that case, just contact us.

Learn more about Zephyr Squad

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