wallaby-cli

Wallaby は、コーディングタスクの間、JavaScript、TypeScript、Python のテストを常に実行可能な状態に保ち、いつでも照会できるようにします。ファイルの変更に応じて影響を受けるテストを実行し、最新の結果、カバレッジ、実行データを利用できる状態に保つため、エージェントはターミナル出力から動作を再構成するのではなく、コードが実際に何をしたかを調べられます。

Wallaby は、Vitest、Jest、Jasmine、Mocha、Angular の ng test、pytest、Python の unittest、またはその他のサポート対象フレームワークを使う既存のプロジェクトのテスト環境を置き換えるものではありません。既存のテストをそのフレームワーク経由で実行し、コーディングエージェント向けに、変更の影響を受けるテストのライブ実行、保持されて照会可能な状態、カバレッジ成果物、実行トレース、実行時の調査機能を追加します。コーディングタスク中のテスト実行と分析には、フレームワークを直接呼び出す代わりに Wallaby を使用してください。npm test、npx vitest、ng test などの従来のテストコマンドを実行するのは、ユーザーから直接実行するよう明示的に求められた場合に限ります。

このライブテスト状態を活用して、次のことを行います。

• 編集を始める前に、現在の失敗、カバレッジ、変更予定のコードを実行するテストを確認して、ベースラインを把握します。
• 編集中は、フィードバックの対象を絞ります。まず関連テストから始め、変更範囲の拡大に合わせて関連テストを追加し、タスクで必要な場合は最後にプロジェクト全体の検証を行います。
• ファイルのバッチ、1 つのソースファイルまたはテストファイル、正確なソース位置、あるいは簡潔な概要から 1 つのテストを分析し、必要な場合にのみ、別途提供されるカバレッジや関連テストの成果物を確認します。カバレッジ、変更リスク、テストの状態、実行時間を参考に、何をどの範囲で変更・検証するかを判断します。
• 複数のソースファイルにまたがる 1 つのテストの結果とカバレッジを分析します。--trace を追加すると、そのテストを再実行し、関係するすべてのファイルにわたって記録されたソース行を実行順に確認できます。トレースにはインポートされたモジュールとセットアップが含まれ、選択したテストの開始位置が示され、そのテストが到達する各ソース行が順に表示されます。同じレポートには、補足的な診断情報として、テストの状態、実行時間、エラー、ログ、カバレッジ対象ファイルも表示されます。
• 1 回のリクエストで、異なるソース位置にある複数の変数や式を調べます。各値は、その位置に到達するすべてのテストコンテキストで取得され、値を生成したテストと関連付けられます。調査対象を絞る場合は、統合された結果を 1 つのテストにフィルターします。コードを変更したり、一時的なログを追加したりする前に、この実行時の証拠を活用します。
• カバレッジや、実行時間、テスト数、複雑さ、変更リスクなどのテストとファイルに関する指標をプロジェクト全体で確認し、意味のあるテストの不足、遅いテストや結合度の高いテスト、より広範な検証が必要な変更を特定します。

コマンドがレポートを生成した場合は、まず簡潔な Markdown 出力を確認し、現在の疑問にさらに詳しい情報が必要な場合にのみ、リンクされたレポートや成果物を開きます。Wallaby は生成したすべてのレポートと成果物をタイムスタンプ付きのディレクトリにディスク上で保存するため、比較が役立つ場合は、以前の結果を履歴スナップショットとして引き続き利用できます。

環境要件

サンドボックスでは、CLI に ~/.wallaby への読み取りおよび書き込みアクセスが必要です。Wallaby のダウンロードまたは更新時には https://*.wallabyjs.com へのネットワークアクセスが必要です。また、@wallabyjs/cli がすでにインストールされていない場合は、設定済みの npm レジストリへのアクセスが必要です。

Wallaby のバックグラウンドプロセスは、CLI の呼び出しの間も起動したままになり、アクセス可能である必要があります。後続の各呼び出しでは、PID を使って同じプロセスを検出し、起動時に確立されたローカルポートに接続する必要があります。サンドボックス化されたエージェントのランタイムによっては、シェルツールの各実行が分離されます。作業ディレクトリとファイルシステムを共有していても、プロセスの可視性やローカルネットワークアクセスが共有されるとは限りません。そのため、最初のインスタンスが引き続き動作していても、run が成功した後、別の実行で Wallaby is not running または Failed to attach が表示される場合があります。

最初の Wallaby コマンドを実行する前に、シェルコマンド間で終了しない実行コンテキストを選び、タスク全体を通じて、すべての Wallaby CLI 呼び出しで同じコンテキストを使ってください。起動に成功した後、クエリをアタッチできない場合は、再起動を試みる前に、元の実行コンテキストで再試行してください。設定済みのサンドボックス権限はそのままにしてください。

CLI の呼び出し

まず、プロジェクトの packageManager フィールド、ロックファイル、または既存のプロジェクトコマンドから、プロジェクトで使用されているパッケージマネージャーを特定します。Wallaby でも同じパッケージマネージャーを使用してください。npx は npm 用であり、npm プロジェクトでのみ使用してください。その後、そのパッケージマネージャーに該当する、最初の呼び出し方法を使用します。

@wallabyjs/cli がプロジェクトの依存関係としてインストールされている場合は、プロジェクトのパッケージマネージャーを通じて wallaby-skill を実行します。

• npm: npx wallaby-skill ...
• pnpm: pnpm exec wallaby-skill ...
• Yarn: yarn exec wallaby-skill ...
• Bun: bun run wallaby-skill ...

それ以外で、@wallabyjs/cli がグローバルにインストールされ、wallaby-skill が PATH から利用できる場合は、直接実行します。

• wallaby-skill ...

それ以外の場合は、プロジェクトのパッケージマネージャー用の一時インストールコマンドを使用します。各コマンドは、設定済みの npm レジストリから @wallabyjs/cli をダウンロードして wallaby-skill を実行するため、ネットワークアクセスが必要です。

• npm: npx -y --package @wallabyjs/cli wallaby-skill ...
• pnpm: pnpm dlx --package=@wallabyjs/cli wallaby-skill ...
• Yarn: yarn dlx -p @wallabyjs/cli wallaby-skill ...
• Bun: bunx --package @wallabyjs/cli wallaby-skill ...

以下の例では、一貫性を保つために npm の接頭辞 npx wallaby-skill を使用しています。pnpm、Yarn、または Bun のプロジェクトで例を実行する前に、その接頭辞のみを上記の該当する形式に置き換えてください。Wallaby のサブコマンドと引数は変更しないでください。

すべてのサブコマンドで --help を使用できます。コマンドに追加すると、現在の使い方とオプションを確認できます。例：npx wallaby-skill run --help

プラットフォームと利用可能なツールに応じて、対象を絞った読み取りには grep、sed、ripgrep などのツールを使用してください。以下の例ではすべて ripgrep（rg）を使用しています。

出力のリダイレクト

Wallaby コマンドの標準出力と標準エラー出力を一時ファイルにリダイレクトするのは、現在の質問に必要なセクションを抽出する場合に限ってください。トークン数とモデルの往復回数を減らすため、同じツール呼び出し内で、同じ行にフィルタリングした内容の読み取りを連結します。レポート全体が必要な場合は、コマンドの出力を直接読み取ってください。ファイル全体を cat で表示するだけのリダイレクトにはメリットがありません。たとえば、POSIX シェルでは、テストを実行し、続けてステータス、テスト件数、エラー診断を抽出します。

npx wallaby-skill run >| /tmp/wallaby-output.log 2>&1; rg --no-line-number -U --pcre2 -o '(?sm)^(?:Status:|- (?:Total|Passed|Failed|Skipped|Todo):)[^\n]*|^## (?:Fatal Error|Global Errors|Failing Tests)\r?\n.*?(?=^## |\z)' /tmp/wallaby-output.log

ログのステータスとエラーに加え、現在の質問に必要なカバレッジまたは実行時の証拠を読み取って、結果を確認します。必要なコンテキストが抜粋に含まれていない場合は、抜粋の範囲を広げてください。

実行コマンド

永続的な Wallaby テストセッションを開始または照会するには、run を使用します。--config を指定しない場合、Wallaby はコマンドを実行したディレクトリによってプロジェクトを識別します。--config を指定した場合は、指定された Wallaby 設定ファイルによってプロジェクトを識別します。実行中のセッションとそのライブ結果を再利用するには、後続の呼び出しでも同じ作業ディレクトリまたは --config の値を使用してください。

Wallaby セッションは、同じ実行中のインスタンスにアクセスできるエージェントスレッド間で、プロジェクトの識別情報に基づいて共有されます。たとえば、複数のスレッドが同じ Git worktree で作業し、run --config ./wallaby.js を呼び出すと、実行環境が許せば同じセッションに接続されます。--config を省略して同じディレクトリから実行する場合も同様です。モード、スコープ、ライブテスト状態は共有されます。いずれかのスレッドがファイルを変更すると、Wallaby は影響を受けるテストをバックグラウンドで再実行し、接続中のすべてのスレッドが更新された結果、カバレッジ、実行データを読み取れます。

プロジェクトで Wallaby がまだ実行されていない場合、最初の run 呼び出しによってモードが決まります。

• テストファイルのパスを指定しない場合、Wallaby はプロジェクトモードで起動し、プロジェクト全体を実行して監視します。
• 1 つ以上のテストファイルのパスを指定した場合、Wallaby は排他モードで起動し、それらのテストファイルのみを実行して監視します。

事前に run --check を実行せず、必要なスコープを指定して run を開始してください。プロジェクトのセッションを開始または再利用し、レポートを返します。

プロジェクトモードでのコールドスタートでは、最初にテストスイート全体を実行する必要があります。また、プロジェクト全体を対象とする --rerun では、すべてのテストが再度スケジュールされます。どちらも、大規模なスイートではかなり時間がかかることがあります。プロジェクト全体のカバレッジや全テストスイートの検証が必要な場合を除き、関連する最小限のテストファイルを排他モードで開始または維持してください。返されたレポートの Mode を確認してください。プロジェクトモードでは、Total と Time を使ってプロジェクト全体の再実行にかかる時間を見積もれます。排他モードでは、これらの値はアクティブなスコープのみを対象とします。排他セッションからプロジェクト全体のコストを見積もるには、レポート内の絶対パスのリンクからタイムスタンプ付きディレクトリに移動し、保持されている兄弟ディレクトリを調べて、Mode: project を含む最新の run.md を確認してください。

後続の run 呼び出しでは、同じセッションが再利用されます。

• プロジェクトモードでは、--rerun や --snapshots を指定せずにテストファイルのパスを渡すと、別の実行をスケジュールしたり監視対象のスコープを狭めたりせず、プロジェクト全体の現在の状態を読み取ります。要求されたファイルの失敗は、インラインレポートの先頭に表示されます。
• 排他モードでは、追加のテストファイルのパスを渡すと、それらがアクティブな排他スコープに追加されます。
• 排他モードでテストファイルのパスを指定せずに run を呼び出すと、セッションはプロジェクトモードに拡張されます。その後、Wallaby はプロジェクト全体を実行して監視し、後続のファイルを指定した呼び出しでも排他モードには戻りません。

Wallaby は各コマンドの後もセッションを実行状態に保ち、ファイルの変更に応じて影響を受けるテストをバックグラウンドで実行し、run、analyze、inspect にライブデータを提供します。セッションに必要なテストが含まれたら、レポートから必要なデータを得られる場合は analyze または inspect を直接呼び出してください。run は、そのレポートのデータが必要な場合にのみ呼び出します。テストの実行中にこれらのコマンドのいずれかを呼び出すと、Wallaby がアイドル状態になるまで待機します。その待機中にさらに編集を行うと、影響を受けるテストがスケジュールされ、待機時間が延長されます。そのため、返されるレポートにはそれらの変更が反映されます。

初回の実行やプロジェクト全体の実行に時間がかかる場合は、バックグラウンドターミナルまたは認可されたサブエージェントで run を開始し、実行中に独立した分析や編集を進めてください。コマンドの実行中に行われた変更は Wallaby によって検出され、その影響を受けるテストはコマンドが返る前に完了します。そのターミナルから別の Wallaby コマンドを送信したり、そのレポートを検証結果として使用したりする前に、コマンドの完了を待ってください。 デフォルトでは --rerun を省略してください。最近の編集、最終確認、時間の計測を行っても、ライブ結果が古くなるわけではありません。--rerun は、ライブ状態が古いと特定できた場合の復旧手段として使用してください。有効な理由は、Wallaby が監視できない関連する外部状態がある場合、または監視対象の変更後に再実行されなかったことを確認した場合です。強制実行する前に、その理由を明示してください。復旧の対象は、影響を受けていると判明している最小限のテストセットに絞ってください。該当するファイルだけを再実行するには、テストファイルのパスを指定し、名前を指定した1つのテストだけを再実行するには --test も追加します。対象を絞った --rerun は、プロジェクトモードで、プロジェクトの残りを再実行したり、セッションを排他モードに切り替えたりせずに機能します。テストファイルのパスを省略するのは、プロジェクト全体のライブ結果が古いことを示す根拠がある場合に限ってください。

スナップショットの失敗が意図した出力の変更を示すものだと確認してから、--snapshots を使用してください。更新の対象は、影響を受けたテストに絞ってください。該当するファイルのスナップショットだけを更新するには、テストファイルのパスを指定し、名前を指定した1つのテストのスナップショットを更新するには --test も追加します。プロジェクトモードでは、対象を絞ったスナップショット更新を行ってもセッションはプロジェクトモードのままで、ほかのテストのスナップショットは更新されません。テストファイルのパスを省略するのは、プロジェクト全体のスナップショットを更新する場合に限ってください。Wallaby がまだ実行されていない場合は、引き続き上記の初回実行時のモード規則に従ってください。

--test で1つのテストを対象にするには、テストファイルを1つだけ指定し、そのテストの正確な完全名を、スイートのパスを / でつないだ形で指定してください。名前がそのファイル内で実行されたテストと一致しない場合、Wallaby はファイル内のすべてのテストを対象にします。複数のファイルパスを指定した場合、--test で対象を絞り込むことはできません。

npx wallaby-skill run # starts or reuses project mode and reports project-wide test results
npx wallaby-skill run --config ./wallaby.js # starts or reuses project mode identified by the specified config file
npx wallaby-skill run ./src/feature-a.spec.ts # starts or extends exclusive scope, or reads this file's results in project mode
npx wallaby-skill run ./src/feature-a.spec.ts ./src/feature-b.spec.ts # starts exclusive mode if needed, or reads their results according to the active mode
npx wallaby-skill run ./src/feature-a.spec.ts --test "feature-a / should match the expected value" # reads this exact test after any automatic affected-test run finishes
npx wallaby-skill run --rerun ./src/feature-a.spec.ts # forces this test file to rerun after observing stale results; add --test with the exact full name to rerun one test
npx wallaby-skill run --snapshots ./src/feature-a.spec.ts ./src/feature-b.spec.ts # updates snapshots only for the specified test files
npx wallaby-skill run --snapshots ./src/feature-a.spec.ts --test "feature-a / should match the expected snapshots" # updates snapshots for the named test in the specified file
npx wallaby-skill run --snapshots # updates snapshots across the project; use only when every snapshot change is intended
npx wallaby-skill run --check # returns the current report only when Wallaby is already running; does not launch or run tests

このコマンドは簡潔な Markdown レポートを出力し、同じ内容を run.md に保存します。レポートが生成された場合、終了コード 0 は Status: succeeded、終了コード 1 は Status: failed に対応します。テストが1つ以上失敗した場合、Wallaby で致命的な実行エラーが発生した場合、またはグローバルエラーが存在する場合、ステータスは失敗になります。CLI の起動、接続、互換性に関するエラーでも終了コード 1 が返されますが、レポートの代わりにエラーが出力されることがあります。

レポートは次の順序で確認してください。

• Status と Mode は、現在の状態が成功したかどうか、およびプロジェクト全体を対象としているか、現在アクティブな専用テスト場所のみを対象としているかを示します。
• Runner と Framework は、Wallaby が報告できる場合に、実行環境とテストフレームワークを示します。
• 専用モードでは、Note: Wallaby is running tests only from specific test locations: にアクティブな範囲が一覧表示されます。このレポート内のすべての件数とカバレッジ値は、それらの場所を対象としているものとして扱ってください。
• Summary には、次のフィールドが含まれます。
  • Total：テストの総数です。
  • Passed：成功したテストの数です。
  • Failed：失敗したテストの数です。
  • Skipped：スキップされたテストの数です。
  • Todo：TODO テストの数です。
  • Coverage：テストでカバーされている、カバー可能なコード範囲の割合です。カバレッジが低い場合、Wallaby は (low) を付加します。
  • Time：報告された各テストの実行時間を合計した、テスト実行時間の合計です。
• Fatal Error は、個々のテストを実行する前に発生したエラーを含む、実行単位のエラーがある場合に表示されます。
• Global Errors は、特定のテストに関連付けられていないエラーがある場合に表示され、インラインで最大 3 件のエラーが含まれます。それ以上のエラーがある場合、レポートはすべてのグローバルエラーを記載した global-errors.md へのリンクを表示します。形式については references/global-errors.md を参照してください。
• Failing Tests には、失敗したテストが最大 5 件、名前、場所、実行時間、エラー、アサーションまたはスナップショットの詳細、スタックトレース、ログ、カバー対象ファイルとともにインラインで表示されます。run に渡されたファイルパスの失敗が先に並びます。それ以上の失敗がある場合、レポートはすべての失敗を記載した failing-tests.md へのリンクを表示します。形式については references/failing-tests.md を参照してください。
• Global Logs は、Wallaby が個々のテストの外部でログを取得した場合に global-logs.md へのリンクになります。形式については references/global-logs.md を参照してください。
• All Tests は、テストが存在する場合に all-tests.md へのリンクになります。リンク先のレポートには、実行時間とテスト件数のランキングに続いて、すべてのテストのステータス、場所、実行時間、ログ、カバー対象ファイルが記載されます。失敗の診断情報は Failing Tests に記載されます。形式については references/all-tests.md を参照してください。
• Coverage は、レポート可能なカバレッジがある場合に coverage.md へのリンクになります。リンク先のレポートでは、変更リスクに基づいてファイルがランキングされ、カバー対象の各ソースファイルについて、カバレッジ、複雑度、変更リスク、カバーするテストファイルが記載されます。形式については references/coverage.md を参照してください。
• Graphical User Interface は、UI の URL が利用可能な場合に Wallaby UI へのリンクになります。このリンクは、ユーザーが UI を開くよう明示的に依頼した場合にのみ使用してください。

All Tests 内で estimates sleet near freezing に言及するすべてのテストを検索するには：

rg -U --pcre2 -o '(?sm)^### [^\n]*estimates sleet near freezing[^\n]*\n.*?(?=^### |^## |\z)' all-tests.md

tests/temperature.spec.ts 内のすべてのテストを検索するには：

rg -U --pcre2 -o '(?sm)^## tests/temperature\.spec\.ts[^\n]*\n.*?(?=^## |\z)' all-tests.md

src/temperature.ts のカバレッジ項目を検索するには：

rg -U --pcre2 -o '(?sm)^## src/temperature\.ts[^\n]*\n.*?(?=^## |\z)' coverage.md

analyze コマンド

analyze を使うと、未カバーのコードを見つけたり、あるファイルや場所をどのテストが実行するかを特定したり、テストの失敗を調べたり、複数のファイルにまたがるテストの実行を追跡したりできます。必要な情報に応じて、分析の種類を選択してください。

• テスト分析では、テスト結果と、そのテストがカバーするすべてのソースファイルのカバレッジが表示されます。--trace を使うと、任意で実行トレースも表示できます。
• ファイル分析では、ファイルのカバレッジと、そのファイルまたはファイル内の場所をカバーするテストに関する情報、あるいはテストファイルに属するテストに関する情報が表示されます。カバレッジとテストの情報は、特定のテストに絞り込めます。
• 複数ファイル分析では、複数のファイルに対する同じファイル単位のカバレッジとテスト情報を、1 つのコマンドでまとめた Coverage Gaps レポートとして表示します。

分析レポートのカバレッジ指標と Uncovered の行および列範囲を、主なカバレッジの根拠として使用してください。特定のカバレッジに関する質問に答えるには情報が不十分で、詳細なソース注釈が必要な場合に限り、リンクされた .wcov 成果物を読み取ってください。必要な場合も、関連する範囲のみを読み取ってください。

このコマンドは、run と同じプロジェクト ID で Wallaby がすでに実行されている場合にのみ使用できます。Wallaby を最初にプロジェクトモードで起動するか、分析対象のテストファイル、または分析対象のソースファイルをカバーするテストを含む排他モードで起動してください。その後、run と同じ作業ディレクトリから、または同じ --config 値を指定して analyze を実行します。必要なテストを含むアクティブなセッションでは、編集後を含め、事前に run を実行する必要はありません。

テスト分析または単一ファイル分析で指定された対象を解決できない場合、コマンドはゼロ以外のコードで終了し、レポートの代わりにエラーメッセージを出力します。これには、無効なパス、存在しないファイル、テストファイルではないテスト対象のパス、存在しないテスト名、解決できないソースファイルの場所が含まれます。複数ファイル分析では、解決できないパスごとのエラーが Files Not Analyzed に報告され、解決可能なパスについては引き続き分析されます。

このコマンドは Markdown レポートを出力し、同じ内容を analyze.md に保存します。

分析の種類

テスト分析

1 つのテストの結果、エラー、ログを調査したり、ソースファイル全体でのカバレッジを確認したり、予期しない動作を説明するために実行を追跡したりする場合は、--target test を使用してください。

テストファイルのパスと、スイート名を / で連結した正確なテスト名全体を指定してください。

npx wallaby-skill analyze --target="test" "{path:'tests/temperature.spec.ts',name:'celsiusToFahrenheit / converts boiling point'}"

実行順序やファイル間の制御フローを追跡して、失敗、予期しない成功、エラー、ログを説明する場合は、--trace を追加してください。--trace を指定しない場合と同じレポートに、Test Execution Trace リンクが追加されます。

npx wallaby-skill analyze --target="test" "{path:'tests/temperature.spec.ts',name:'celsiusToFahrenheit / converts boiling point'}" --trace

メインレポートには次の情報が含まれます。

• Status、Mode、および Fatal Error または Global Errors（実行コマンドのレポートと同じ意味です）。Status はアクティブなセッションの状態を示すため、選択したテストが成功していても failed になる場合があります。
• Test Analysis には、選択したテストの完全な名前、ステータス、利用可能な場合は場所、実行時間、エラー、アサーションまたはスナップショットの差分、ソースのコンテキストを含むスタックトレース、ログが表示されます。
  • --trace を指定した場合、テスト項目の前に Test Execution Trace リンクが表示されます。トレースには、インポートやセットアップを含む、ファイルをまたいで実行されたソース行が順に表示され、選択したテストの最初の行には test starts here とマークされます。形式については references/test-trace.md を参照してください。
• Covered Files には、カバレッジをエクスポートできる各対象ソースファイルの項目が表示されます。
  • ファイルのメタデータと利用可能なメトリクスには、パス、行数、カバレッジ、change risk anti-patterns、サイズが含まれます。カバレッジメトリクスは選択したテストが対象です。
  • ファイルにカバレッジの抜けがある場合、Uncovered: には、完全に未カバーの行と、一部がカバーされている行の未カバー列範囲が表示されます。
  • 各 Detailed Coverage リンクから、選択したテストに対するファイル全体のカバレッジを示す .wcov アーティファクトを開けます。
• Run Report から、同じセッション状態のより広範な診断情報を示す、run コマンドのレポートと同じ形式のレポートに移動できます。

生成された Test Execution Trace アーティファクトは大きくなる場合があります。アーティファクト全体を読むのではなく、対象を絞って検索してください。たとえば、選択したテストの開始位置を見つけるには、次のようにします。

rg -n -B 20 -A 5 'test starts here' test-trace.md

ファイル分析

ソースファイルのカバレッジギャップを特定する、ソースファイルまたは行番号や行・列で指定した位置をカバーするテストを特定する、テストファイルの失敗を調査する、あるいは特定のテストがソースファイルのどの行や式をカバーしているか確認する場合は、--target file を使用します。

必須の path を指定したセレクターを渡します。特定の行、または行と列をカバーするテストが必要な場合は、location を追加します。行と式は分かっていても列が分からない場合は、line と expression を渡します。Wallaby が列を解決します。ソースの断片と式が分かっている場合は、fragment と expression を渡します。Wallaby が行と列を解決します。複数行の断片に含まれる特殊文字や改行のエスケープを避けるには、base64 エンコードした fragment を使用します。CLI はファイルを検索する前に断片をデコードします。

npx wallaby-skill analyze --target="file" "{path:'src/temperature.ts'}" # analyzes the specified source file
npx wallaby-skill analyze --target="file" "{path:'src/temperature.spec.ts'}" # analyzes the specified test file
npx wallaby-skill analyze --target="file" "{path:'src/temperature.ts',location:{line:10}}" # analyzes the specified location in the source file by line number
npx wallaby-skill analyze --target="file" "{path:'src/temperature.ts',location:{line:10,expression:'celsius'}}" # analyzes the specified location in the source file by line number, using the expression to resolve the column
npx wallaby-skill analyze --target="file" "{path:'src/temperature.ts',location:{line:10,column:10}}" # analyzes the specified location in the source file by line and column numbers
npx wallaby-skill analyze --target="file" "{path:'src/temperature.ts',location:{fragment:'return (celsius * 9) / 5 + 32;',expression:'celsius'}}" # analyzes the specified location in the source file by fragment search, using the expression to resolve the line and column in the first fragment match
npx wallaby-skill analyze --target="file" "{path:'src/temperature.ts',location:{fragment:'cmV0dXJuIChjZWxzaXVzICogOSkgLyA1ICsgMzI7',expression:'celsius'}}" # analyzes the specified location in the source file by base64-encoded fragment search, using the expression to resolve the line and column in the first fragment match

選択したファイルのカバレッジと関連テストを 1 つのテストに絞り込むには、テストファイルのパスと、スイート名を / でつないだ正確な完全名を指定して、--test を追加します。

npx wallaby-skill analyze --target="file" "{path:'src/temperature.ts'}" --test "{path:'tests/temperature.spec.ts',name:'celsiusToFahrenheit / converts boiling point'}" # analyzes the specified source file and filters to the exact test

そのテストがカバーするすべてのソースファイルのカバレッジを確認するには、--trace を付けずに --target test を使用します。

メインレポートには、次の情報が含まれます。

• Status、Mode、および該当する場合は Fatal Error または Global Errors。それぞれの意味は run コマンドのレポートと同じです。
• ソースファイルの場合は File Analysis、テストファイルの場合は Test File Analysis。
  • ファイルのメタデータと、パス、位置、テスト数、行数、カバレッジ、change risk anti-patterns、サイズなど、利用可能な分析指標。--test フィルターに一致する場合、カバレッジ指標と .wcov アーティファクトは選択したテストのみを対象とします。
  • ファイルにカバレッジギャップがある場合、Uncovered: には、完全にカバーされていない行と、一部しかカバーされていない行の未カバー列範囲が一覧表示されます。
  • 関連性の高い失敗テストのエントリーが最大 5 件含まれます。各エントリーにはテストの完全名が見出しとして表示され、ステータス、位置、所要時間、エラーメッセージ、アサーションまたはスナップショットの差分、ソースコンテキスト付きスタックトレース、ログ、および利用可能な場合はカバー対象ファイルが示されます。関連性はセレクターに従います。ソースファイルまたは位置をカバーするテスト、テストファイルに属するテスト、またはフィルターに一致するテストが対象です。失敗が 5 件を超える場合、ソースファイルでは Covering Tests リンク、テストファイルでは Tests リンクの前に、省略された失敗数が表示されます。これらのリンクには、省略された失敗を含む関連テストの一覧がすべて含まれます。
• ソースファイルの場合は Covering Tests リンク、テストファイルの場合は Tests リンクがあり、関連テストの一覧全体を含む別のアーティファクトを参照します。メインレポートにはその一覧はインライン表示されません。リンクにはアーティファクトのサイズが含まれます。テストの識別情報、ステータス、位置、所要時間、ログ、またはカバー対象ファイルが必要でない限り、大きなテスト一覧は開かないでください。関連するテストまたはプロパティが 1 つだけの場合は、一覧を直接検索してください。2 種類のアーティファクト形式については、references/file-tests.md を参照してください。
• Detailed Coverage は、ファイルの完全なカバレッジを示す .wcov アーティファクトへのリンクです。
• Run Report は、同じセッション状態からより広範な診断情報を確認できる、run コマンドのレポートと同じ形式のレポートへのリンクです。

Covering Tests と Tests の一覧は大きくなる場合があります。関連テストを選択または調査するときに開き、一覧全体を読む代わりに、対象を絞って検索してください。たとえば、テストを 1 つ見つけるには次のようにします。

rg -U --pcre2 -o '(?sm)^### [^\n]*generates severe heat alert[^\n]*\n.*?(?=^### |^## |\z)' [email protected]

ファイル分析

ソースファイル間のカバレッジの不足箇所を比較する場合や、複数のソースファイルまたはテストファイルのカバレッジと関連テストの情報を1つのレポートで確認する場合は、--target files を使用します。

タスクに関連する特定のソースファイルまたはテストファイルを分析するには、paths 配列を渡します。

npx wallaby-skill analyze --target="files" "{paths:['src/accounts.ts','src/contracts.ts']}" # analyzes the specified source files
npx wallaby-skill analyze --target="files" "{paths:['src/accounts.ts','tests/accounts.spec.ts']}" # analyzes the specified source and test files

セレクターで指定できるのはファイルパスのみです。特定のソース位置を分析するには --target file を使用します。また、--test と組み合わせると、ファイルのカバレッジと関連テストの結果を特定のテストに絞り込めます。

セレクターを省略すると、アクティブなセッションでレポート対象となるカバレッジが最も低いソースファイルを最大20個分析します。

npx wallaby-skill analyze --target="files" # analyzes up to 20 source files with the lowest coverage

メインレポートには次の情報が含まれます。

• Status、Mode、および Fatal Error または Global Errors。それぞれの意味は run コマンドのレポートと同じです。
• ファイルテーブルとカバレッジの概要を示す Files Analysis。
  • 分析対象のすべてのソースファイルについて、パス、カバレッジ、変更リスク、ギャップ数を示すソースファイルテーブル。ギャップがないファイルや、カバレッジを取得できないファイルも含まれます。行は、カバレッジが低い順、変更リスクが高い順、パス順に並びます。メトリクスを取得できないファイルは最後に表示されます。
  • テストファイルが含まれる場合は、パス、テスト数、失敗したテスト数を示すテストファイルテーブル。
  • ソースファイルテーブルの順に、ソースファイルごとの簡潔な ### <path> セクションが最大20個続きます。ファイルにギャップがある場合は、Uncovered: の後に未カバーの行番号と列範囲が示されます。それ以外の場合は、ギャップがないか、カバレッジを取得できないことが示されます。
  • 分析できなかったパスを示す Files Not Analyzed。メインレポートには最大3件のエラーが表示されます。リンク先の Coverage Gaps レポートにはすべてのエラーが含まれます。
• 分析対象のすべてのファイルについて、未カバーの式のテキストと Covering Tests または Tests、Detailed Coverage へのリンクを含む詳細結果をまとめた完全なバッチレポートへのリンク Coverage Gaps。詳細は references/coverage-gaps.md を参照してください。
• 同じセッション状態から広範な診断情報を確認できる、run コマンドのレポートと同じ形式のレポートへのリンク Run Report。

Coverage Gaps 内のすべてのファイルセクション見出しと行番号を一覧表示するには：

rg -n '^## ' coverage-gaps.md

レポート内で src/accounts.ts の見出しと行番号を探すには：

rg -n -Fx '## src/accounts.ts' coverage-gaps.md

見出しから始めて、次のファイルセクションの直前まで src/accounts.ts のセクション全体を表示するには：

rg -U --pcre2 -o '(?sm)^## src/accounts\.ts\n.*?(?=^## |\z)' coverage-gaps.md

詳細なカバレッジ

.wcov アーティファクトには、ソースの行番号とカバレッジ状態（full、partial、none）が注釈として付与されたソースファイル全体が含まれます。ソースファイルの行数と行位置は保持されます。つまり、アーティファクト内のN行目はソースファイルのN行目に対応するため、ソースの行番号からカバレッジ情報を直接確認できます。部分的にカバーされた行では、取得可能な場合、未カバーの式の範囲も示されます。ソースのコンテキストで、実行された行や式、実行されなかった行や式を確認するには、このアーティファクトを使用してください。一致する --test フィルターを指定したテスト分析およびファイル分析では、選択したテストのカバレッジが表示されます。それ以外の場合は、アクティブなセッションのカバレッジが反映されます。形式については、references/wcov.md を参照してください。

アーティファクトは大きくなる場合があります。全体を読むのではなく、対象を絞って検索してください。たとえば、部分的にカバーされた行を探すには：

rg -n 'coverage: partial' [email protected]

まったくカバーされていない行を探すには：

rg -n 'coverage: none' [email protected]

src/alerts.ts のソース行146をカバレッジ注釈とともに表示するには：

sed -n '146p' [email protected]

カバレッジ注釈と前後の行を含めて、ソース内の式を探すには：

rg -n -C 3 -F 'alerts.push({' [email protected]

Inspect コマンド

静的なソース、カバレッジ、エラー、既存のログでは説明できない実行時状態が、失敗や予期しない動作の原因となっている場合は、inspect を直接使用します。正確なソース位置で変数や式を調べ、状態の変化を追跡したり、分岐の背後にある入力や条件を確認したり、アサーションが特定の値を受け取る理由を調べたりできます。一時的な console.log 文を追加して後で削除する代わりに、この実行時の証拠を活用してください。 このコマンドは、run と同じプロジェクト ID で Wallaby がすでに実行されている場合にのみ機能します。まず Wallaby をプロジェクトモードで起動するか、検査対象の場所に到達するテストを含む排他モードで起動してください。次に、run と同じ作業ディレクトリから、または同じ --config 値を指定して inspect を実行します。必要なテストが含まれているアクティブなセッションでは、編集後を含め、先行する run は不要です。

各検査では、ソースの場所に到達するすべてのテスト実行コンテキストで式の値を取得し、それぞれの値を生成したテストを特定します。関連する実行時の状態をまとめて調べるには、1 回のリクエストで異なるファイルや場所を対象とする複数の検査を渡します。--test を使うと、完全な未フィルタリング結果へのリンクを保持したまま、メインレポートに表示する値を一致するテストのものに絞り込めます。

リクエスト内の解決済みの検査ごとに、Wallaby は一時的な実行時インストルメンテーションを追加し、影響を受けるテストをまとめて実行して、リクエストされたすべての値を収集します。コマンドは、それらのテストが完了するまで待ってから、一貫性のあるレポートを返します。--test は報告する値をフィルタリングしますが、実行する影響対象のテストは制限しません。

値を収集した後、検査対象を指定せずに inspect --clear を使って、それらを削除します。クリアのみのリクエストではテストはスケジュールされず、セッションがアイドル状態であればすぐに完了します。--clear と新しい検査対象を組み合わせると、Wallaby はまず以前の値をクリアし、その後、新しいインストルメンテーションを追加して通常どおり影響対象のテストを実行します。

各検査対象は、ファイルパス、ソースの場所、式を含む個別の引数として渡します。ソースの場所には、コード断片、行番号、または行番号と列番号を指定できます。たとえば、src/alerts.ts の alerts 変数の値を検査するには、次のようにします。

npx wallaby-skill inspect "{path:'src/alerts.ts',location:{fragment:'const alerts: WeatherAlert[] = [];'},expression:'alerts'}" "{path:'src/alerts.ts',location:{line:134},expression:'alerts'}"

断片ベースの場所では、その断片がファイルの検索条件と、ファイル内で式を見つけるための包含スニペットの両方として機能します。行番号を計算する必要がないため、断片ベースの場所はコーディングエージェントに適していることがよくあります。

base64 でエンコードした fragment を使うと、複数行にわたる断片内の特殊文字や改行をエスケープせずに済みます。CLI はファイルを検索する前に断片をデコードします。

npx wallaby-skill inspect "{path:'src/alerts.ts',location:{fragment:'Ly8gdW5pcXVlIGNvZGUgZnJhZ21lbnQKY29uc3QgYWxlcnRzOiBXZWF0aGVyQWxlcnRbXSA9IFtdOw=='},expression:'alerts'}"

行番号がわかっている場合は、断片の代わりに行番号を使います。

npx wallaby-skill inspect "{path:'src/alerts.ts',location:{line:134},expression:'alerts'}"

同じ行の近くに式が複数回出現する場合は、列番号を追加して最も近い一致を選択します。

npx wallaby-skill inspect "{path:'src/alerts.ts',location:{line:134,column:10},expression:'alerts'}"

メインレポートに、名前が一致するテストで生成された値のみを表示するには、完全なテスト名またはその一部を指定して --test を渡します。

npx wallaby-skill inspect "{path:'src/alerts.ts',location:{line:134},expression:'alerts'}" --test "alerts output / combined conditions"

以前に取得したすべての実行時の値をクリアするには、--clear を渡します。

npx wallaby-skill inspect "{path:'src/alerts.ts',location:{line:134},expression:'alerts'}" --clear # clears all captured runtime values and adds new inspection
npx wallaby-skill inspect --clear # clears all captured runtime values

検査対象を指定せずに --clear を使うと、コマンドは Markdown レポートの代わりに Cleared all captured runtime values. と表示します。

それ以外の場合、コマンドは Markdown レポートを出力し、同じ内容を inspect.md として保存します。通常、ゼロ以外の終了コードは、レポートに失敗したテストまたはエラーが含まれていることを意味しますが、CLI 自体または Wallaby 自体の失敗を意味する場合もあります。

• Status、Mode、および Fatal Error や Global Errors は、run コマンドのレポートと同じ意味です。
• Runtime Values には、取得された値がソースファイル、行、式、整形済みの値、および各値を生成したテストとともに表示されます。要求された検査を取得できなかった場合は、パス、式、場所、理由を含む警告も表示されます。追加の値が省略されている場合は、ランタイム値の完全なレポートへのリンクが表示されます。ランタイム値の完全なレポート形式が必要な場合は、references/runtime-values.md を参照してください。
• --test を使用すると、メインレポートではテスト名でランタイム値が絞り込まれ、ほかの値がある場合は、フィルターが適用されていない完全なレポートへのリンクが表示されます。未取得の検査に関する警告は引き続き表示されます。これは、特定のテストで取得された値ではなく、要求された検査場所を示すためです。
• Run Report は、同じセッション状態から広範な診断を確認できる、run コマンドのレポートと同じ形式のレポートにリンクします。

Runtime Values から src/alerts.ts の取得済みの値をすべて見つけるには：

rg -U --pcre2 -o '(?sm)^## src/alerts\.ts[^\n]*\n.*?(?=^## |\z)' runtime-values.md

名前に combined conditions を含むテストによって生成されたランタイム値をすべて見つけるには：

rg -U --pcre2 -o '(?sm)^## [^\n]*\n.*?^- name: .*combined conditions.*\n.*?(?=^## |\z)' runtime-values.md

Stop command

最初の run の後、Wallaby はバックグラウンドで実行され続け、プロジェクトファイルを監視して、以降のコマンドで使用できるライブテスト状態を保持します。通常の run、analyze、inspect の呼び出しの間に停止しないでください。自動シャットダウンが利用可能な場合、検出されたエージェントプロセスが終了すると Wallaby は停止します。また、CLI の操作がない状態が一定時間続くと停止します。エージェントプロセスが検出された場合は 20 分、対応するエージェントプロセスが見つからない場合は 5 分です。

実行中のプロセスを入れ替える、またはリソースを解放する必要がある場合は、明示的に stop を使用してください。

• Node モジュールをインストール、更新、削除する前に Wallaby を停止し、依存関係を変更してから run で再起動してください。Wallaby は node_modules 内の変更を監視しないため、既存のプロセスでは更新された依存関係を確実に使用できません。
• 別の Wallaby 設定またはランタイム環境で再起動する前に、既存のセッションを停止してください。
• ユーザーから要求された場合、クリーンな再起動が必要な場合、または自動シャットダウン前に実行中のプロセスがリソースを解放する必要がある場合は、直ちに停止してください。

stop は、セッションがプロジェクトモードか排他モードかにかかわらず、run と同じプロジェクト ID を使用します。run と同じ作業ディレクトリから呼び出すか、同じ --config の値を指定してください。設定を切り替えるときは、新しい設定で開始する前に、既存のプロジェクト ID を使って古いセッションを停止してください。

npx wallaby-skill stop # stops the session identified by the current working directory
npx wallaby-skill stop --config ./wallaby.js # stops the session identified by this Wallaby configuration file

Update command

run で Wallaby Core との互換性エラーが報告された場合は、Core を更新してから、同じ run コマンドを再試行してください。

npx wallaby-skill update