stryker-agent-reporter

stryker-agent-reporterv0.3.0Apache-2.0

A Stryker reporter that writes JSON Lines a coding agent can act on directly

インストール

npm install stryker-agent-reporter

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

stryker-agent-reporter は、コーディングエージェントのための Stryker レポーターです。 1 行に 1 つの JSON オブジェクトを書く JSON Lines を出力するので、エージェントは結果を 1 行ずつ読み、grep や jq で絞り込めます。 生き残ったミュータントの行には、その場所、元のテキストと置き換え後のテキスト、そのまま適用できるパッチ、再実行コマンドが入ります。 エージェントは、これらを Stryker 本体のレポートから改めて割り出す必要がありません。 ほかに convert と gate の 2 つのコマンドがあり、どちらもこの出力だけをもとに動きます。

特徴

• ミュータントごとに 1 行。 reports/mutation/agent.jsonl は run の行で始まり、変異させたファイルごとの scope の行、対処すべきミュータントごとの行、どのミュータントも kill しなかったテストごとの testWithoutKills の行が続きます。 testWithoutKills の行の coveredMutants は、そのテストが到達した、この実行のミュータントの数です。 これで、ミュータントに対して実行されたのに 1 つも kill しなかったテストと、--mutate で絞った範囲のミュータントに一度も到達しなかったテストを区別できます。 最後に summary の行が来るので、この行がないファイルは、実行が最後まで終わらなかったことを示します。
• 修正のための材料。 survivor の行には、git apply --unidiff-zero でそのまま適用できる patch が付きます。 そのファイルを再実行する rerun と、そのミュータントだけを再実行する rerunExact も付きます。
• 安定したキー。 各ミュータントの key は、行番号ではなく、そのミュータント自身のソースのテキストから作ります。 そのため、ファイルのほかの場所を編集しても key は変わりません。 scope の行にはそのファイルのすべてのキーが並ぶので、kill されたミュータントと、狭い mutate の範囲から外れたミュータントを区別できます。
• 実行中に読める結果。 レポーターは、完了したミュータントを 1 つずつ reports/mutation/agent.partial.jsonl に追記します。 そのため、Stryker の実行中でも tail -f で生き残ったミュータントを確認できます。
• プルリクエストのゲート。 stryker-agent-reporter gate --since origin/main --format github は、変更された行だけを検査し、GitHub Actions でその行にアノテーションを付けます。 終了コード 1 は、生き残ったミュータントか、カバーされていないミュータントが残っていることを表します。 終了コード 3 は測定の失敗を表し、テストの不足が証明されたわけではありません。 --baseline <file> を付けると、新たに生き残ったミュータントがあるときだけゲートが失敗します。
• 保存済みのレポート。 stryker-agent-reporter convert は、保存済みの mutation.json を同じ JSON Lines に変換します。

エージェントでの使い方

1. agent レポーターを指定して Stryker を実行し、実行中は agent.partial.jsonl を読みます。
2. 生き残ったミュータントを抽出します。 たとえば jq -c 'select(.kind=="survivor")' reports/mutation/agent.jsonl を使います。
3. 生き残ったミュータントごとに original、replacement、patch を読んで変更を加え、その rerunExact のコマンドで、そのミュータントをもう一度テストします。
4. CI では gate --since を実行し、プルリクエストが、自分で変更した行のミュータントでだけ失敗するようにします。

はじめかた

npm install --save-dev stryker-agent-reporter

Stryker の設定に agent レポーターを加えます。 Stryker の既定の plugins は @stryker-mutator/* しか読み込まないので、このパッケージも明示的に指定します。

{
  "reporters": ["clear-text", "agent"],
  "plugins": ["@stryker-mutator/*", "stryker-agent-reporter"]
}