{"meta":{"title":"テストの実行","intro":"QL クエリの単体テストを実行します。","product":"セキュリティとコードの品質","breadcrumbs":[{"href":"/ja/enterprise-cloud@latest/code-security","title":"セキュリティとコードの品質"},{"href":"/ja/enterprise-cloud@latest/code-security/reference","title":"リファレンス"},{"href":"/ja/enterprise-cloud@latest/code-security/reference/code-scanning","title":"コードスキャン"},{"href":"/ja/enterprise-cloud@latest/code-security/reference/code-scanning/codeql","title":"CodeQL"},{"href":"/ja/enterprise-cloud@latest/code-security/reference/code-scanning/codeql/codeql-cli-manual","title":"CodeQL CLI のマニュアル"},{"href":"/ja/enterprise-cloud@latest/code-security/reference/code-scanning/codeql/codeql-cli-manual/test-run","title":"テストの実行"}],"documentType":"article"},"body":"# テストの実行\n\nQL クエリの単体テストを実行します。\n\n> \\[!NOTE]\n> このコンテンツでは、CodeQL CLI の最新リリースについて説明します。このリリースについて詳しくは、をご覧ください。\n>\n> 以前のリリースの、このコマンドで使えるオプションを詳しく確認するには、ターミナルで `--help` オプションを指定してコマンドを実行してください。\n\n## 概要\n\n```shell copy\ncodeql test run [--threads=] [--ram=] ... -- ...\n```\n\n## Description\n\nQL クエリの単体テストを実行します。\n\n## オプション\n\n### 主なオプション\n\n#### `...`\n\n各引数は、次のいずれかです。\n\n* 実行するテストを定義する `.ql` または `.qlref` ファイル。\n* 実行するテストを再帰的に検索するディレクトリ。\n\n#### `--failing-exitcode=

`\n\n```\n          \\[詳細設定] エラーが発生した場合に生成する終了コードを設定します。 通常は 1 ですが、出力を解析するツールでは、0 に設定すると有用な場合があります。\n```\n\n#### `--format=`\n\n出力形式を選びます。 可能な選択肢:\n\n```\n          `text` (既定値): 人間が判読できるテキスト レンダリング。__\n\n          `json`: テスト結果オブジェクトのストリーミングされた JSON 配列。\n\n          `betterjson`: イベント オブジェクトのストリーミングされた JSON 配列。\n\n          `jsonz`: ゼロ終端の JSON テスト結果オブジェクトのストリーム。\n\n          `betterjsonz`: ゼロ終端の JSON イベント オブジェクトのストリーム。\n\n          `betterjson` 形式と `betterjsonz` 形式の場合、各イベントには、イベントの種類を指定する `type` プロパティがあります。 将来的に新しいイベントの種類が追加される可能性があるため、コンシューマーは認識できない `kind` プロパティを持つイベントを無視する必要があります。\n```\n\n#### `--[no-]keep-databases`\n\n```\n          \\[詳細設定] ディレクトリ内のすべてのテストに合格した場合でも、テスト クエリを実行するために抽出されたデータベースを保持します (\"失敗\" したテストがある場合、データベースは常に存在したままになります)。__\n```\n\n#### `--[no-]fast-compilation`\n\n```\n          \\[非推奨] \\[詳細設定] テスト クエリをコンパイルするときに、特に速度の遅い最適化手順を省略します。\n```\n\n#### `--[no-]learn`\n\n```\n          \\[詳細設定] テストで予期しない出力が生成された場合、失敗する代わりに、`.expected` ファイルを更新して実際の出力と一致させ、合格するようにします。 このモードでもテストは失敗する可能性があります。たとえば、クエリを実行するテスト データベースの作成に失敗する場合などです。\n```\n\n#### `--consistency-queries=`\n\n```\n          \\[詳細設定] 各テスト データベースに対して実行される整合性クエリを含むディレクトリ。 \n          `CONSISTENCY` ファイルを含む `.expected` サブディレクトリがテスト ディレクトリに含まれていない限り、これらのクエリでは出力は生成されません (問題が見つかった場合を除きます)。 これは、主に抽出子のテストに役立ちます。\n```\n\n#### `--[no-]check-databases`\n\n```\n          \\[詳細設定] 作成された各テスト データベースに対して [codeql dataset check](/code-security/reference/code-scanning/codeql/codeql-cli-manual/dataset-check) を実行し、矛盾が検出された場合は失敗を報告します。 これは、抽出子のテストに役立ちます。 特定のデータベースでチェックが (一時的に) 失敗することが予想される場合は、テスト ディレクトリに `DB-CHECK.expected` ファイルを配置してください。\n```\n\n#### `--[no-]show-extractor-output`\n\n```\n          \\[詳細設定] テスト データベースを作成する抽出スクリプトからの出力を表示します。 これは、テスト ケースの開発または編集時に役立つ場合があります。\n```\n\n複数のスレッドでこれを使用すると、重複した、または形式が正しくない出力が生成される場合があることにご注意ください。\n\n#### `-M, --ram=`\n\nテスト ランナーで使用できる必要がある RAM の合計量を設定します。\n\n#### `--slice=`\n\n```\n          \\[詳細設定] テスト ケースをほぼ同じサイズの _M_ 個のスライスに分割し、そのうちの _N_th のみを処理します。 これは、テスト プロセスの手動による並列化に使用できます。\n```\n\n#### `--[no-]strict-test-discovery`\n\n```\n          \\[詳細設定] テストとして明確に識別できるクエリのみを使用します。\n```\n\nこのモードでは、単体テストを定義する `.ql` ファイルと、有用なクエリを意図した `.ql` ファイルを区別しようとします。 このオプションは、ディレクトリ ツリー内のファイルがどのように配置されているかが事前にわからなくても、ディレクトリ ツリー内のすべての単体テストを識別する必要がある IDE などのツールで使用されます。\n\n```\n          `qlpack.yml` で `tests` ディレクトリを宣言する QL パック内では、そのディレクトリ内のすべての `.ql` ファイルがテストと見なされ、そのディレクトリの外部にある `.ql` ファイルは無視されます。 \n          `tests` ディレクトリを宣言しない QL パックでは、対応する `.ql` ファイルがある場合にのみ、`.expected` ファイルがテストとして識別されます。\n```\n\n一貫性を保つために、`.qlref` ファイルが実際にはテストではないファイルにできない場合でも、`.ql` ファイルは `.qlref` ファイルと同じ規則によって制限されます。\n\n### テストで使うライブラリとエクストラクターを見つけるためのオプション\n\n#### `--search-path=[:...]`\n\nQL パックが見つかる可能性があるディレクトリの一覧。 各ディレクトリは、QL パック (またはルートに `.codeqlmanifest.json` ファイルを含むパックのバンドル)、または 1 つ以上のこのようなディレクトリの直接の親ディレクトリのいずれかです。\n\nパスに複数のディレクトリを含める場合は、それらの順序で、それらの間の優先順位を定義します。解決する必要があるパック名が複数のディレクトリ ツリーで一致する場合は、最初に指定したものが優先されます。\n\nオープンソースの CodeQL リポジトリのチェックアウトでこれを指定すると、そこにある言語の 1 つを照会するときに機能するはずです。\n\nCodeQL リポジトリを、アンパックされた CodeQL ツールチェーンの兄弟としてチェックアウトしている場合、このオプションを指定する必要はありません。このような兄弟ディレクトリは、他の方法では見つからない QL パックについて常に検索されます (このデフォルトが機能しない場合は、ユーザーごとの構成ファイルで `--search-path` を一度だけ設定することを強くお勧めします)。\n\n(注: Windows では、パスの区切り記号は `;` です)。\n\n#### `--additional-packs=[:...]`\n\nこのディレクトリの一覧が指定されている場合、パックは、`--search-path` 内のディレクトリの前に、これらのディレクトリで検索されます。 これらの間の順序は重要ではありません。このリストの 2 か所でパック名が見つかった場合は、エラーです。\n\nこれは、デフォルトのパスにも表示される新しいバージョンのパックを一時的に開発している場合に役立ちます。 一方、構成ファイルでこのオプションをオーバーライドすることは \"お勧めしません\"。内部アクションによっては、このオプションがオンザフライで追加され、構成済みの値がオーバーライドされます。\\_\\_\n\n(注: Windows では、パスの区切り記号は `;` です)。\n\n#### `--library-path=[:...]`\n\n```\n          \\[詳細設定] QL ライブラリの生インポート検索パスに追加するオプションのディレクトリ リスト。 これを使う必要があるのは、QL パックとしてパッケージ化されていない QL ライブラリを使用する場合のみです。\n```\n\n(注: Windows では、パスの区切り記号は `;` です)。\n\n#### `--dbscheme=`\n\n```\n          \\[詳細設定] どの dbscheme クエリに対してコンパイルする必要があるかを明示的に定義します。 これは、自分が何をしているかを確信している呼び出し元のみが指定する必要があります。\n```\n\n#### `--compilation-cache=`\n\n```\n          \\[詳細設定] コンパイル キャッシュとして使用する追加のディレクトリを指定します。\n```\n\n#### `--no-default-compilation-cache`\n\n```\n          \\[詳細設定] クエリを含む QL パックや CodeQL ツールチェーン ディレクトリなどの標準の場所でコンパイル キャッシュを使用しません。\n```\n\n### CodeQL パッケージ マネージャーを構成するためのオプション\n\n#### `--registries-auth-stdin`\n\n```\n          \\\n          =\n          \\ ペアのコンマ区切りのリストを渡して、GitHub Enterprise Server コンテナー レジストリに対して認証を行います。\n```\n\nたとえば、`https://containers.GHEHOSTNAME1/v2/=TOKEN1,https://containers.GHEHOSTNAME2/v2/=TOKEN2` を渡して、\n2 つの GitHub Enterprise Server インスタンスに対して認証を行うことができます。\n\nこれを使って、CODEQL\\_REGISTRIES\\_AUTH および GITHUB\\_TOKEN 環境変数をオーバーライドします。 github.com コンテナー レジストリに対する認証のみが必要な場合は、代わりに、より単純な `--github-auth-stdin` オプションを使って認証できます。\n\n#### `--github-auth-stdin`\n\n標準入力を介して github.com GitHub Apps トークンまたは個人用アクセス トークンを渡して、github.com コンテナー レジストリに対して認証を行います。\n\nGitHub Enterprise Server コンテナー レジストリに対して認証を行うには、`--registries-auth-stdin` を渡すか、CODEQL\\_REGISTRIES\\_AUTH 環境変数を使います。\n\nこれを使って、GITHUB\\_TOKEN 環境変数をオーバーライドします。\n\n### クエリ コンパイルを制御するためのオプション\n\n#### `--no-release-compatibility`\n\n```\n          \\[詳細設定] 移植性を犠牲にして、最新のコンパイラ機能を使用します。\n```\n\n場合によっては、新しい QL 言語機能とエバリュエーターの最適化が、それらが QL コンパイラにおいてデフォルトで有効になる数リリース前に、QL エバリュエーターによってサポートされます。 これにより、最新の CodeQL リリースでクエリを開発するときに生じるパフォーマンスを、コード スキャンまたは CI 統合にまだ使用されている可能性がある少し古いリリースと一致させることができます。\n\nクエリが他の (以前または以降の) CodeQL リリースと互換性があるかどうかを気にする必要がない場合は、このフラグを使用してコンパイラの最近の改善を早期に有効にすることで、パフォーマンスを多少向上させることができます。\n\nリリースに有効にすべき最近の改善がない場合、このオプションは通知することなく何も実行しません。 このため、グローバル CodeQL 構成ファイルで一度にすべて設定しても安全です。\n\n```\n          `v2.11.1` 以降で使用できます。\n```\n\n### テスト クエリの評価を制御するオプション\n\n#### `--[no-]tuple-counting`\n\n```\n          \\[詳細設定] クエリ エバリュエーター ログの各評価ステップのタプル数を表示します。 \n          `--evaluator-log` オプションを指定すると、コマンドで生成されるテキストベースのログと構造化された JSON ログの両方にタプル数が含まれます (これは、複雑な QL コードのパフォーマンス最適化に役立ちます)。\n```\n\n#### `--timeout=`\n\n```\n          \\[詳細設定] クエリ評価のタイムアウトの長さを秒単位で設定します。\n```\n\nタイムアウト機能は、複雑なクエリの評価に \"かなり長い時間\" がかかるケースを検出することを目的としています。 クエリの評価にかかる合計時間を制限するのは効果的な方法ではありません。 評価は、計算の個別に時間指定された各部分がタイムアウト内に完了する限り続行できます。 現在、これらの個別に時間指定された部分は、最適化されたクエリの \"RA レイヤー\" ですが、将来変更される可能性があります。\n\nタイムアウトが指定されていない場合、またはタイムアウトに 0 が指定されている場合、タイムアウトは設定されません (デフォルトのタイムアウトが 5 分である codeql test run を除きます)。\n\n#### `-j, --threads=`\n\nこの数のスレッドをクエリの評価に使用します。\n\n既定値は 1 です。 0 を渡して、コンピューター上のコアごとに 1 つのスレッドを使用したり、*N* を渡して、*N* 個のコアを未使用のままにしたりすることができます (ただし、その場合でも、少なくとも 1 つのスレッドが使用されます)。\n\n### エバリュエーターに関する構造化ログの出力を制御するためのオプション\n\n#### `--evaluator-log=`\n\n```\n          \\[詳細設定] 指定されたファイルにエバリュエーターのパフォーマンスに関する構造化ログを出力します。 このログ ファイルの形式は、予告なく変更される場合がありますが、2 つの改行文字 (デフォルト) または `--evaluator-log-minify` オプションが渡された場合は 1 つの改行文字で区切られた JSON オブジェクトのストリームになります。 このファイルのより安定した概要を生成するために `codeql generate log-summary ` を使用し、ファイルを直接解析しないようにしてください。 ファイルが既に存在している場合は上書きされます。\n```\n\n#### `--evaluator-log-minify`\n\n```\n          \\[詳細設定] `--evaluator-log` オプションが渡された場合、このオプションも渡されると、生成される JSON ログのサイズは最小限に抑えられますが、人間が判読しにくいものになります。\n```\n\n### インポートされた TRAP をチェックするためのオプション\n\n#### `--[no-]check-undefined-labels`\n\n```\n          \\[詳細設定] 未定義のラベルのエラーを報告します。\n```\n\n#### `--[no-]check-unused-labels`\n\n```\n          \\[詳細設定] 未使用のラベルのエラーを報告します。\n```\n\n#### `--[no-]check-repeated-labels`\n\n```\n          \\[詳細設定] 繰り返しラベルのエラーを報告します。\n```\n\n#### `--[no-]check-redefined-labels`\n\n```\n          \\[詳細設定] 再定義されたラベルのエラーを報告します。\n```\n\n#### `--[no-]check-use-before-definition`\n\n```\n          \\[詳細設定] 定義される前に使われたラベルのエラーを報告します。\n```\n\n#### `--[no-]fail-on-trap-errors`\n\n```\n          \\[詳細設定] トラップのインポート中にエラーが発生した場合、0 以外で終了します。\n```\n\n#### `--[no-]include-location-in-star`\n\n```\n          \\[詳細設定] 元の TRAP ファイル内の場所をエンコードするエンティティ ID を構築します。 TRAP ジェネレーターのデバッグに役立つ場合がありますが、データセット内で多くの領域を占有します。\n```\n\n#### `--[no-]linkage-aware-import`\n\n```\n          \\[詳細設定] [codeql データセットのインポート](/code-security/reference/code-scanning/codeql/codeql-cli-manual/dataset-import)がリンケージ対応 _(既定)_ かどうかを制御します。 データベース作成のこの部分で消費されるメモリが多すぎるプロジェクトでは、このオプションを無効にすると、データベースの完全性が犠牲になりますが、進行しやすくなる場合があります。\n\n          `v2.15.3` 以降で使用できます。\n```\n\n### 共通オプション\n\n#### `-h, --help`\n\nこのヘルプ テキストを表示します。\n\n#### `-J=`\n\n```\n          \\[詳細設定] コマンドを実行している JVM にオプションを指定します\n```\n\n(スペースを含むオプションは正しく処理されないことに注意してください)。\n\n#### `-v, --verbose`\n\n出力される進行状況メッセージの数を段階的に増やします。\n\n#### `-q, --quiet`\n\n出力される進行状況メッセージの数を段階的に減らします。\n\n#### `--verbosity=`\n\n```\n          \\[詳細設定] 詳細レベルを、errors、warnings、progress、progress+、progress++、progress+++ のいずれかに明示的に設定します。 \n          `-v` と `-q` がオーバーライドされます。\n```\n\n#### `--logdir=`\n\n```\n          \\[詳細設定] タイムスタンプと実行中のサブコマンドの名前を含む生成された名前を使用して、指定されたディレクトリ内の 1 つまたは複数のファイルに詳細なログを書き込みます\n```\n\n(完全に制御できる名前でログ ファイルを書き込むには、代わりに `--log-to-stderr` を指定し、必要に応じて stderr をリダイレクトします)。\n\n#### `--common-caches=`\n\n```\n          \\[[詳細設定] ダウンロードした QL パックやコンパイル済みクエリ プランなど、CLI の複数の実行間に保持される、ディスク上でキャッシュされたデータの場所を制御します。 明示的に設定されない場合、デフォルトではユーザーのホーム ディレクトリに名前が付けられた `.codeql` ディレクトリになります。まだ存在しない場合は作成されます。\n\n          `v2.15.2` 以降で使用できます。\n```"}