テストケースの関連付け作業を簡単にするためにAzure DevOps REST APIを使ってTest Plansに登録されているTest Caseの更新をしてみた｜前編

SHIFT Group 技術ブログ

2022年12月12日 08:00

はじめに

こんにちは！SHIFTでテスト自動化アーキテクトをしている木村です。

今回はAzure DevOpsが提供しているREST APIを用いて、Test Plansに登録されているTest Caseの結果を更新してみましたので、その内容について書いていきたいと思います。

内容が盛り沢山なので、前編・後編に分けて紹介したいと思います。まずは前編として、APIを実行できる環境作りと更新手順について、書いていきたいと思います。

Azure DevOps REST APIとは

Microsoftが提供している、Azure DevOpsを操作するためのREST APIであり、以下のようなREST APIを実行することで、Azure DevOpsに対して、アプリケーションから様々なことができるようになります。

https://dev.azure.com/{organization}/{project}/_apis/{area}/{resource}?api-version={version}

Webにリファレンスが公開（https://learn.microsoft.com/en-us/rest/api/azure/devops/?view=azure-devops-rest-7.1）されていますので、こちらを参照しながら、組み込みたい機能を追加していく形になります。

実装する前に・・・

これをお読みになっている読者の中には、「Test Plansに登録したTest CaseはVisual Studioと統合できるから、それでテスト結果も登録されるし、わざわざAPIを使わなくてもいいんじゃないの？」という疑問があるかと思います。

はい。確かにその通りです。

Visual StudioにてTest Explorerにて統合したいテストを選択して、コンテキストメニューから「Associate to Test Case」を選択します。

表示されたダイアログにTest PlansのTest Case IDを入力して「Add Association」ボタンをクリックすると、該当のテストケースと紐づけることができ、紐づけを実行後、Test Plansからテストを実行すると、結果がTest PlansのTest Caseにて確認できます。
この対応で問題ない方は、こちらのやり方が簡単ですので、おススメです。

なぜAPIを使うのか

ただ、この処理ですが、テストケースが数千個に及ぶと、非常に手間がかかってしまいます。
これを別の方法で、一括登録できないかと検討したのですが、よいソリューションがなかったため、アプリケーションで対応できないかを探していたたところ、Azure DevOps APIを発見しました。
これを使用すると、アプリケーションからTest Plansに登録されたTest Caseの情報をまとめて対応できると考えました。

やりたいこと

Test Plansに登録されてるテストを、個々のTest Plansを選択して実行するのではなく、Pipelineからまとめて実施することを考えます。
テストコードとしては、TestMethodとなるテストケースを1つとし、それを実行すると、そのテストケースから、Test Plansに登録しているTest Caseを順次実行するということを考えます。
また、テスト結果にはエビデンスとなるスクリーンショットを登録し、成功と失敗を登録することとします。

こうすることで、Visual Studioで連携するTest Methodは一つでよく、後はそこから実行するTest Caseをアプリケーション上で追加、編集、削除できるため、テストのコードを変更することで対応が可能となります。
その際、Azure DevOps APIを使用して、Test Plansに登録されたTest Caseの情報を更新します。

Azure DevOps APIを使ってみる

APIを投げてみる

さて、方針が決まったので、まずはAPIが実行できるかどうかの調査を開始しました。APIの基本URLとしては、上記に記載の通り、

https://dev.azure.com/{organization}/{project}/_apis/{area}/{resource}?api-version={version}

となっています。{organization}/{project}には使用しているAzure DevOpsのURLに記載されている組織とプロジェクト名を入力する形になります。[area]/[resource]については、どのサービスを利用し、何をどうするかによって異なりますので、リファレンスを参考にしてください。
最後に、そのAPIのどのバージョンを使用するかを[version]に入力します。

ということで、これで何か試しにリクエスト出してみることにしました。
まずはTest Plansに登録されているTest Caseにどのようなものがあるかを取得できないかということで、以下のAPIを投げてみました。

Test Suites - List
GET /test/Plans/{planId}suites/{suiteId}/testcases

{planId}にはTest PlansのIDを入力し、{suiteId}にはTest SuiteのIDを入力します。それぞれ、Test PlansのURLに以下のようになっているはずです。

これで、Test Caseの情報が取得できる！きっとJSONで結果が返ってくるから、それをパースして。。。と思ったら、応答はHTMLでかえってきました。エラーになっているようです。

ん、、、これじゃない。

と思ってリファレンスを読むと、こんな記載がありました。

HTTP ヘッダーを使用して個人用アクセストークンを指定する場合は、まずそれを Base64 文字列に変換する必要があります

個人用アクセストークン？はて、それはいったい。。。

個人用アクセストークンの発行

上記の対応で情報が取得出来たら、URLがわかったら、簡単に情報が引っこ抜ける状態になってしまうので、当然アクセス制限がかかっています。
そのアクセス制限に使われるのが個人用アクセストークン（Personal Access Token:以下PAT）になります。
APIのリクエスト送信時には、Base64変換したこのPATをHTTPのヘッダーのBasicに設定する必要があります。

このPATですがAzure DevOpsから発行する必要があります。
Azure DevOpsのページの右上にあるUser Settingメニューをクリックし、メニューの「Personal access tokens」をクリックします。

表示される画面のNew Tokenをクリックします。

新規作成画面が表示されるので、名称、有効期限を入力して、ScopesをCustom definedに指定します。
こうすることで、意図しない機能の変更を防ぐことができます。

そして肝心の許可を与えるところになりますが、Show all scopesをクリックして、すべてのスコープを表示します。
スクロールを下げていき、以下のスコープにチェックを入れます。

Test Plansを変更するので、Test Managementの読み書き権限が必要なことは理解できるかと思います。
また、Test CaseのテストはWork Itemとして扱われるので、Work Itemsの読み書き権限が必要なことも理解できるかと思います。
いったんこの状態でAPIを実行してみましたが、なぜか先ほどのAPIにおいて、データが取得できませんでした。
そこで、下記の権限も追加しました。

これにより、APIの結果が正しいJSONで取得できるようになりました。
上記のスコープを追加しないと正しくデータが取得できませんので、ご注意ください。この状態で、Createボタンをクリックして、PATを作成します。完了すると、Tokenが発行されますので、これをコピーします。
このトークンはこの画面でした見れませんので、ご注意ください。

再びAPIを投げてみる

PATが準備できたので、再び上記のAPIを実行してみます。

Test Suites - List
GET /test/Plans/{planId}suites/{suiteId}/testcases

以下のような結果が返ってきました

  {"value":[
    {
     "testCase":
     {
       "id": "123456",
       "url": "xxxxx",
       :
     },
     "pointAssignments":[
       {
         :
       }
     ]
   },
   :
 ]}

valueの中にテストケース分の情報が入っており、testCaseの中のidでTest CaseのIDを取得できることが分かったので、このIDを指定することで、Test Caseの情報を変更できるところまでたどりつきました。

テストの結果を登録する処理を検討する

ようやくTest Plansを編集することができる！と思ったのも束の間、APIリファレンスのTest Casesを見てみると、

ん？Updateがありませんね。では、Test Suitesの方を見てましょう。

おぉ、Updateありますね。では、Updateの詳細は

Test Suites - Update
PATCH　 /testplan/Plans/{planId}/suites/{suiteId}

あれ、Test Caseの指定ないですね。
なるほど、これはTest Suiteの更新なので、各ケースではなく、Test Suiteの情報更新ですね。となると、どうしたらいいのか。
調べた結果、各テストの実行はWork Itemの単位で作成され、それを作成するのに、TestRunを作成する必要があることがわかりました。
したがって、個々のテストケースに対するテスト結果を登録する処理の最終的な流れは以下のようになります。

流れがわかったので、さっそくTestRunを作成するために、以下のAPIを実行してみることにしました。

Runs - Create
POST /test/runs

POSTメッセージなので、リクエストのBodyに必要な情報を入れないといけません。なるほど、ここで、Test Case IDを使うわけですね。。。
あれ、パラメータにない。。。Test PlanのIDはあるものの、Test Case IDを設定するところがありません。代わりに以下の記述を見つけました。

pointIds？これはいったい何だろう。。。と調べてみると、Test Case IDと紐づくTest Point IDとなる値があることが判明。
これを取得するには以下のAPIを実行する必要があります。

Test Point - Get Points List
GET /testplan/Plans/{planId}/Suites/{suiteId}/testpoint

この応答で取得できるTest Point IDを指定することで、TestRunの作成ができ、そこに情報を追加していくことで、テスト結果を蓄積することができます。このPoint IDは各Test Caseに割り当てられているので、一度このPoint IDを取得して、情報として記憶しておけば、テスト実行のたびにこれらを再度取得する必要はありません。
これで準備が整ったので、次は実際に結果を更新する実装を進めたいと思います。

前編のまとめ

いかがでしたか。前編では、APIを使用するための準備と、Test Caseに実行結果を追加するための流れについて記載しました。
なかなか実行するまでに、手間がかかったかと思います。
後編では各APIの具体的な使用方法と流れに沿ったTest Caseの結果の作成と更新について記載します。

最後に

今回の事前準備によって、アプリケーションからAzure DevOpsのTest Plansの情報を取得・更新ができるということがわかりました。
APIを使うことでアプリケーションから様々なことができるようになりますので、皆様もぜひ一度試してみてください。

以上です。皆様も素敵な自動化ライフを！

＼明日の記事もお楽しみに／

執筆者プロフィール：木村直樹
製造業のSE、フリーランス、大手製造業のグループ会社をへて、2022年にSHIFTに入社。様々なソフトウェア開発を経験し、PMや案件管理者として働きながら、エンジニアとしてもまだまだ勉強中。趣味はDIYやプラモデル作成など。

お問合せはお気軽に
https://service.shiftinc.jp/contact/

SHIFTについて（コーポレートサイト）
https://www.shiftinc.jp/

SHIFTのサービスについて（サービスサイト）
https://service.shiftinc.jp/

SHIFTの導入事例
https://service.shiftinc.jp/case/

お役立ち資料はこちら
https://service.shiftinc.jp/resources/

SHIFTの採用情報はこちら　
https://recruit.shiftinc.jp/career/

最後まで読んでくださり、ありがとうございます！

御社サービスのご相談はお気軽に。

ソフトウェア品質のプロがお伺いします。