Spekta

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

アノテーション一覧

テストファイルに書ける [spekta:*] コメントの一覧です。これらのコメントが仕様書の構造とコンテンツになります。

コメントは //（TypeScript）または #（Ruby/Python）で始めます。インデントの深さがセクションのネスト構造を決定します。

[spekta:page] — ページの定義

仕様書の1ページを定義します。値は英語のスラッグで、URL のパスに使われます。

1ファイルに1つが基本ですが、複数書くこともできます。同じページ名を複数ファイルに書くと、1ページにマージされます。

// [spekta:page] company-search

基本的な使い方

  1. // [spekta:page] my-feature と書く
  2. ページ名 my-feature のページが生成される

[spekta:section] — セクションの定義

仕様書のセクション（見出し）を定義します。テストの describe や context に対応します。

Tip
インデントの深さでネスト構造が決まります。テストコードのインデントと合わせると、コードの構造がそのまま仕様書の階層になります。
// [spekta:section] 親セクション
describe("親セクション", () => {
  // [spekta:section] 子セクション
  it("子セクション", () => {});
});

セクションの作成

  1. // [spekta:section] セクション名 と書く
  2. 見出しとしてセクションが生成される

インデントによるネスト

  1. インデントを深くして [spekta:section] を書くと、子セクションになる

[spekta:summary] — 概要

ページやセクションの概要テキストを設定します。仕様書の冒頭に表示されます。

// [spekta:page] my-feature
// [spekta:summary] ユーザーが企業を検索する機能です。

ページに概要を追加する

  1. [spekta:page] の後に [spekta:summary] を書く
  2. 概要テキストがページに表示される

[spekta:why] — 理由の説明

設計判断やルールの理由を説明します。仕様書ではコールアウト（強調ブロック）として表示されます。

「なぜこの仕様なのか」を読者に伝えるために使います。テストで「何を検証しているか」は見ればわかりますが、「なぜそうである必要があるか」はコメントがないと伝わりません。

セクションに理由を追加する

  1. セクション内に [spekta:why] を書く
  2. 理由がコールアウトとして表示される

[spekta:see] — 関連ページへの参照

関連するページへのリンクを作成します。値にはページ名を書きます。仕様書では「関連:」セクションにリンクとして表示されます。

ページ名で参照する

  1. [spekta:see] other-page と書く
  2. 参照先が SHA256 ID に変換される

[spekta:steps] と [spekta:step] — 操作手順

操作手順を番号付きリストで記述します。[spekta:steps] で開始し、[spekta:steps:end] で終了するブロック構文です。

Warning
[spekta:steps] と [spekta:steps:end] は必ずペアにしてください。ネストはできません。
// [spekta:steps]
// [spekta:step] ページを開く
// [spekta:step] フォームに入力する
// [spekta:step] 送信ボタンをクリックする
// [spekta:steps:end]

ステップブロックの書き方

  1. [spekta:steps] と [spekta:steps:end] で囲む
  2. 中に [spekta:step] で手順を書く

ステップ内に画像を差し込む

なぜ？
操作手順の途中にスクリーンショットを挟むことで、読者が手順を視覚的に追えるようになります。
  1. [spekta:steps] ブロック内で [spekta:image] を書く
  2. ステップの間に画像が配置される

[spekta:image] — 画像の埋め込み

スクリーンショットや図を仕様書に埋め込みます。値には画像ファイルのパスを書きます。

画像パスの指定

  1. [spekta:image] path/to/image.png と書く
  2. 画像が仕様書に埋め込まれる

[spekta:graph] — Mermaid ダイアグラム

Mermaid 記法のダイアグラムを仕様書に埋め込みます。[spekta:graph] の後にコメント行で Mermaid 記法を書くと、複数行がまとめて読み取られます。

Mermaid ダイアグラムの書き方

  1. [spekta:graph] に続けて Mermaid 記法をコメントで書く
  2. ダイアグラムが仕様書に表示される

[spekta:text] — テキスト

散文テキストを仕様書に追加します。セクション内に説明文や補足情報を書くために使います。

// [spekta:text] この機能はユーザー認証後に使用できます。

テキストの追加

  1. [spekta:text] にテキストを書く
  2. テキストが仕様書に表示される

[spekta:code] — コードブロック

コードブロックを仕様書に埋め込みます。[spekta:code] で開始し [spekta:code:end] で終了するブロック構文です。開始タグの後ろに言語名を指定できます。

Warning
[spekta:code] と [spekta:code:end] は必ずペアにしてください。ネストはできません。

コードブロックの書き方

  1. [spekta:code] 言語名 で開始し、[spekta:code:end] で閉じる
  2. 間のコメント行がコード本文になる
  3. 言語名とコード本文がそれぞれ格納される

言語名を省略する

言語名を省略するとシンタックスハイライトなしのコードブロックになります。

[spekta:callout] — 注意書き

注意書きやヒントを強調ブロックとして表示します。variant をテキストの前に指定します。

利用可能な variant は以下の3種類です。

// [spekta:callout] warning この操作は元に戻せません
// [spekta:callout] tip インデックスを追加するとパフォーマンスが改善します
// [spekta:callout] note この設定はオプションです
  • note — 補足情報や参考情報
  • warning — 注意が必要な情報
  • tip — 便利なヒントやコツ

variant を指定する

  1. [spekta:callout] variant テキスト と書く（variant は note/warning/tip）
  2. variant とテキストが分離して格納される

[spekta:list] と [spekta:item] — 箇条書きリスト

箇条書きリストを仕様書に埋め込みます。[spekta:list] で開始し [spekta:list:end] で終了するブロック構文です。

Warning
[spekta:list] と [spekta:list:end] は必ずペアにしてください。[spekta:item] はブロック内にのみ書けます。
// [spekta:list]
// [spekta:item] メール通知
// [spekta:item] Slack 通知
// [spekta:item] Webhook
// [spekta:list:end]

リストの書き方

  1. [spekta:list] と [spekta:list:end] で囲む
  2. 中に [spekta:item] で項目を書く
  3. 箇条書きとして表示される