トップ > YAML×AIで脱Excel地獄！テストの本質に思考を集中させよう

YAML×AIで脱Excel地獄！テストの本質に思考を集中させよう

Control Plane部の小森 (@littleforest12)です。

みなさん、システムテストのシナリオやテストケース、どのように作成していますか？

ここ数ヶ月の間、筆者がアーキテクトとして参画したプロジェクト*1では、中盤以降にシステムテストの準備も主導しました。 このプロジェクトは、複数チームが協力して開発するものであったため、システムテストでもアーキテクトによる横断的視点での確認が必要だったためです。

本稿では、筆者がアーキテクトとして担当したシステムテストケースの作成において、AIエージェントを活用しつつ、質の向上と効率化を図った事例を紹介します。 読者の皆さんの開発現場での参考にしていただければ、幸いです。

システムテストは気が重い

システムテストというと、開発エンジニアとしてはモチベーションが上がりにくい部分かもしれません。 私もその重要性を重々承知しているものの、いつも気が重くなります。

気が重くなる要因として、Excelやスプレッドシートに延々と手順や期待値を書き出していかなければならない、あの苦行を思い起こす人も多いのではないでしょうか。 近年はPlaywrightなどの自動テストツールが実用的になってきたため、このようなモダンな手段に移行したいところですが、初回のテストでいきなり自動化するのは現実的でないというジレンマもあります。 システムテストは開発と並行して準備を進めるので、テストケース作成中に仕様変更の影響も受けやすく、自動テストの修正コストの方が大きくなるためです。

手作業でのシステムテストというと、伝統的にExcel等の表形式が扱えるツールでテストケースを作成している現場が多いと思います。 筆者のこれまでの経験でもそうでしたし、キャディでもGoogleスプレッドシートにテストケースを書いていました。

今回筆者らは、試験的にテキストファイル (YAML) 形式でテストケースを記述する方法を導入しました。 本稿では、その経緯とAIとの親和性を含む導入後の気づきをご紹介します。

これまでのテストケースの作り方

なぜスプレッドシートを使うのか？

冒頭にも書いたように、テストケースの管理スプレッドシート (Excel) を利用する開発現場は多いと思います。 あらためてその理由を言語化すると、以下のようなものになるでしょう。

  • 汎用性: 多くのメンバーが使い慣れているツールで、導入しやすい
  • 項目の追加しやすさ: 列を追加するだけで新しい管理項目を増やせる
  • 一覧性: 多数のテストケースを横断的に確認できる

多くの場合、「テスト実施日」「テスト実施者」「テスト結果(OK/NG)」などを記入する列も設けて、テスト結果の記録する手段としても使います。 もともと表計算ソフトなので、OK/NG項目数などの実施結果を集計するのにも使えます。

スプレッドシートのデメリット

これも皆さんが感じていることだと思いますが、デメリットも多いです。

1つ目は、セル内に長い文章を書きにくいことです。 テストの前提条件や手順を詳細に記述しようとすると、読みにくくなってしまいます。 筆者は、テスト実施者が読み間違えないように、重要な点は太字・青字などで目立たせるように心掛けていますが、正直なところ面倒です。

2つ目は、メンテナンスのしにくさです。 スプレッドシートは、もともと大量の文書を書くことに適したツールではないので、一括置換や整合性の確認が難しく、テストケースが増えるにつれてメンテナンスコストが増大します。

3つ目は、バージョン管理システムとの相性の悪さです。 Excelであれば、無理やりリポジトリ管理できますが、差分確認などはできません。

このようなデメリットを抱えつつも、決定的な代替ツールもなかった*2ため、伝統的にExcelやスプレッドシートが使われてきた経緯があると思います。

テストケースをYAMLに書くアイデア

今回、再びシステムテストに取り組むにあたり、テストケースをテキストファイル（YAML形式）で管理するアプローチを試みました。 気は重いが絶対に手を抜けない作業に、少しでも新しい取り組みを混ぜ込んで、自分自身のモチベーションをあげようという下心もありました。

いうまでもなく、テストケースをテキストファイルで記述すれば、前述のデメリットは解消されます。 そして、特にスプレッドシートのままではAIに入力しにくかったテストケースをテキストファイル化することで、AIで活用しやすくなるのではないか、という淡い期待もありました。

一方、テキスト化することで、表形式で閲覧できるメリットが失われてしまいます。

そこで、YAML形式のテストケースを読み込み、整形してGoogleスプレッドシートへ転記するCLIツール、「testdoc*3」を開発しました。

たとえば、1つのテストケースを以下のようにYAML形式で記述します*4。

testcases:
  - id: DAC-SEA-1-01
    category:
      - キーワード検索+表示切替(ユーザー01)
    title: サムネイル表示(32件)
    priority: high
    precondition:
      - "*B*ユーザー01*B*でログインしていること"
    steps:
      - 画面左上のハンバーガーメニューから「図面」を開く
      - 画面右上の表示件数を*B*32*B*件にする
      - 画面上部のソート順を「↑(昇順)」「図番」に設定する
      - 画面上部の「キーワード」欄に「*B*`AUZ-0`*B*」を入力し、検索ボタンを押す
    expected:
      - "別表([](sheet://○○○○#ユーザー-図面))を参照し、○○○○○○○○○○○○○○○○"
    notes:
      page: P-DW-DRA-001
      user: ユーザー01
      usecase: UC-D-2-2-1

このようなYAMLファイルをtestdocで処理すると、Google Sheets API をコールして、指定したGoogleスプレッドシートにレンダリングしてくれます。 レンダリングイメージは以下のようなになります。

Googleスプレッドシートへレンダリングしたテストケースのイメージ

このようなツールは技術的なハードルは低いのですが、作ること自体が面倒でした。 しかし、Claude Codeの登場で、こういったツールを低コストに開発できると考えたのです。 実際、開発はテスト設計をする傍らでClaude Codeを活用することで、自分では1行もコードを書くことなく実現できました。 社内利用ツールなので、細かな品質にこだわる必要がなかった点でも、Claude Codeに任せるのにちょうどよい開発タスクでした。

全体の利用イメージは以下のような感じにになります。

testdocの利用イメージ

testdocで実現したこと

testdocは自分でテストケースを作成しながら、欲しい機能を付け足していきました。 ここでは、いくつかの機能を紹介します。

テンプレートシートの利用

スプレッドシートへの転記は、あらかじめ用意されたテンプレートシートをコピーして、そこに上書きする方式としました。 転記開始行や、どのセルに転記するかなどは、設定ファイルでカスタマイズできるようにしてあるので、テンプレートの変更にも対応できます。

これにより、もともと社内で使われていた書式と同等の成果物を出力できます。 試験的な試みであったため、やってみてうまく行かなければ、旧来のやり方に戻すつもりでした。 そのため、成果物が旧来と同じものになる点は重要です。

簡易マークダウン記法

テストケースの説明文に簡易マークダウン形式を使えるようにしました。 これにより、スプレッドシートのセルでは難しかった、構造化された長い文章を自然に記述できるようになりました。

  • 太文字(**〜**)、青字(*B*〜*B*)、赤字(*R*〜*R*)などの色つき文字 *5
  • インラインコード(等幅フォント) (`〜`)
  • 箇条書き、番号付きリスト
  • ハイパーリンク ([タイトル](URL))

ハイパーリンク機能

特にハイパーリンクは、通常のURLの他に、YAMLファイル内でテストケース同士や関連シートへの参照をハイパーリンクとして記述できるようにしました。 これにより、テストケース間の依存関係や参照関係を明示的に記述できます。

  • [](sheet://<シート名>) で、他のシートへのハイパーリンク
  • [](ref://<テストケースID>) で、他のテストケースへのハイパーリンク

背景色の色分け機能

シナリオやカテゴリ単位など、意味のある塊で背景色を白/薄いグレーなど交互に変えて、視覚的に識別しやすくすることがあります。 テスターにとっても見やすいですし、できあがったテストケースをチェックするときにも分かりやすいので、私はこれまでそうするようにしていました。

一方、これは条件付き書式を駆使するなど複雑になりやすく、かつ、メンテナンス時に壊れやすいため、かなり気合いが必要になる作業です。 本ツールでは、これにも対応し、カテゴリ毎に背景色を自動的に切り替えるようにしています。

スプレッドシートの「メモ」への転記

ExcelやGoogleスプレッドシートには、マウスカーソルをセル上に移動したときにホバー表示される「メモ」機能があります。 手順や確認方法に関するちょっとした補足を、メモとして転記する機能も作成しました。 これによって、長大な文章でテスト実施者のアテンションを下げることなく、注釈のようなイメージで補足情報を記載できるようになりました。

YAML による再利用

アンカーやエイリアスといったYAMLの標準機能を利用して、テストケースの一部を別のファイルから参照・再利用することが可能になりました。 共通のテスト前提条件やセットアップ手順を一箇所にまとめて管理できます。

どんなプロンプトで作ったか

私自身、Claude Codeにそこまで慣れているわけではないため、普段自分がツールを作るときの手順そのままで、細かくステップを割って実現していきました。 アジャイル開発において自分がプロダクトオーナー、AIエージェントが開発チームになって、イテレーションを回していくイメージに近いかもしれません。 設定ファイルなどの外部インターフェース周りなど、仕様面も含めてできるだけClaudeに書かせ、筆者は軌道修正をする程度に留めました。

具体的なプロンプトは記録しなかったため紹介できませんが、大まかな作業の流れを紹介します。

STEP.1 : プロトタイプ作成

私自身もSheets APIを利用したことはないので、YAMLをパースしてSheet APIへ転記するという核心的な部分が実現できるかを、まず検証しました。 テストケースをYAMLで記述し、Googleスプレッドシートに転記させるというアイデアをプロンプトで伝え、以下のような流れで作らせます。

  1. テストケースをYAMLファイルで記述したテストケースのサンプルを作らせる
  2. YAMLファイルをパースしてGoogleスプレッドシートに転記する処理を作らせる → Claude Codeは自分でSheets APIの仕様を参照して作ってくれる

なお、Sheets APIを利用するための認証はADC *6を利用しました。 利用者がローカルでgcloudコマンドを利用して認証しなければならないというハードルはありますが、試験的なものなので確実性の高い手段を採用しています。

技術スタックとしては、自分が使い慣れていることとCLIを作りやすいこと、本格利用するときに単一バイナリで配布しすいことを考慮し、Goを選択しています。

STEP.2 : 簡易マークダウンのレンダリング処理実装

スプレッドシートへの書き込みができることが確認できたので、簡易マークダウンの解釈とセル内へのレンダリング処理を追加します。 マークダウン自体は一般的な仕様なので、細かなところまで伝えなくても実装をしてくれました。

この段階で対応していたのは、太字とインラインコード、ハイパーリンク程度だったと思います。 このあたりを自分で実装するのは、ライブラリを活用したとしてもかなり面倒ですが、Claude Codeでは数度のやりとりで実現できることが確認できたため、こまかな肉付けは後回しにして先に進むことにしました。

STEP.3 : テンプレートの利用を実現

テスト仕様書として社内で違和感なく使ってもらうため、既存のフォーマットに合わせた出力ができることは重要な要件でした。 そこで、テンプレートとなるシートをコピーして、そこにテストケースをレンダリングすることに取り組みました。 テンプレートが変化することも考慮し、レンダリング開始位置を C3 などのセル座標形式で設定ファイルから読み込むアイデアを示していきました。

STEP.4 : ドッグフーディングしながらの継続的改善

ここまで来ると、ベースはほぼできた状況になるので、テストケースを書きながら、ほしいと思った機能を付け足しつつ使っていく感じになります。 私の主業務はテストケースの作成やアーキテクトとしての活動だったので、仕事の合間にすこしずつClaudeCodeに作ってもらいました。 そのため、testdocのソースコードは一切確認しませんでした*7。

使ってみて、どうだったか

テストケースをYAMLで記述するようにしたことで、もともと期待していた効果だけでなく、予想外の効果も得られました。

Pull request ベースのレビュー

まず想定内の効果ですが、テストケースがテキストファイル化され、GitHubでの管理に移行したことで、Pull requestとして相互レビューできるようになりました。 差分が明確になるため、どのテストケースがどのように変更されたかを追跡しやすくなります。

この時点で、Claude CodeをはじめAIによるレビューも可能になります。 総じて、テストケースの品質向上にもつながりました。

GitHub Actionsによるスプレッドシートへの自動転記

mainブランチへのマージと同時にツールを実行し、スプレッドシートへの自動転記も実現できました。 testdocはGoで作成したCLIツールなので、ローカルからも実行可能ですが、自動実行化することで常に最新のテストケースが展開されるのは、安心感があります。

ただ、PRレビューの段階でもスプレッドシート上で展開させたかったため、PR毎に新しいファイルに転記し、そのURLをPRに自動記載などできれば、さらに便利だったと思います。 今回は時間の関係で、そこまではできませんでした。

きちんと書く意識の向上

次に、想定外の効果です。 狭いセル内に長文を書くというのは、自分が認識していた以上の心理的制約になっていたことに気づきました。

テキストファイルで書くことで、自然と読み手を意識した記述をするようになりました。 これまでスプレッドシートでは省略しがちだった全体説明や、テストケースの意図などを、丁寧に記述するようになったことは予想外の効果でした。 また、全体説明についてはテストケースを書いた後、Claude Codeにサマライズさせることで効率的に記述することもできました。

テストの目的をきちんと記述

今回のテスト実施は短期的に参画いただいた業務委託の方々にお願いをしましたが、「わかりやすく、テストしやすかった」という嬉しい感想をいただきました。

テストケース作成中における閲覧性の課題

一方で、課題もあります。

正直なところ、YAMLファイルを直接編集している最中はスプレッドシートと比べて閲覧性が劣ります。 特にテストケースが多い場合は、やはり全体像を把握しにくいと感じました。

これまで、私は1つのシートに数十のテストケースを書いてしまうことが多かったのですが、1ファイル=1シートとなったことで、必然とファイルを分けるようになりました。 しかし、1ファイル10個程度のテストケースであっても閲覧性は下がります。 エディタのアウトライン設定の工夫で、多少は全体構造が把握できますが、ローカルでスプレッドシートへの転記を何度か行い、書きながら全体を確認する作業が必要になりました。 これは現時点での課題として認識しています。

まとめ：テストの「本質」に思考を集中させるために

システムテストの準備において、私たちが戦うべき相手は「複雑な仕様」であって、「セルの書式」ではありません。

今回、テストケースをYAML管理に移行し、Claude Codeの活用でツールを自作したことで、単なる効率化以上のメリットが得られました。 「なにをテストすべきか」「どのようにテストすべきか」「テスターにとって理解しやすいテストケースをどう書くか」という本質に思考を集中できるようになったことが、大きな価値だったと思います。

そして最大のメリットは、密かな期待通り、AIエージェントの恩恵を受けやすくなったことです。 初期アイデアの段階ではここまで予想できなかったのですが、Claude Codeによって、実用的なレベルでシステムテストケースの自動生成が可能だということがわかりました。 これは、筆者の試みに賛同してくれた同僚が実現してくれたので、後日別エントリにて詳しく紹介してもらいます。 ご期待ください！

キャディでは、ClaudeCodeをはじめとするAIエージェントの活用にも積極的に取り組んでいます。 ご興味ある方は、ぜひ採用サイトもご覧ください！

recruit.caddi.tech

*1:昨年末に寄稿した『腹をくくり、最後まで伴走しきってこそアーキテクト。不確実性を乗り越える「共創」のアプローチ』で紹介したプロジェクトです。

*2:TestLinkなどのテスト管理ツールがありましたが、筆者は使ったことがありません。一般的にもそこまで普及した印象はなかったと思います。

*3:testdocは試験的に作成したツールであるため、今のところ非公開です

*4:一部マスクしています。ご了承ください

*5:色つき文字の表現はマークダウンには無い独自仕様です

*6:Application Default Credentials

*7:確認する余裕がなかったというのが、正直なところかもしれません