こんにちは。ダイの大冒険エンジョイ勢のbun913と申します。
以前、Zephyr というテスト管理ツールの CLI を作った記事を書きました。
今回はその CLI に TUI（Terminal User Interface）を追加し、テスト実行の記録をターミナル上で快適に行えるようにしたので、その紹介をします。
いきなりデモ
以下のようなかたちで、TUIツールを zephyr play コマンドで開け、その中でテスト結果の記録などを行えます。
なお、この記事を読んで直接嬉しいのは Zephyr を利用している方になります。一方で、今回単に TUI ツールを作ったのではなく、実は AI との協働を見越した工夫をしております。CLI ツールに TUI を組み込む時の一つの工夫を見ていただけると、Zephyr を利用されていない方にも参考になるかもしれません。
機能追加の背景・感じていたつらさ
Zephyr にはブラウザ上でテストを実行・記録するための Test Player という機能があります。基本的な機能は揃っているのですが、業務で使っていく中でいくつか気になる点がありました。
まず、わかりやすいところで言えば「フォルダの構造などが把握しにくい」ことです。
Test Player ではテストケースがフォルダ単位でグループ表示されますが、フォルダパスがフラットに表示されます。
例えば /01_ユーザー認証/ログイン/ソーシャルログイン/Google のような深い階層があると、パスが途中で切れてしまい、どのフォルダ配下のテストケースなのか分からなくなることがあります。
以前の記事で紹介した Chrome 拡張を入れればフォルダパスを表示できますが、拡張なしだとフォルダのネスト構造が直感的に把握できません。
それ以外にも細かい以下のようなつらさを感じていました。
- Test Player ページで表示されるテストケースやフォルダの順番が本来テストケース画面で登録していたものと異なる時がある
- テストケース自体を修正したい際に、手数がかかる
- テストケース詳細画面に移動する
- 詳細画面でテストケースを修正
- Player画面で表示される「ケースがアップデートされました。ここを押して更新」といったメッセージをクリックする必要がある
- テストサイクルからテストケースを除外したい場合の手数がとても多い
- それは上記Chrome拡張に Remove ボタンをつけて、気軽にできるようにしております
TUI で解決したこと
これらの課題を解消するために、CLI に zephyr play という TUI コマンドを追加しました。
ツリー構造でフォルダを表示
テストケースをフォルダの階層構造に沿ってツリー表示します。各フォルダにはテストケース数も表示されるので、全体の構造を一目で把握できます。
以下の点の使いやすさを意識しています。
- 自分のため
- j,k といったキーバインドで操作ができる
- もちろん ↓ などで操作できますが、手に馴染んでいるキーバインドをつけています
- すべてのユーザーのため
- フォルダがネストされたツリー構造で表示される
- 後にもありますが p: Pass, f: Fail といったワンキーでテストケース全体や個別のステップの結果を登録できる
- また、文字列だけなら Enter を押すことですぐに登録できるようにしています
- カスタムフィールドなどの値も表示しています（編集には対応していません）
Snapshot ワークフロー
TUI はローカルの JSON ファイル（snapshot）を元に動作します。
# テストサイクルを対話的に選択してsnapshotを作成
zephyr play init
# または直接テストサイクルを指定
zephyr snapshot sync KAN-R1 -o KAN-R1.json
play init を実行すると、プロジェクト内のテストサイクル一覧が表示され、選択したサイクルのテストケース・ステップ・フォルダ情報を fetch して JSON ファイルに出力します。
一部ですが、以下のような形でJSONファイルを出力しています。
{
"version": "1.0",
"exportedAt": "2026-02-28T05:51:22.646Z",
"projectKey": "KAN",
"testCycleKey": "KAN-R1",
"testCycleName": "v1.0 リグレッションテスト",
"testCases": [
{
"key": "KAN-T1",
"name": "有効なユーザー名とパスワードでログインできる",
"objective": "正常なログインフローの検証",
"precondition": "ログインページが表示されている",
"estimatedTime": null,
"labels": [],
"component": null,
"customFields": {
"custom_lines": "優先度高・スモークテスト対象"
},
"folderId": 34381002,
"folderPath": "/01_ユーザー認証/ログイン",
"createdAt": "2026-02-28T02:38:50Z",
"originalIndex": 0,
"execution": {
"id": 2201343190,
"status": "Pass",
"comment": null,
"executedBy": "712020:d5f9e47a-a3fb-4a98-9305-79d7adcfc817",
"actualEndDate": "2026-02-28T03:15:03Z",
"executionTime": null
},
"steps": [
{
"index": 0,
"description": "ユーザー名を入力する",
"testData": "",
"expectedResult": "ユーザー名が入力欄に表示される",
"result": {
"status": "Not Executed",
"actualResult": ""
}
},
{
"index": 1,
"description": "パスワードを入力する",
"testData": "",
"expectedResult": "パスワードが入力欄にマスク表示される",
"result": {
"status": "Not Executed",
"actualResult": ""
}
},
{
"index": 2,
"description": "ログインボタンをクリックする",
"testData": "",
"expectedResult": "ダッシュボードに遷移する",
"result": {
"status": "Not Executed",
"actualResult": ""
}
}
],
"excluded": false
}
]
}
# TUIを起動
zephyr play KAN-R1.json
この snapshot ファイルがテスト実行中のソースになります。TUI で記録した結果は snapshot に保存され、Zephyr に同期されます。
JSON をソースにしているため、sort コマンドなどもサクサク動きますし、都度データを取り直す必要がありません。というのも、私の使い方の場合、テスト実行時に大幅にテストケースの入れ替えなどを秒単位でしません。R を押すことで全てのテストケースやフォルダなどを取り直すことができるため、情報の同期はそれで十分と判断しました。
TUI の操作
TUI ではキーボード操作でテスト実行を記録できます。
テストケース・ステップの結果を記録
テストケースを選択した状態で p を押すと Pass、f を押すと Fail として、全ステップの結果を一括で更新できます。ステップを個別に選択して p/f を押せば、ステップごとの結果を個別に記録することも可能です。
結果の記録時にはコメントを入力でき、テスト実行中に気づいた点をその場でメモとして残せます。
テストケースの詳細画面を開く
テストケースを選択して e を押すと、ブラウザでそのテストケースの詳細画面を開きます。テストケースの内容を編集したい場合や、テストスクリプトやトレーサビリティを確認したい場合に便利です。
ちなみに「テストケースを編集したい」ので edit の e です。
ブラウザの Test Player を開く
テストケースを選択して o を押すと、ブラウザで Test Player を開きます。結果の画像やファイルを添付したい場合など、ブラウザ側で操作したいケースに使えます。
本来は該当のテストケースを選択した状態で Test Player を開きたかったのですが、Test Player のページは内部的なテストケース ID を使用しており、公開 API からはその ID を取得できませんでした。
そのため、o を押すとテストケース ID をクリップボードにコピーした上で Test Player のページを開くようにしています。Test Player の検索ボックスにペーストすれば、すぐに該当のテストケースを見つけられます。
また、以前作成した Chrome 拡張と組み合わせると、Test Player 上からテストサイクルのテストケースを除外することもできます。TUI で結果を記録しつつ、不要になったテストケースはブラウザ側でサイクルから外す、といった運用も可能です。
データの再取得
r で選択中のテストケースだけを Zephyr から個別に再取得できます。毎回全件取得すると時間がかかるため、特定のテストケースだけを素早く最新化したい場合に便利です。
R ではテストサイクル全体を再取得します。こちらは時間がかかりますが、テストサイクルに追加・削除されたテストケースも含めて完全に同期できます。
AI活用 / AIに操作をさせる工夫
先ほど紹介した TUI の操作は、すべて個別の CLI コマンドでも同じことができます。
# テストケース全体の結果を記録
zephyr snapshot record KAN-R1.json KAN-T1 --status Pass
# コメント付きで記録
zephyr snapshot record KAN-R1.json KAN-T5 --status Fail --comment "ボタンが表示されない"
# ステップ単位で記録
zephyr snapshot record KAN-R1.json KAN-T1 --step 0 --status Pass --actual-result "ページが表示された"
人間は TUI で操作し、AI エージェントはこれらの CLI コマンドで操作する。どちらも同じ snapshot ファイルを通じて Zephyr とやり取りするため、同じワークフローの上で動けます。
（もちろん JSON を介さずに、直接 API で情報を更新するコマンドも用意しています）
さらに、以下のように Agent Skills を準備しておくことで、AI との対話で Zephyr を操作させることが可能です。リポジトリにもサンプルとして配置しています。
私はまだその段階に至っておりませんが、今後もし「AI に事前に用意したテストケースを自動で実行してもらう」といったことが起きた時に、このスキルを使えばその証跡も Zephyr に残させることが可能なのでは？と考えています。
まとめ
- Zephyr の Test Player でのテスト実行にはフォルダ構造の把握しにくさやテストケース名の途切れなどの課題があった
- CLI に TUI（
zephyr play）を追加し、ツリー表示やキーボード操作で快適にテスト実行を記録できるようにした - 全ての操作を CLI コマンドとしても提供しているため、AI エージェントとの連携も可能
- またテスト実行したJSONファイルに実行結果なども残るため、もしAI活用のためにGit管理したい。という場合も使い道があるかもしれません
一方で、私の把握する限り Zephyr の公開APIには、画像などの添付ファイルを作成するエンドポイントがないため、その際はブラウザを開く必要があります。もし、今後可能になればそのような問題にも対応したいです。（もしくはChrome拡張と連携させるのもありかもしれません）
以上、最後まで読んでいただき、ありがとうございました。
Discussion