PHP x Markdown or asciidocでテスト仕様書を作って幸せになりたい

Excelテスト仕様書がつらい

重い。管理が面倒。A1セルにフォーカス当てる？全ブック？なんで途中から連番が手入力なの。。。

Markdownじゃ対応しきれない

設計書はこれでいいんだけど。。。テスト結果の集計ができない。。。

データと文書を分割しよう

Markdownで対応できないのはテスト結果というデータを持つから。
なら、これをjsonとかで別に持ってやればいい。

PHP x Markdown

PHPって別にhtmlに限らずテキスト形式ファイルに出力できる。
テスト項目&結果データを渡してPHPで記述してやればいい。

やってみた

単純に配列データを表にするだけ。
PHP以外はそのまま出力されるからMarkdownをそのまま書ける。

ディレクトリ構造

project
 |
 ├─build
 │  └─test.md
 │
 ├─resources
 │  ├─data
 │  │  └─data.json
 │  │
 │  └─template
 │     └─template.php
 │
 └─src
    └─compile.php

data.json

{
  "contents": [
    {
      "key": "key1",
      "value": "value1",
      "result":true
    },...
  ]
}

template.php

# Parkdown

## Markdown

### table
Percentage :
<?php
class ResultSum
{
    static $sum;

    static function summary($content){
        self::$sum += $content["result"] ? 1 : 0;
    }
}

array_walk($contents, "ResultSum::summary");
echo ResultSum::$sum . "/" . count($contents) . "\n";
?>

|index | key | value | result |
|:---|:---|:---| :---: |
<?php

foreach ($contents as $index => $content) {
    $result = $content["result"] ? "○" : "×";
    echo "|No." . ($index + 1) . "|" . $content["key"] . "|" . $content["value"] . "|" . $result . "|\n";
}

compile.php

<?php

/**
 * 出力先ディレクトリがなければ作る
 * @param $paths
 */
function make_dir($paths)
{
    if (count($paths) > 0) {
        $dir = implode("/", $paths);
        is_dir($dir) or mkdir($dir, 0777, true);
    }
}

/**
 * テンプレートにデータを渡してテキストファイルを作成する。
 * @param $target_resource
 * @param $output_name
 */
function output_file($target_resource, $output_name)
{
    ob_start();
    $contents = json_decode(file_get_contents($target_resource), true)["contents"];

    include("../resources/template/template.php");

    $full_file_name = "../build/" . $output_name;
    $paths = explode("/", $full_file_name);
    array_pop($paths);
    make_dir($paths);
    file_put_contents($full_file_name, ob_get_contents());

    ob_end_clean();
}

output_file("../resources/data/data.json", "test.md");

complie.phpを実行すればbuildディレクトリにtest.mdが出力される。

test.md

# Parkdown

## Markdown

### table
Percentage :
4/6

|index | key | value | result |
|:---|:---|:---| :---: |
|No.1|key1|value1|○|
|No.2|key2|value2|○|
|No.3|key3|value3|○|
|No.4|key4|value4|×|
|No.5|key5|value5|○|
|No.6|key6|value6|×|

ファイル監視すれば、変更を即時反映できる。
ソースコード

メリット

• テスト仕様書の体裁を統一できる。
• 体裁の修正がテンプレートファイル分で済む。
• phpブロックを畳めばMarkdownと同じくらいの可読性
• 別ファイルへのリンクが貼れる
• 学習コストが低い（PHPを本気でやるわけではないので）

課題

まだテスト項目・結果データを新規入力・更新するには、データファイルを直接編集しなければいけない状態。
typoraのように出力結果を編集することで元ファイルを更新できるようにしたい。