depug

@meganemura/depugv0.2.0MIT

Measure runtime values in TypeScript test runs instead of guessing them from source.

インストール

npm install @meganemura/depug

GitHub のソースコード
使っているツール: archstrict, nukadoko
このツールを使っているツール: archstrict, firstlight, nukadoko

depug は、TypeScript のテスト失敗を、コーディングエージェントが読める証拠に変えます。失敗したテストをデバッグするエージェントは、たいてい周りのコードから値が何だったかを推測します。 depug はテストを計装して再実行し、値が実際に何だったかを報告します。 vitest と、Node 組み込みのテストランナーで動きます。

特徴

失敗時の証拠。 レポーターを設定しておくと、失敗したテストは、JSON ファイルを示す depug evidence: の行と、そのテストだけを再実行するコマンドを示す depug rerun: の行を表示します。誤った値を作ったコードがまだスタックにあるかどうかも、注記で示します。
probe。 1 つの関数へのすべての呼び出しを、引数と戻り値つきで一覧表示します。観測した値の形を宣言された型と並べて、mismatch: id was string, declared number (5 of 5 calls) のように示します。
flt。 1 回の呼び出しを行ごとに追い、どのローカル変数がどの行で変わったかを示します。 new Promise(...) を返す関数のように本体が 1 つの式だけの呼び出しでは、その呼び出しが行った呼び出しを一覧表示します。それぞれの ID は、そのまま次の flt に渡せます。
frames と preflight。 frames はテストが呼び出した関数を一覧表示し、--at <file:line> を付けるとソースの行を関数の ID に変換します。 preflight は、呼び出しの番号が 2 回の実行の間で変わらないことを確認します。最後に、depug result: fail (exit 1) in both runs のように、2 回の実行がどう終わったかを示します。
exec。 指定した 1 行の位置で、その関数自身のスコープの中で式を実行し、その結果を報告します。
rerun。 テストのコマンドを時間制限つきで実行し、既定では 120 秒で止めます。終わらないテストは、テストランナー自身のタイムアウトが依存しているワーカーをふさいでしまうからです。

関数の ID は path:name@line:column#k の形で、k は、1 つのテストの中でその関数が何回目に呼ばれたかを表します。

エージェントでの使い方

失敗したテストが、証拠のパスと再実行のコマンドを表示します。
失敗した呼び出しが記録済みのフレームにあると注記に書かれていれば、エージェントは証拠のファイルを読みます。
そうでなければ、表示されたコマンドの前に depug の verb を付けます。 depug preflight を実行し、次に怪しい関数に depug probe を、最後に誤った呼び出しに depug flt を実行します。

README の実例では、この流れで、IPv6 の処理にある切り捨てのバグを 3 つのコマンド、約 4 秒で見つけました。値を推測するために実装を読むことはしていません。 depug は verb を実行したときだけプロセスを起動するので、テストがすべて成功している間はコストがかかりません。パッケージには、出力の読み方をエージェントに教えるスキルが含まれています。

はじめかた

npm install --save-dev @meganemura/depug

vitest の設定にレポーターを加えます。 verb は設定なしで使えます。

import { defineConfig } from "vitest/config";
import DepugReporter from "@meganemura/depug/reporter";

export default defineConfig({
  test: {
    reporters: ["default", new DepugReporter()],
  },
});

npx depug probe "src/utils/ipaddr.ts:expandIPv6@13:14" -- npx vitest run "src/utils/ipaddr.test.ts" -t "^expandIPv6 Should result be valid$"