コンテンツにスキップ
meganemura/*

bulldogger

bulldoggerv0.3.1MIT

Ruby execution evidence for coding agents: failure snapshots captured at the moment a test raises, written as files an agent can read and query.

インストール

gem install bulldogger

bulldogger は、Ruby のテストの失敗を、コーディングエージェントのための構造化された証拠として書き出します。 各 JSON ファイルには、例外、バックトレース、取得したフレームの値が入ります。 失敗の出力は、そのファイルの絶対パスと、そのテストだけを再実行するコマンドを示します。 1 つのフレームを追うような重い収集は、エージェントが明示的に verb を実行したときだけ始まります。

特徴

Section titled “特徴”
  • 失敗のスナップショット。 require "bulldogger/minitest" か require "bulldogger/rspec" で、失敗した各テストを tmp/bulldogger/ の下の JSON ファイルに記録し、実行ごとに index.json を作ります。 debug gem があれば各フレームのローカル変数を、なければ例外を投げたフレームのローカル変数を記録します。
  • 再実行の行。 失敗ごとに、bulldogger evidence: のパスと、テストとシードを含む bulldogger rerun: のコマンドが出力されます。 bulldogger がそのコマンドを自分で実行することはありません。
  • 呼び出しの索引。 bulldogger frames -- <command> はテストを新しいプロセスで実行し、各呼び出しに path:method#k という形のフレーム ID を付けます。
  • 決定性の確認。 bulldogger preflight -- <command> はコマンドを 2 回実行してアプリケーションのフレームを比較します。 flt や exec は、preflight が deterministic と報告したときだけ使ってください。
  • 1 つのフレーム、1 つの文。 bulldogger flt '<fid>' -- <command> は 1 つのフレームのローカル変数を行ごとに追います。 bulldogger exec '<fid>' --line N --statement <text> -- <command> は、指定した行を通る 1 回の時点で、1 つの文を評価します。
  • プローブ。 Bulldogger.probe("Billing::Invoice#amount") { ... } は、引数と戻り値のクラス、nil の値、例外による終了、呼び出し元をまとめます。 Bulldogger.probe_compare は、2 つのプローブのファイルが identical かどうかを報告します。

エージェントでの使い方

Section titled “エージェントでの使い方”
  1. テストスイートを実行し、失敗したテストが示す証拠のパスを開きます。 そこには 1 つの失敗と、取得した値が入っています。
  2. スナップショットで足りなければ、表示された再実行のコマンドを bulldogger frames 経由で実行し、フレーム ID を取得します。
  3. 同じコマンドを bulldogger preflight で実行し、deterministic のときだけ先に進みます。
  4. bulldogger flt でフレームを追うか、bulldogger exec で 1 つの文を評価します。 評価する文が実行結果を変えることがあるので、証拠として使う前に結果のファイルを確認します。

bulldogger のスキルは、エージェントにこれらのファイルの読み方を伝えます。 gh skill install meganemura/bulldogger はデフォルトブランチからインストールし、bulldogger skill path はインストール済みの gem に合うスキルのパスを出力します。

はじめかた

Section titled “はじめかた”

両方の gem をテストのグループに加えます。

gem "bulldogger", group: :test
gem "debug", group: :test

そのうえで、test_helper.rb に require "bulldogger/minitest" を、または spec_helper.rb に require "bulldogger/rspec" を 1 行加えます。 BULLDOGGER_DISABLE=1 を設定すると、そのテストプロセスでは記録も出力も行いません。