Creating test reports is an essential part of software testing, but manually compiling information from Jira can quickly become repetitive and time consuming. Whether you're preparing evidence for an audit, sharing release progress with customers, or documenting test coverage, reporting should help your team, not slow it down.
In our latest Xray Document Generator Workshop, we explored how Document Generator helps automate reporting with reusable templates that combine Jira and Xray data into professional documents. If you missed the live session, we've included the full recording below so you can follow every demonstration at your own pace:
What is Xray Document Generator?
Document Generator is Xray's reporting solution for Jira. It enables teams to create reusable templates that automatically generate reports using Jira and Xray data.
Instead of manually collecting information every time a report is needed, you create a template once and use it whenever you need it. Reports can include requirements, tests, test executions, test plans, defects, traceability information, and native Jira data depending on how the template is configured.
Templates are available for both Word and Excel, and reports can also be exported as PDF for easy sharing with stakeholders who do not have access to Jira.
Understanding where Document Generator adds value
The workshop began by exploring the most common reporting scenarios where teams use Document Generator.
Some of the most common use cases include:
- Compliance and regulatory reporting, where testing evidence needs to be preserved for audits.
- Sharing reports with customers, executives, and auditors who do not have access to Jira.
- Maintaining testing records that provide a historical snapshot of testing activities and release readiness.
The session also explained the different report types available out of the box, including:
|
Report |
Best used for |
|
Test Report |
Documenting individual test specifications |
|
Test Execution Report |
Summarizing execution results, defects, and covered requirements |
|
Test Plan Report |
Reporting on planned or completed testing activities |
|
Test Set Report |
Reviewing the tests contained within a Test Set |
|
Requirement Traceability Report |
Demonstrating traceability between requirements, tests, executions, and defects |
|
Excel Reports |
Exporting structured data for analysis and filtering |
One useful takeaway from the session was the distinction between report formats. Word templates are designed for structured, presentation-ready reports, while Excel templates focus on exporting tabular data for further analysis.
Building reports with existing templates
One of the most practical demonstrations showed how quickly teams can start using Document Generator without creating templates from scratch.
The session walked through:
- Installing a template from the Document Generator Store.
- Configuring its scope and output settings.
- Generating a report directly from a Test Execution.
- Reviewing the final document.
The generated report included a cover page, execution summary, covered requirements, execution status, defects, evidence, comments, attachments, and detailed test information, demonstrating how much information can be generated automatically from existing Jira and Xray data.
The key takeaway was simple: start with an existing template whenever possible. Most reporting needs can be met by customizing an existing template instead of building one from scratch.
Creating custom templates from scratch
The second live demonstration focused on building a custom template using a blank Word document.
Rather than simply explaining the concepts, the workshop showed how templates are built incrementally using several core Document Generator capabilities:
Mappings
Mappings are placeholders that retrieve information directly from Jira and Xray when a report is generated. Because the data is populated dynamically, the same template can be reused across multiple projects and issues.
Iterations
Iterations automatically loop through related information, making it possible to generate detailed reports without manually repeating sections. During the demonstration, iterations were used to navigate from a Test Plan to its associated Tests and then into the individual Test Steps for manual tests.
Conditional blocks
Conditional blocks determine whether content should appear in the final report. A practical example demonstrated how to display detailed test steps only for manual tests, preventing unnecessary sections from appearing for Generic or Cucumber tests.
Native Jira data
The workshop also demonstrated how Document Generator combines Jira and Xray information within the same report by retrieving native Jira entities such as issue links alongside Xray testing artifacts.
Best practices for building templates
The workshop concluded with several recommendations that can save teams time when building their own templates.
- Start with an existing template. Customize it before deciding to build a new one.
- Build incrementally. Add one section at a time, generate the report, validate the output, and then continue.
- Keep reports focused. Include only the information your audience needs.
- Maintain clean testing data. Well-organized Jira and Xray projects make reports easier to generate and maintain.
These recommendations not only simplify template development but also make troubleshooting much easier as templates become more sophisticated.
Watch the full workshop
This article covers the main highlights, but the live demonstrations provide much more detail on how each feature works in practice.
Watch the full workshop below to see Document Generator in action, follow each step of the template-building process, and learn how to create reports tailored to your own reporting requirements.
FAQ: Xray Document Generator
What is Xray Document Generator used for?
Xray Document Generator automates report creation using Jira and Xray data. It helps teams generate reusable reports for compliance, stakeholder communication, testing documentation, and traceability.
Can I customize the built-in Document Generator templates?
Yes. The templates available in the Document Generator Store are fully customizable. You can modify existing templates or use them as the starting point for your own reports.
Can Document Generator include both Jira and Xray data?
Yes. Reports can combine Xray artifacts with native Jira information, including issue links, comments, attachments, and other supported Jira entities.
Should I build templates from scratch?
Not necessarily. The workshop recommends starting with an existing template whenever possible. Building from scratch is best suited for reporting requirements that cannot be met through customization.
Where can I learn more about building custom templates?
The workshop recording demonstrates the complete template-building process, while the Xray documentation provides detailed guidance on mappings, iterations, conditional blocks, native Jira data, and other advanced features.
