Spekta

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

はじめに

Spekta はテストコードから仕様書を生成するツールチェインです。テストファイルに [spekta:*] コメントを書くだけで、人間が読める仕様書が自動生成されます。このページでは、最初のセットアップからドキュメント生成までの手順を説明します。

プロジェクトの初期化

spekta init コマンドで .spekta.yml（設定ファイル）と .spekta/（出力ディレクトリ）が生成されます。

Tip
生成された .spekta.yml はコメントアウトされた状態なので、プロジェクトに合わせて編集してください。

spekta init の実行

  1. プロジェクトディレクトリで spekta init を実行する
  2. .spekta.yml と .spekta/ ディレクトリが生成される
  3. 設定ファイルの内容はコメントアウトされている

設定ファイルの編集

.spekta.yml を編集して、テストファイルの場所と使用する Exporter を設定します。

target_dir にテストファイルが置かれたディレクトリを、include に対象ファイルの拡張子パターンを、exporter に使用する Exporter プラグインを指定します。

version: 1
target_dir: test/
include:
  - ".test.ts"
exporter:
  "@ktmage/spekta-exporter-web":
    name: "My Project"

最小構成の設定例

  1. .spekta.yml に target_dir, include, exporter を設定する
  2. 設定ファイルが正しく読み込まれる

テストファイルへのアノテーション

テストファイルにコメントで [spekta:*] アノテーションを追加します。これらのコメントが仕様書の構造になります。

最低限、[spekta:page]（ページ定義）と [spekta:section]（セクション定義）を書けば仕様書が生成されます。[spekta:summary] で概要を、[spekta:steps] で操作手順を追加すると、より充実した仕様書になります。

// [spekta:page] hello
// [spekta:summary] はじめての仕様書です。
// [spekta:section] Hello World
describe("Hello World", () => {
  // [spekta:section] 挨拶が表示される
  it("挨拶が表示される", () => {});
});

アノテーションを書いてドキュメントを生成する

  1. .spekta.yml を作成する
  2. テストファイルに [spekta:page], [spekta:section], [spekta:summary] を書く
  3. spekta render を実行する
  4. .spekta/web/ に HTML 仕様書が生成される