はじめに

以前、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を成果物にする

という分担が、今のところ自分には一番しっくりきています。
まだ改善したいところはありますが、以前よりは大分使いやすい状態になったので、改めて公開してみました。

GitHub - kazuki0529/md-test-spec2excel