UI スクリプト：はじめに

TestRail では、「UI スクリプト」によってユーザー インターフェイスをカスタマイズすることが可能です。UI スクリプトは非常に柔軟な管理者向けツールであり、標準的な JavaScript コードを記述し、簡単なスタイルシートを定義することによって、TestRail の設計と動作の一部をカスタマイズできます。

UI スクリプトは、単一ページ、複数ページ、あるいはアプリケーション全体にも適用できます。TestRail で直接スクリプトを定義してテストできるため、UI スクリプトを作成するのに特別な開発環境やフレームワークは必要ありません。UI スクリプトを作成するには、基本的な HTML、CSS、および JavaScript の知識が必要ですが、初心者が簡単なスクリプトを作成しながら知識を学ぶことは可能です。

UI スクリプトの作成

UI スクリプトは TestRail の[管理 ]> [カスタマイズ]で定義できます。初めて UI スクリプトを作成する場合は、[UI スクリプトの追加] をクリックするとエディターに基本的な例が表示されます。

次のセクションでは、UI スクリプトを構成する 3 つの部分を見ていきます。また、UI スクリプトのサンプルを参照することもできます。

メタ情報

UI スクリプトは単純なテキストブロックであるので、名前、作成者、バージョンなどのすべてのメタ情報をスクリプトの一部として直接定義できます。そのため、スクリプトをコピー＆ペーストするだけで、複数の TestRail の間で UI スクリプトを簡単に共有できます。

UI スクリプトの先頭のブロックには、スクリプトの機能やスコープ (スクリプトの適用先ページ) を説明するメタ情報が含まれています。

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

name属性は、TestRail の UI スクリプトのリストでスクリプトの表示名として使用されますが、description、author、および version は、開発者向けの情報提供のみを目的としています。

includes 属性と excludes 属性は、TestRail で UI スクリプトが適用されるページを定義します。したがって、これらの属性を使用してカスタマイズの範囲を制限し、特定のページに対してのみ UI スクリプトを実行できます。

UI スクリプトをアプリケーションの特定のページだけに実行する必要がある場合は、パフォーマンス上の理由から、includes および excludes 属性を使用してスクリプトの範囲を制限することを強くお勧めします。たとえば、上記の例の includes 属性は、ダッシュボードにだけ UI スクリプトを適用します。includes および exclude 属性は正規表現として解釈され、TestRail の pages 引数 (URL の index.php? の後のクエリー文字列) と照合されます。

フィルターの適用方法に関していくつかの規則があります。

• • exclude 属性は常に includes 属性よりも優先されます。
  • includes 属性と exclude 属性の両方に空の文字列を指定 (または両方のプロパティを省略) すると、すべてのページに UI スクリプトが適用されます。

これらの規則には 1 つ例外があります。必要なときに壊れたスクリプトを無効にできるように、UI スクリプト フォーム自体に UI スクリプトは実行されません。

スタイル シート

css 属性を使用すると、UI スクリプトでスタイル シートを定義 (または上書き) できます。TestRail のビルトイン スタイル シートを上書きすることは、TestRail のユーザーインターフェイスをカスタマイズする最も簡単な方法です。たとえば、要素の色を変更したり、TestRail の UI の一部のデザインを変更したり、必要であれば TestRail の機能の一部を完全に隠したりすることもできます。UI スクリプトでは次のように css 属性を定義します。

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

TestRail はスコープの定義に従ってスタイル シートをページに直接適用します。そのため、CSS 機能のフルセットを使用して TestRail をカスタマイズできます。

JavaScript

より複雑なカスタマイズの場合は、通常、スタイル シートに加えて、またはスタイル シートの代わりに JavaScript を使用します。UI スクリプトで JavaScript コードを定義するには、次のように js 属性を使用します。

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

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

TestRail には、広く使用されている JavaScript のライブラリーである jQuery が付属しており、 全機能を使用できます。たとえば、上の例のように、現在のページが完全にロードされるまで待機するには、jQuery の $(document).ready() イベントを使用するのがお勧めです。

コンテキスト情報

TestRail は、現在のユーザーまたはプロジェクトに関する詳細など、JavaScript コードから使用できるいくつかの追加のコンテキスト情報を提供します。このコンテキスト情報を使用して、スクリプトの実行を特定のユーザー ロールまたはプロジェクトに限定したり、外部ツールとの統合にこのデータを活用したりできます。以下のコンテキスト属性が定義されています。

uiscripts.context.user

• • id
  • name
  • email
  • is_admin
  • role_id

uiscripts.context.project

• • id
  • name

次のようにして、スクリプトからコンテキスト情報にアクセスできます。

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

TestRail 3.0 以降では、uiscripts.context に現在のページのコンテキストに関する追加の詳細が含まれています。以下の情報があります。

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

TestRail 3.0 のもう 1 つの新機能は、uiscripts.env です。uiscripts.env は、TestRail が実行されている環境についての詳細を提供します。uiscripts.env には、以下のプロパティがあります。

Name	説明
is_hosted	TestRail Cloud を使用している場合は true、オンプレミスで使用している場合は false
page_base	TestRailのindex.php エンドポイントのベースアドレス。(例えば “index.php?”)これにより、TestRail のページへのリンクを動的に生成できます。
resource_base	TestRail の静的リソース (画像、JSファイルなど) を参照するためのベース アドレス。例： “https://static.testrail.com/<version>/”

パフォーマンスの考慮事項

UI スクリプトは強力で柔軟性がありますが、スクリプトとカスタマイズがパフォーマンスにもたらす影響を理解することが重要です。汎用的な JavaScript セレクターを使用する (例えば、ページ上のすべての div にコードを適用する) と、JavaScript の実行が大幅に遅くなり、ページのロード時間が長くなる可能性があります。

一般的な経験則として、UI スクリプトの実行は実際にカスタマイズしたいページに限定し、JavaScript コードのセレクターをできるだけ限定的に定義する必要があります。一般的な JavaScript のパフォーマンスに関してはこのドキュメントでは取り扱いません。