TestRail API へのアクセス

TestRail の API は HTTP ベースであり、単純な HTTP リクエストを使用して対話できます。すべての書き込みリクエストは HTTP POST メソッドを使用し、すべての読み取りリクエストは HTTP GET メソッドを使用する必要があります。データは UTF-8 エンコーディングの JSON 形式で転送されます。

認証

TestRail は、API の認証情報が標準的な HTTP ベーシック認証によって指定されると期待します。TestRail で API リクエストを認証する方法は2つあります。

ユーザー名とパスワード

標準の TestRail ユーザー名 (通常は電子メールアドレス) と TestRail パスワードを TestRail に渡して API 認証を行うことができます。これは HTTP のベーシック認証で送信する必要があります。

TestRail 認証の設定によっては、パスワードが通常の Active Directory または LDAP のパスワードである場合もあります (TestRail の設定によって異なります。詳細は認証ガイドを参照してください)。TestRail でどのオプションが使用されているかわからない場合は、TestRail 管理者にお問い合わせください。

$ curl -H "Content-Type: application/json" \ 
  -u "user@example.com:{some-password}" \
  ..

ヘッダーが定義されており、-H で始まり、ユーザー認証情報の後の 2 つめの \で終わっています。

ユーザー名と API キー

別の方法として、TestRail は API キーもサポートします。API キーは TestRail の [個人設定] で生成できます。API キーを使用する場合も、HTTP のベーシック認証を使用して TestRail のユーザー名 (メールアドレスなど) を送信します。パスワードを任意の生成されたまたはアクティブな API キーで置き換えます。複数の API キーを生成してシステムまたはサードパーティ製ツールごとに使い分け、 [個人設定] で API キーを削除することで、いつでもアクセスを取り消すことができます。

$ curl -H "Content-Type: application/json" \
  -u "user@example.com:{api key}" \
  ..

API スクリプト リポジトリ

パブリックな GitHub リポジトリにサンプル API スクリプトがあります。そのままで、あるいは簡単な変更だけでお客様のニーズに合うスクリプトが見つかるかもしれません。TestRail カスタマイズ GitHub リポジトリを参照してください。

このリポジトリには、他のユーザーの役に立つ可能性がある自作のスクリプトをサブミットできます。

GET リクエストの例

次の例は、テスト ケースを読み取る単純なリクエストを示しています。この例では cURL コマンドラインツールを使用してリクエストを送信していますが、どの HTTP ツールまたはライブラリでも機能します。すべてのユーザー名、パスワード、および URL はサンプルです。

$ curl -H "Content-Type: application/json" \
  -u "user@example.com:APIkey" \
  "https://example.testrail.com/index.php?/api/v2/get_case/1"

リクエストの各部分の詳細：

部分	説明
“Content-Type: application/json”	必須ヘッダー
https://example.testrail.com/	サーバー アドレス
index.php?/api/v2/	TestRail API のパス
get_case	呼び出される API メソッド
/1	API メソッドへの引数

実際の HTTP リクエストとレスポンスは次のようになります (簡略化されています)。

GET /index.php?/api/v2/get_case/1 HTTP/1.1
Host: example.testrail.com
Content-Type: application/json

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "id":1,
  "title":"An example test case"
  ..
}

POST リクエストの例

次の例は、テスト結果を送信する単純な書き込みリクエストを示しています。

$ curl -H "Content-Type: application/json" \
  -u "user@example.com:" \
  -d '{ "status_id": 1 }' \
  "https://example.testrail.com//index.php?/api/v2/add_result/1"

リクエストとレスポンスは次のようになります (簡略化されています)。

POST /index.php?/api/v2/add_result/1 HTTP/1.1
Host: example.testrail.com
Content-Type: application/json

{ "status_id": 1 }

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "id":1,
  "test_id":1,
  "status_id":1
  ..
}

添付ファイル アップロードの例

次の例は、テスト結果に添付ファイルを追加する単純な書き込みリクエストを示しています。

$ curl -H "Content-Type: multipart/form-data" \ 
  -u "user@example.com:" \ 
  -F "attachment=@C:\\image.jpg" \ 
  "https://example.testrail.io/index.php?/api/v2/add_attachment_to_result/1"

リクエストとレスポンスは次のようになります (簡略化されています)。

POST /index.php?/api/v2/add_attachment_to_result/1 HTTP/1.1
Host: example.testrail.io
Content-Type: multipart/form-data

{"attachment_id":11}