excel-petter

テスト実施時に集めたエビデンス（スクリーンショット・SQL・DB 結果・ログ）を、 所定のディレクトリに置くだけで Excel ブックに自動で貼り付けるツールです。

仕様は docs/prd.md、リリース手順は docs/RELEASE.md を 参照してください。

インストール

npm install -g @szk302/excel-petter

一度きりの利用なら、インストールせずに実行することもできます。

npx @szk302/excel-petter evidence_root -o evidence.xlsx

使い方

エビデンスを次の構造で並べます。第 1 階層のディレクトリ名がシート名になります。

evidence_root/
  └─ C001/                          <-- シート名
      ├─ 1_前提準備/
      │   └─ 01_SQL_データ投入.sql
      ├─ 2_事前確認/
      │   └─ 01_DB_Before.csv
      ├─ 3_テスト操作/
      │   ├─ 01_WEB_入力画面.png
      │   └─ 02_SQL_実行クエリ.sql
      └─ 4_事後確認/
          ├─ 01_WEB_完了画面.png
          └─ 04_LOG_アプリログ.txt

# evidence_root 配下すべてを新しいブックに書き出す
excel-petter evidence_root -o evidence.xlsx

# C001 のシートだけを作り直す（他のシートには手を触れない）
excel-petter evidence_root -o evidence.xlsx --sheet C001

| オプション | 説明 | |---|---| | -o, --output <path> | 出力する .xlsx のパス（既定: evidence.xlsx） | | -s, --sheet <ID> | 対象のテスト項目 ID。複数指定可 | | --max-image-width <px> | スクリーンショットの最大幅（既定: 1000） | | --font-size <px> | テキスト画像化の文字サイズ（既定: 13） |

ファイル名の規約

連番_種別_ラベル.拡張子 の形式です。種別（大文字）で貼り付け方が決まります。

| 種別 | 貼り付け方 | |---|---| | WEB | 画像としてそのまま貼付（最大幅まで縮小） | | DB, TEXT | セルに罫線付きの表として展開 | | SQL, LOG | 等幅グリッドで PNG に画像化して貼付 |

Web や db のような表記ゆれは大文字化して同じ種別として扱うため、警告は出ません。

上の 5 つ以外の種別や、規約から外れた名前でもスキップはせず、警告を出したうえで 拡張子から判定します。

動作の約束

• CSV の値は型変換もトリムもせず、文字列のまま入れます（0001 の先頭ゼロが消えません）。
• 長いログは省略せず、必要に応じて複数枚の画像に分割して全文を貼ります。
• 既存ブックに書き込むときは、対象シートだけを作り直します。シートの並び順も変えません。

[!NOTE] 既存ブックへの書き込みは exceljs による読み書きを経由します。 グラフやピボットテーブルなど exceljs が扱えない要素を含むブックでは、 それらが保持されない可能性があります。重要なブックはバックアップを取ってください。

ライセンス

本体は MIT License です。

ただし同梱している Noto Sans JP（assets/NotoSansJP-Regular.otf）は SIL Open Font License 1.1 で、MIT ではありません。 OFL はソフトウェアへの同梱・再配布を明示的に許可しており、フォントのライセンスが 本体のコードに波及することもありません。条件は「各コピーに著作権表示とライセンス 全文を含めること」で、パッケージには両方を同梱しています（CI で検証しています）。

そのため package.json の license は SPDX 式で MIT AND OFL-1.1 としています。

依存ライブラリはすべて MIT 互換です（MIT / ISC / Apache-2.0 / BSD-3-Clause / Unlicense など）。コピーレフトのライブラリは含みません。

開発

make setup   # 依存のインストールとビルド
make build   # ビルド
make test    # テスト

テストは Node.js の型ストリップ機能を使うため、開発には Node.js 22.6 以上が 必要です（同梱の devcontainer と CI は 24.14.1）。公開パッケージ自体は dist/ のコンパイル済み JavaScript なので Node.js 20 以上で動きます。

リリースは GitHub Actions が行います。手順は docs/RELEASE.md を 参照してください。