UI scripts introduction

TestRail provides the ability to customize the user interface via so called UI Scripts. UI Scripts are a very flexible tool for administrators to customize parts of TestRail’s design and behavior by writing standard JavaScript code and by defining simple style sheets.

UI Scripts can be applied to single pages, multiple pages or even the whole application. You don’t need a special development environment or framework to write UI scripts, as you can simply define and test scripts directly in TestRail. Basic HTML, CSS and JavaScript knowledge is required to write UI Scripts, but it’s possible to learn this while writing your first simple scripts.

Writing UI scripts

UI Scripts can be defined in TestRail under Administration > Customizations. To start writing your first UI Script, click on Add UI Script and the editor will show a basic example.

In the next sections we will take a look at the three parts that make up a complete UI Script, and you can also take a look at our UI Scripts examples to get started.

Meta information

As UI Scripts are simple text blocks, you can directly define all meta information such as the name, author or version as part of the script. This allows you to easily share UI Scripts between TestRail installations by simply copying & pasting the script.

The first block of a UI Script contains some meta information that describe its functionality as well as define its scope (i.e. the pages to which the script is applied to).

name: Hello world
description: Shows a 'Hello, world!' message on the dashboard
author: Gurock Software
version: 1.0
includes: ^dashboard
excludes:

The name attribute is used as the script’s display name in TestRail’s list of UI Scripts, whereas description, author and version are merely intended for informational purposes for the developer.

The includes and excludes attributes define which pages the UI Script is applied to in TestRail. You can thus limit the scope of a customization with these attributes and execute a UI Script on specific pages only.

If a UI Script should only be executed on specific pages of the application, it’s highly recommended to limit the scope of the script via the includes and excludes attributes for performance reasons. For example, the includes attribute in the above example would apply the UI script to the dashboard only. The includes and excludes attributes are interpreted as regular expressions and are matched against TestRail’s pages argument (the query string after the index.php? part of the URL).

There are a few rules regarding how the filters are applied:

• The exclude filter always has precedence over the include filter.
• Empty strings for both the includes and excludes attributes (or omitting both properties) means that the UI Script will be applied to all pages.

There’s one exception to these rules: UI Scripts are never executed on the UI Script form itself to make sure that you can disable broken scripts if needed.

Style sheets

You can define (or override) style sheets with UI Scripts via the css attribute. Overriding TestRail’s built-in style sheets is the easiest way to customize TestRail’s user interface. For example, you can change the color of elements, change the look and feel of certain aspects of TestRail’s UI, or even completely hide parts of TestRail’s functionality if needed. You define the css attribute in a UI Script as follows:

css:
div.some-class {
  color: red;
}

TestRail directly applies the style sheet to all pages as defined by the scope. You can therefore use the full set of available CSS features to customize TestRail.

JavaScript

For more complex customizations you would usually use JavaScript in addition to or instead of style sheets. To define JavaScript code in your UI Script you can simply use the js attribute as follows:

js:
$(document).ready(
  function() {
    alert('Hello, world!');
  }
);

TestRail comes with the popular jQuery JavaScript library, and you can use jQuery’s full set of features. For example, it’s generally a good idea to use jQuery’s $(document).ready() event to wait until the current page has been fully loaded (as you can see in the above example).

Context information

TestRail provides some additional context information that you can use from your JavaScript code, such as details about the current user or project. You can use this context information to limit the execution of your scripts to specific user roles or projects, or leverage this data for integrating with external tools. The following context attributes are defined:

uiscripts.context.user

• id
• name
• email
• is_admin
• role_id

uiscripts.context.project

• id
• name

You can access the context information from your scripts as follows:

js:
  alert('Welcome ' + uiscripts.context.user.name);

Starting with TestRail 3.0, uiscripts.context contains additional details about the context of the current page and this can include:

• uiscripts.context.case
• uiscripts.context.milestone
• uiscripts.context.plan
• uiscripts.context.run
• uiscripts.context.suite
• uiscripts.context.test

Also new in TestRail 3.0 is uiscripts.env which contains details about the environment TestRail is running in. The following properties are available for uiscripts.env:

Performance considerations

As powerful and flexible as UI Scripts are, it’s important to understand the performance implications of your scripts and customizations. Using generic JavaScript selectors (e.g. applying code to all divs on page) can severely slow down the execution of JavaScript and increase the load time of pages.

As a general rule of thumb you should limit the execution of UI Scripts to the pages you actually want to customize, and to define the selectors for your JavaScript code as precisely as possible. The discussion of general JavaScript performance tips is outside the scope of this article, but there are some good resources about JavaScript and jQuery performance out there.