All Works

testglass

テストコードを静的解析し、人間がレビューするためのテスト仕様書（HTML・Markdown・CSV）を生成するツール。

運用中Tora29/testglass
testglass が生成したテスト仕様書。「正しいパスワードでログインに成功する」というテストは、結果を確認しておらず固定時間の待ちもあるため「要修正」と判定されている

Overview

AI にテストを書かせると量が多く、実装まですべて読み切るのは難しい。せめてテストだけは人間がしっかりレビューできるように、テストコードを「テスト名・手順・期待結果・警告」の表に並べたテスト仕様書を生成する。テスト名と中身が一致しているかを、ソースを開かずに確かめられることが目的。

npm で公開している（testglass）。

  • Vitest と Playwright のテストに対応する。テストは実行せず、構文木から読み取る
  • アサーションが無い、.only が残っている、モックの呼び出ししか見ていない、固定時間の待ちがある、などを警告として示す
  • 出力は CSS・JS・データを埋め込んだ単一ファイルの HTML で、そのまま共有したり CI の成果物にしたりできる。Markdown・CSV でも出力できる

Architecture

  • 「テストを読む → 中間 JSON（spec.json）に保存 → JSON から成果物を生成」の3段構成。中間 JSON は JSON Schema で形式を公開している
  • 入力（テストフレームワーク）と出力（HTML・Markdown・CSV）はアダプタ方式で、アダプタを1つ足すだけで対応を増やせる
  • 手順は LLM を使わず、TypeScript Compiler API で得た構文木からルールで組み立てる。同じコードからは常に同じ結果が出る
  • 警告ルールは構文木ではなく、テストごとに抽出した「事実」を見て判定する。言語が違っても同じルールがそのまま働く

Tech

TypeScriptVitestPlaywrightGitHub Actions

Development Timeline12

  1. v0.2.0 をリリース

    細工したテストファイルで解析が止まる問題（ReDoS）を直した。Markdown 出力のエスケープ漏れもなくした。testglass を CI で使っていて、信頼できない PR を受け付けている場合は更新を勧める。

  2. 細工したテストファイルで解析が止まらないようにした

    細工したテストファイルで解析が数秒〜数分止まる問題（ReDoS）を直し、Markdown 出力のエスケープ漏れもなくした。testglass を CI で使っている場合に、信頼できない PR に含まれるファイルで CI が止められないようになった。

  3. 出力の言語をロケールから自動で決めない理由を README に書く

    出力の言語を OS のロケールから自動で決めない理由を、README の日本語版・英語版に書いた。手元と CI でレポートの言語が変わらないことと、英語にしたいときは --lang en で指定すればよいことが分かる。

  4. CLI のヘルプとメッセージを英語でも表示できるようにする

    CLI のヘルプ・進行状況・エラーメッセージを、--lang en か設定ファイルの "lang": "en" で英語でも表示できるようにした。レポートだけでなく、ツールの操作もすべて英語で行えるようになった。

  5. README にスクリーンショットと英語版を追加する

    README の先頭にテスト仕様書のスクリーンショットを載せ、日本語の本文をすべて英訳した English の節を追加した。何を見つけるツールかが一目で分かり、npm で見つけた海外の人も使い方を読めるようになった。

  6. テスト仕様書を英語でも出力できるようにする

    テスト仕様書（HTML・Markdown・CSV）を、日本語に加えて英語でも出力できるようにした。--lang en か設定ファイルの "lang": "en" を指定すると、判定・指摘・列名・ボタンなどの表示がすべて英語になる。

  7. spec.json を表示の言語に依存しない形にする

    spec.json の警告から日本語の文言を外し、ルールと詳細だけを持たせるようにした。文言はレポートを出力するときに組み立てるので、英語のレポートを出力できるようにする準備が整った。

  8. ESLint との違いを README に書く

    README に、ESLint との違いを説明する節を追加した。ESLint はコードを書く人に向けた指摘、testglass はテストをレビューする人に向けた仕様書であり、両方を併用する想定であることが分かるようにした。

  9. CLI のコマンドとオプションの説明を分かりやすくする

    README に CLI のコマンドの一覧を追加し、各オプションがどのコマンドで使えるかと、既定値の決まり方を正確に書いた。

  10. テスト仕様書を Markdown と CSV でも出力できるようにする

    テスト仕様書を、HTML に加えて Markdown と CSV でも出力できるようにした。Markdown は PR やドキュメントにそのまま貼れ、CSV は Excel で絞り込みや並べ替えができる。

  11. レポートの文字を一回り大きくして読みやすくする

    HTML レポートの文字が全体的に小さく読みにくかったので、一回り大きくした。あわせて、ばらばらだった文字サイズを 5 段階に揃えた。

  12. 指摘の一覧を判定ごとに整理し、読みやすくする

    HTML レポートの指摘一覧を、要修正・要確認ごとに指摘の種類と件数を並べる形に作り直した。ラベルも「expect がない」のように具体的な言葉にし、文字の大きさとコントラストを見直した。

この作品の Activity を見る

Related Notes