はじめに
以前、Markdownで書いたテスト仕様書をExcelに変換するツールを作りました。
MarkdownからExcelのテスト仕様書を作成するツールを作りました
当時から、テスト仕様書をExcelで直接管理するのはGitと相性が悪いので、
原本はMarkdownにしておきたいと思っていました。
ただ、実際の現場では、
- レビュー時にはExcelで見たい
- テスト結果をExcelへ記録したい
- すでに決められたExcelの様式がある
- 最終成果物としてExcelを求められる
といった事情もあるので、「もうExcelをやめよう！」というのもなかなか難しいです。
それなら、
原本はMarkdownで管理して、必要なときだけExcelを生成する
という形がちょうどいいのでは、
ということでツールを作ったのが前回でした。
それから大分放置してしまっていたのですが、
最近になってちゃんと使える状態にしたくなり、構成を含めて大きく作り直しました。
作り直したものはこちらです。
GitHub - kazuki0529/md-test-spec2excel
AI時代になってMarkdown管理の意味が増した気がする
前回の記事を書いたのは2022年でした。
当時、Markdownで管理したかった主な理由は、Gitで差分を確認できることでした。
もちろん今でもそこは大きなメリットなのですが、最近は生成AIとの相性も重要になってきたように思います。
例えば、画面仕様やAPI仕様をAIに渡して、
この仕様をもとに、正常系・異常系・境界値の
テストケースを作成してください。
とお願いすれば、テストケースのたたき台を作ってもらえます。
ただ、出力先がExcelになると少し扱いにくいです。
AIにExcelファイルを直接編集させる方法もありますが、
- 何が変更されたのか確認しづらい
- 既存の書式が壊れていないか気になる
- プロンプトやツールによって出力が安定しない
- 人間がレビューする前にExcelファイルができてしまう
といった問題があります。
一方、MarkdownであればAIにも生成させやすく、人間もそのまま読めます。
Gitで差分を確認して、問題なければマージし、最後にExcelへ変換できます。
つまり、
AIが扱いやすい原本はMarkdownにして、
人間が使いやすい成果物としてExcelを生成する
という分け方ができるのではないかと思いました。
AIが作ったテストケースが正しいとは限らないので、レビューなしでそのままExcelにするのは怖いですが、Markdownの差分として確認できるのであれば、比較的運用に組み込みやすそうです。
ツールの概要
このツールは、Markdown形式で記載したテスト仕様書を、JXls形式のExcelテンプレートへ埋め込むものです。
Markdownファイルごとに別々のExcelを作るのではなく、複数のMarkdownファイルをまとめて1つのExcelに出力できます。
前回と同じく、Excelファイルをプログラム側で一から組み立てるのではなく、あらかじめ用意したExcelテンプレートへ値を埋め込みます。
そのため、既存のExcel様式やセルの書式、条件付き書式などを残したまま使えます。
Markdownの書き方
基本的には、見出しとリストを使ってテストケースを記述します。
# ログイン機能テスト
## 正常系
### パスワード認証
#### 正しいIDとパスワードでログイン
1. ブラウザでログイン画面を開く
1. 正しいIDとパスワードを入力する
1. ログインボタンを押す
- [ ] ホーム画面が表示される
- [ ] ユーザー名がヘッダーに表示される
```text
事前条件: テストユーザーが登録済みであること
```
Markdownの各要素は、次のようにテスト仕様書へ変換されます。
| Markdown | Excel上の項目 |
|---|---|
# |
テスト仕様書のタイトル |
## |
大項目 |
### |
中項目 |
#### |
小項目 |
| 順序付きリスト | 確認手順 |
| チェックリスト | 想定動作 |
| コードブロック | 備考 |
番号付きリストをすべて 1. で書いても、出力時に連番へ変換します。
Markdownの差分で番号の振り直しが大量に発生するのが嫌だったので、この形にしています。
front matterに対応した
今回、Markdownの先頭にYAML front matterを書けるようにしました。
---
spec_var: loginSpec
feature: ログイン
viewpoint: 正常系
---
# ログイン機能テスト
spec_var は、Excelテンプレートから参照するときの変数名です。
それ以外の値は、ユーザー定義変数としてテンプレートから参照できます。
${loginSpec.vars['feature']}
${loginSpec.vars['viewpoint']}
テスト仕様書によって表紙へ出したい項目が違ったり、
プロジェクト固有の情報を持たせたかったりするので、
固定のデータモデルへすべて追加するのではなく、
ある程度自由に変数を増やせるようにしました。
テストケース単位のカスタム項目にも対応した
テストケースごとに優先度やテスターなどを設定したい場合は、Markdown内に3列のテーブルを書きます。
| 論理名 | 変数名 | 値 |
|---|---|---|
| 優先度 | priority | High |
| テスター | tester_id | user123 |
Excelテンプレートからは、次のように参照できます。
${case.customFields['priority']}
${case.customFields['tester_id']}
どんな項目が必要になるかをツール側ですべて予測するのは難しいので、
ここも利用側で拡張できるようにしました。
AIと組み合わせる場合
例えば、AIへ次のように依頼します。
以下の画面仕様からテストケースを作成してください。
正常系、異常系、境界値を含めてください。
出力は次の形式にしてください。
# 機能名
## 大項目
### 中項目
#### 小項目
1. 確認手順
- [ ] 想定動作
生成されたMarkdownをそのまま採用するのではなく、
Pull Requestとしてレビューします。
画面仕様
↓
AIでテストケースのたたき台を生成
↓
Markdownの差分を人間がレビュー
↓
Gitへマージ
↓
Excelを生成
Excelを直接生成させるよりも、途中にレビュー可能なMarkdownを挟めるところが重要だと思っています。
また、既存のテストケースもMarkdownなので、
- この機能追加によって必要になるテストケースを追加する
- 表現が曖昧なテストケースを洗い出す
- 正常系しかない機能から異常系を検討する
- 仕様変更の差分から影響を受けるケースを探す
といった用途でも、AIに渡しやすくなります。
ただし、AIが作ったテストケースの妥当性を保証するものではありません。
最終的な確認は人間が行う前提です。
最後に
当初は、Excelのテスト仕様書をGitで管理しやすくするために作ったツールでした。
それから生成AIが身近になり、Markdownで原本を持つことには、単なる差分管理以上の意味が出てきたように感じています。
Excelには、レイアウトの自由度や、レビュー・テスト実施時の使いやすさがあります。
Markdownには、差分管理、自動処理、AIからの読み書きのしやすさがあります。
どちらか一方に統一するのではなく、
Markdownを原本にして、Excelを成果物にする
という分担が、今のところ自分には一番しっくりきています。
まだ改善したいところはありますが、以前よりは大分使いやすい状態になったので、改めて公開してみました。