In this page

What is Zephyr?

(supported since Better Excel Exporter 3.2.0)

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

Zephyr integration features

  • You can export the test steps for any test list. Zephyr 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 data.

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

Zephyr integration vs. the Zephyr built-in Excel exports

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

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

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 tests to Excel reports!

Zephyr Excel export samples

Zephyr test steps

Zephyr test cases are Jira issues of the "Test" type. This export example generated from the issue-navigator-with-test-steps.xlsx Excel template shows a mix of regular issue fields in the left (key, summary, priority) and Zephyr test step details in the right (instructions, test data, expected result).


Zephyr test executions

Export Zephyr test execution reports to Excel easily! Run a JQL search in Jira to find any arbitrary set of Zephyr tests, then generate a filterable, searchable, shareable, grouped list of their test executions.


Zephyr test step results

This highly detailed Excel export captures the Zephyr test results in three logical levels: tests, test executions for each test, and test step results for each test execution. Being a complete snapshot of testing data, you can search this, import this to external systems, use it for archiving purposes, etc.


Zephyr test report

You can also export custom Excel reports from Zephyr test data. The zephyr-report.xlsx template gives a valuable overview of test executions per version, test cycle and tester, shows the test execution history, and shows which tests and executions discover the most defects. Build your own Zephyr Excel reports by copying this template.



Configuring the Zephyr Excel views

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


  1. Login to Jira as administrator.
  2. Go to AdministrationAdd-onsExcel 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 and Better Excel Exporter integration relies on the REST API provided by Zephyr itself or by ZAPI.

What does the "or" mean?

  • Zephyr 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 tests, test executions and such.
    • ZAPI is also developed by the SmartBear/Zephyr team.
    • ZAPI is free since version 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 5.6.0 or newer versions provide a public API. There is no need for ZAPI with these Zephyr versions.

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

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-onsExcel 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 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.)


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


Only the first 1000 Zephyr tests and executions are exported

This is a limit exposed by the Zephyr API for performance reasons. (Their documentation does not mention 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 API returns this field as date-only (ex: "29/Aug/17"), albeit this is a complete date-time in the Zephyr web UI (ex: "2017/08/29 10:56").

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

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

The Zephyr API returns these fields without line-breaks.

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

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

The Zephyr 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 API and reported this to Zephyr team.

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

Our integration party relies on the /execution/export API end-point provided by the Zephyr 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 and newer Zephyr versions.

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

Learn more about Zephyr