Spekta

テストコードから仕様書を生成するツールチェイン

コンセプト

Spekta の設計思想と、テストコードから仕様書が生成されるまでの仕組みを説明します。

テストファイルが仕様書である

テストは実行可能で、正しいかどうか検証可能です。Spekta はテストファイルに書かれた [spekta:*] コメントを仕様書の構造として読み取ります。

Note
コメントの記法は言語に依存します。TypeScript では //、Ruby や Python では # を使います。

テストコード自体は読みませんが、コメントで記述された仕様は常にテストと同じファイルに存在するため、乖離が起きにくくなっています。

  • TypeScript: // [spekta:*]
  • Ruby: # [spekta:*]
  • Python: # [spekta:*]

コメントから仕様書の構造を読み取る

  1. テストファイルに [spekta:page], [spekta:summary], [spekta:section] を書く
  2. Parser がコメントから IR（中間表現）を生成する
  3. ページ、概要、セクションが構造化されて出力される

Annotator → Parser → Exporter

Spekta は3つのステージで仕様書を生成します。

Annotator はテスティングフレームワークの DSL を読んで [spekta:*] コメントを自動補完します（省略可能）。Parser はコメントだけを読んで IR に変換します。Exporter は IR からドキュメント（HTML, Markdown 等）を出力します。

テストファイル (.test.ts, _spec.rb)
  ↓ Annotator（省略可能）
[spekta:*] コメント付きテストファイル
  ↓ Parser
IR（中間表現 / JSON）
  ↓ Exporter
HTML / Markdown / PDF

Parser はテストコードの構文を理解しない

なぜ？
Parser がフレームワーク固有の構文に依存しないことで、どの言語・フレームワークのテストでも同じ Parser が使えます。
  1. describe や it などのテストコードが含まれるファイルを渡す
  2. Parser は [spekta:*] コメントだけを読み、他は無視する

複数ファイルから1つのページを生成する（マージ）

なぜ？
大きな機能を複数のテストファイルに分けて書いても、同じ [spekta:page] を指定すれば1つの仕様書ページにまとめられます。
  1. 2つのファイルに同じ [spekta:page] を書く
  2. 同じページ名からは同じ ID が生成され、マージの対象になる