TestRail 3.0 introduced a new Reports area with support for generating, scheduling, sharing and emailing reports. While TestRail already comes with many powerful generic report templates built in, it can also be useful to write custom reports, be it to visualize your data from a different angle or to aggregate and display it in a way that is not covered by the built-in reports.
This documents explains the basic structure of custom reports, how to integrate them into your installation and best practices. Please note that this document assumes basic knowledge of PHP, SQL as well as web development (HTML, CSS and JavaScript). Implementing custom reports requires experience with all of the above technologies.
Terminology
TestRail uses the following terminology to differentiate between the different report related entities:
Report
Reports are generated HTML-based documents and all the associated files. Reports usually display charts and statistics to visualize your data. Reports can be private or shared across all users in a given project.
Report job
Reports can be scheduled in configurable intervals and a report job defines the schedule and stores all related settings. Report jobs are also called scheduled reports in TestRail’s UI.
Report format
A report can be viewed inside TestRail (inline) or outside of TestRail (standalone). When a report is generated, TestRail post-processes it and saves it into different so called report formats.
Report plugin
The report plugin implements the actual generation of the viewable reports. Report plugins are self-contained and reusable bundles of PHP files and HTML assets (style sheets, JavaScript files and images). Report plugins implement or solve a specific problem (e.g. displaying the result coverage for test cases) and can be configured by passing report options.
Report form
When you create or edit a (scheduled) report you do this on the report form. The report form is divided into two sections. The first section configures the so called custom options for the report and this section looks different for every report plugin. The second section defines the system options (access, notifications and scheduling) and is the same for all report plugins.
Getting started
There are two directories where TestRail looks for report plugins when the application is initialized. The first directory is where TestRail also stores its built-in default plugins. You should never add or modify plugin scripts in this directory, as those files will be overridden when you update TestRail:
<TestRail>/app/plugins/reports
Modified or new plugin scripts should always be placed into the custom report plugin directory:
<TestRail>/custom/reports
The easiest way to get started with TestRail’s report plugins is to use the following GitHub repository. You can use this template as reference but it’s still recommended to begin with an empty directory for new report plugins and create/copy the template files one by one.
$ git clone https://github.com/gurock/testrail-custom.git
$ ls testrail-custom/reports/template
about.json
i18n/
images/
js/
report.php
styles/
views/Plugin structure
As you can see from the example template, a report plugin is a simple directory and contains the actual PHP module of the plugin (report.php), a description file (about.json) and several sub directories that contain HTML assets (images, js, styles) as well as language files and views (used for rendering the report). The following sections explain the different objects in detail.
about.json
This file serves as the plugin description file and specifies the meta data of the report plugin such as the label (name), description and author. It uses JSON and looks as follows:
{
"author": "Gurock Software",
"version": 1,
"label": "l:reports_tmpl_meta_label",
"summary": "l:reports_tmpl_meta_summary",
"description": "l:reports_tmpl_meta_description",
"group": "l:reports_tmpl_meta_group",
"translations": ["reports_tmpl"]
}TestRail is fully translatable and this also includes reports. To translate a report, you can include one or more “translation” files which are loaded automatically by TestRail when the report plugin is initialized.
The label and group define how the report plugin appears in the sidebar on the report overview page in TestRail. The summary and description fields should be a brief/somewhat longer description of what the report plugin does.
By convention, strings that start with ‘l:’ are interpreted as strings from the translation file (please see below).
i18n/
This directory contains the translation files of the report plugin and this should contain the file you’ve specified previously in about.json, e.g. reports_tmpl.php. The full relative path for this file should then be:
i18n/translations/en/reports_tmpl.php
The path follows the same conventions as the standard translation system of TestRail. The content of the file specifies the translated strings:
$lang['reports_tmpl_meta_label'] = 'Template';
$lang['reports_tmpl_meta_group'] = 'Template Group';
$lang['reports_tmpl_meta_summary'] = 'Demonstrates how to develop \
custom report plugins.';
$lang['reports_tmpl_meta_description'] = 'Demonstrates how to develop \
custom report plugins and serves as a skeleton for new report \
plugins.';
..report.php
This file contains the actual PHP based implementation of the report plugin. TestRail expects a class with the name of the report plugin directory followed by “_report_plugin”:
class Template_report_plugin extends Report_plugin
{
}
..This class is expected to implement several methods for rendering and validating the report form and options as well as generating the actual report.
views/
This directory contains the views of the report plugin used for the rendering process of a report. The views are standard PHP files which are loaded by the report plugin and generate the actual HTML documents.
Building your own plugin
Read on to find out how to write custom reports and to learn more about the inner workings and structure of report plugins: