Skip to main content

テストの実行

QL クエリの単体テストを実行します。

この機能を使用できるユーザーについて

CodeQL は、次の種類のリポジトリで使用できます:

この記事の内容

このコンテンツでは、CodeQL CLI の最新リリースについて説明します。 このリリースについて詳しくは、 https://github.com/github/codeql-cli-binaries/releases をご覧ください。

以前のリリースの、このコマンドで使えるオプションを詳しく確認するには、ターミナルで --help オプションを指定してコマンドを実行してください。

構文

Shell
codeql test run [--threads=<num>] [--ram=<MB>] <options>... -- <test|dir>...

説明

QL クエリの単体テストを実行します。

[オプション]

主なオプション

<test|dir>...

各引数は、次のいずれかです。

  • 実行するテストを定義する .ql または .qlref ファイル。
  • 実行するテストを再帰的に検索するディレクトリ。

--failing-exitcode=<code>

[詳細設定] エラーが発生した場合に生成する終了コードを設定します。 通常は 1 ですが、出力を解析するツールでは、0 に設定すると有用な場合があります。

--format=<fmt>

出力形式を選択します。 可能な選択肢:

text (既定値): 人間が判読できるテキスト レンダリング。__

json: テスト結果オブジェクトのストリーミングされた JSON 配列。

betterjson: イベント オブジェクトのストリーミングされた JSON 配列。

jsonz: ゼロ終端の JSON テスト結果オブジェクトのストリーム。

betterjsonz: ゼロ終端の JSON イベント オブジェクトのストリーム。

betterjson 形式と betterjsonz 形式の場合、各イベントには、イベントの種類を指定する type プロパティがあります。 将来的に新しいイベントの種類が追加される可能性があるため、コンシューマーは認識できない kind プロパティを持つイベントを無視する必要があります。

--[no-]keep-databases

[詳細設定] ディレクトリ内のすべてのテストに合格した場合でも、テスト クエリを実行するために抽出されたデータベースを保持します ("失敗" したテストがある場合、データベースは常に存在したままになります)。__

--[no-]fast-compilation

[非推奨] [詳細設定] テスト クエリをコンパイルするときに、特に速度の遅い最適化手順を省略します。

--[no-]learn

[詳細設定] テストで予期しない出力が生成された場合、失敗する代わりに、.expected ファイルを更新して実際の出力と一致させ、合格するようにします。 このモードでもテストは失敗する可能性があります。たとえば、クエリを実行するテスト データベースの作成に失敗する場合などです。

--consistency-queries=<dir>

[詳細設定] 各テスト データベースに対して実行される整合性クエリを含むディレクトリ。 .expected ファイルを含む CONSISTENCY サブディレクトリがテスト ディレクトリに含まれていない限り、これらのクエリでは出力は生成されません (問題が見つかった場合を除きます)。 これは、主に抽出子のテストに役立ちます。

--[no-]check-databases

[詳細設定] 作成された各テスト データベースに対して codeql dataset check を実行し、矛盾が検出された場合は失敗を報告します。 これは、抽出子のテストに役立ちます。 特定のデータベースでチェックが (一時的に) 失敗することが予想される場合は、テスト ディレクトリに DB-CHECK.expected ファイルを配置してください。

--[no-]show-extractor-output

[詳細設定] テスト データベースを作成する抽出スクリプトからの出力を表示します。 これは、テスト ケースの開発または編集時に役立つ場合があります。 複数のスレッドでこれを使用する場合は、重複した出力や形式が正しくない出力が生成される可能性があります。

-M, --ram=<MB>

テスト ランナーで使用できる必要がある RAM の合計量を設定します。

--slice=<N/M>

[詳細設定] テスト ケースをほぼ同じサイズの M 個のスライスに分割し、そのうちの N 番目のみを処理します。 これは、テスト プロセスの手動による並列化に使用できます。

--[no-]strict-test-discovery

[詳細設定] テストとして明確に識別できるクエリのみを使用します。 このモードでは、単体テストを定義する .ql ファイルと、有用なクエリを意図した .ql ファイルを区別しようとします。 このオプションは、ディレクトリ ツリー内のファイルがどのように配置されているかが事前にわからなくても、ディレクトリ ツリー内のすべての単体テストを識別する必要がある IDE などのツールで使用されます。

qlpack.ymltests ディレクトリを宣言する QL パック内では、そのディレクトリ内のすべての .ql ファイルがテストと見なされ、そのディレクトリの外部にある .ql ファイルは無視されます。 tests ディレクトリを宣言しない QL パックでは、対応する .expected ファイルがある場合にのみ、.ql ファイルがテストとして識別されます。

一貫性を保つために、.qlref ファイルが実際にはテストではないファイルにできない場合でも、.qlref ファイルは .ql ファイルと同じ規則によって制限されます。

テストで使用されるライブラリと抽出子を検出するためのオプション

--search-path=<dir>[:<dir>...]

QL パックが見つかる可能性があるディレクトリの一覧。 各ディレクトリは、QL パック (またはルートに .codeqlmanifest.json ファイルを含むパックのバンドル)、または 1 つ以上のこのようなディレクトリの直接の親ディレクトリのいずれかです。

パスに複数のディレクトリを含める場合は、それらの順序で、それらの間の優先順位を定義します。解決する必要があるパック名が複数のディレクトリ ツリーで一致する場合は、最初に指定したものが優先されます。

オープンソースの CodeQL リポジトリのチェックアウトでこれを指定すると、そこにある言語の 1 つを照会するときに機能するはずです。

CodeQL リポジトリを、アンパックされた CodeQL ツールチェーンの兄弟としてチェックアウトしている場合、このオプションを指定する必要はありません。このような兄弟ディレクトリは、他の方法では見つからない QL パックについて常に検索されます (このデフォルトが機能しない場合は、ユーザーごとの構成ファイルで --search-path を一度だけ設定することを強くお勧めします)。

(注: Windows では、パスの区切り記号は ; です)。

--additional-packs=<dir>[:<dir>...]

このディレクトリ リストを指定した場合、ディレクトリは、--search-path で指定したものより前に、パックについて検索されます。 これらの間の順序は重要ではありません。このリストの 2 か所でパック名が見つかった場合は、エラーです。

これは、デフォルトのパスにも表示される新しいバージョンのパックを一時的に開発している場合に役立ちます。 一方、構成ファイルでこのオプションをオーバーライドすることは "お勧めしません"。内部アクションによっては、このオプションがオンザフライで追加され、構成済みの値がオーバーライドされます。__

(注: Windows では、パスの区切り記号は ; です)。

--library-path=<dir>[:<dir>...]

[詳細設定] QL ライブラリの生インポート検索パスに追加するオプションのディレクトリ リスト。 これを使う必要があるのは、QL パックとしてパッケージ化されていない QL ライブラリを使用する場合のみです。

(注: Windows では、パスの区切り記号は ; です)。

--dbscheme=<file>

[詳細設定] どの dbscheme クエリに対してコンパイルする必要があるかを明示的に定義します。 これは、自分が何をしているかを確信している呼び出し元のみが指定する必要があります。

--compilation-cache=<dir>

[詳細設定] コンパイル キャッシュとして使用する追加のディレクトリを指定します。

--no-default-compilation-cache

[詳細設定] クエリを含む QL パックや CodeQL ツールチェーン ディレクトリなどの標準の場所でコンパイル キャッシュを使用しません。

CodeQL パッケージ マネージャーを構成するためのオプション

--registries-auth-stdin

<registry_url>=<token> ペアのコンマ区切りのリストを渡して、GitHub Enterprise Server コンテナー レジストリに対して認証を行います。

たとえば、https://containers.GHEHOSTNAME1/v2/=TOKEN1,https://containers.GHEHOSTNAME2/v2/=TOKEN2 を渡して、 2 つの GitHub Enterprise Server インスタンスに対して認証を行うことができます。

これを使って、CODEQL_REGISTRIES_AUTH および GITHUB_TOKEN 環境変数をオーバーライドします。 github.com コンテナー レジストリに対する認証のみが必要な場合は、代わりに、より単純な --github-auth-stdin オプションを使って認証できます。

--github-auth-stdin

標準入力を介して github.com GitHub Apps トークンまたは個人用アクセス トークンを渡して、github.com コンテナー レジストリに対して認証を行います。

GitHub Enterprise Server コンテナー レジストリに対して認証を行うには、--registries-auth-stdin を渡すか、CODEQL_REGISTRIES_AUTH 環境変数を使います。

これは、GITHUB_TOKEN 環境変数をオーバーライドします。

クエリ コンパイルを制御するためのオプション

--no-release-compatibility

[詳細設定] 移植性を犠牲にして、最新のコンパイラ機能を使用します。

場合によっては、新しい QL 言語機能とエバリュエーターの最適化が、それらが QL コンパイラにおいてデフォルトで有効になる数リリース前に、QL エバリュエーターによってサポートされます。 これにより、最新の CodeQL リリースでクエリを開発するときに生じるパフォーマンスを、コード スキャンまたは CI 統合にまだ使用されている可能性がある少し古いリリースと一致させることができます。

クエリが他の (以前または以降の) CodeQL リリースと互換性があるかどうかを気にする必要がない場合は、このフラグを使用してコンパイラの最近の改善を早期に有効にすることで、パフォーマンスを多少向上させることができます。

リリースに有効にすべき最近の改善がない場合、このオプションは通知することなく何も実行しません。 このため、グローバル CodeQL 構成ファイルで一度にすべて設定しても安全です。

v2.11.1 以降で使用できます。

テスト クエリの評価を制御するオプション

--[no-]tuple-counting

[詳細設定] クエリ エバリュエーター ログの各評価ステップのタプル数を表示します。 --evaluator-log オプションを指定すると、コマンドで生成されるテキストベースのログと構造化された JSON ログの両方にタプル数が含まれます (これは、複雑な QL コードのパフォーマンス最適化に役立ちます)。

--timeout=<seconds>

[詳細設定] クエリ評価のタイムアウトの長さを秒単位で設定します。

タイムアウト機能は、複雑なクエリの評価に "かなり長い時間" がかかるケースを検出することを目的としています。 クエリの評価にかかる合計時間を制限するのは効果的な方法ではありません。 評価は、計算の個別に時間指定された各部分がタイムアウト内に完了する限り続行できます。 現在、これらの個別に時間指定された部分は、最適化されたクエリの "RA レイヤー" ですが、将来変更される可能性があります。

タイムアウトが指定されていない場合、またはタイムアウトに 0 が指定されている場合、タイムアウトは設定されません (デフォルトのタイムアウトが 5 分である codeql test run を除きます)。

-j, --threads=<num>

この数のスレッドをクエリの評価に使用します。

デフォルト値は 1 です。 0 を渡して、コンピューター上のコアごとに 1 つのスレッドを使用したり、N を渡して、N 個のコアを未使用のままにしたりすることができます (ただし、その場合でも、少なくとも 1 つのスレッドが使用されます)。

エバリュエーターに関する構造化ログの出力を制御するためのオプション

--evaluator-log=<file>

[詳細設定] 指定されたファイルにエバリュエーターのパフォーマンスに関する構造化ログを出力します。 このログ ファイルの形式は、予告なく変更される場合がありますが、2 つの改行文字 (デフォルト) または --evaluator-log-minify オプションが渡された場合は 1 つの改行文字で区切られた JSON オブジェクトのストリームになります。 このファイルのより安定した概要を生成するために codeql generate log-summary <file> を使用し、ファイルを直接解析しないようにしてください。 ファイルが既に存在している場合は上書きされます。

--evaluator-log-minify

[詳細設定] --evaluator-log オプションが渡された場合、このオプションも渡されると、生成される JSON ログのサイズは最小限に抑えられますが、人間が判読しにくいものになります。

インポートされた TRAP をチェックするためのオプション

--[no-]check-undefined-labels

[詳細設定] 未定義のラベルのエラーを報告します。

--[no-]check-unused-labels

[詳細設定] 未使用のラベルのエラーを報告します。

--[no-]check-repeated-labels

[詳細設定] 繰り返しラベルのエラーを報告します。

--[no-]check-redefined-labels

[詳細設定] 再定義されたラベルのエラーを報告します。

--[no-]check-use-before-definition

[詳細設定] 定義される前に使われたラベルのエラーを報告します。

--[no-]fail-on-trap-errors

[詳細設定] トラップのインポート中にエラーが発生した場合、0 以外で終了します。

--[no-]include-location-in-star

[詳細設定] 元の TRAP ファイル内の場所をエンコードするエンティティ ID を構築します。 TRAP ジェネレーターのデバッグに役立つ場合がありますが、データセット内で多くの領域を占有します。

--[no-]linkage-aware-import

[詳細設定] codeql データセットのインポートがリンケージ対応 (既定) かどうかを制御します。 データベース作成のこの部分で消費されるメモリが多すぎるプロジェクトでは、このオプションを無効にすると、データベースの完全性が犠牲になりますが、進行しやすくなる場合があります。

v2.15.3 以降で使用できます。

共通オプション

-h, --help

このヘルプ テキストを表示します。

-J=<opt>

[詳細設定] コマンドを実行している JVM にオプションを指定します

(スペースを含むオプションは正しく処理されないことに注意してください)。

-v, --verbose

出力される進行状況メッセージの数を段階的に増やします。

-q, --quiet

出力される進行状況メッセージの数を段階的に減らします。

--verbosity=<level>

[詳細設定] 詳細レベルを、errors、warnings、progress、progress+、progress++、progress+++ のいずれかに明示的に設定します。 -v-q がオーバーライドされます。

--logdir=<dir>

[詳細設定] タイムスタンプと実行中のサブコマンドの名前を含む生成された名前を使用して、指定されたディレクトリ内の 1 つまたは複数のファイルに詳細なログを書き込みます

(完全に制御できる名前でログ ファイルを書き込むには、代わりに --log-to-stderr を指定し、必要に応じて stderr をリダイレクトします)。

--common-caches=<dir>

[[詳細設定] ダウンロードした QL パックやコンパイル済みクエリ プランなど、CLI の複数の実行間に保持される、ディスク上でキャッシュされたデータの場所を制御します。 明示的に設定されない場合、デフォルトではユーザーのホーム ディレクトリに名前が付けられた .codeql ディレクトリになります。まだ存在しない場合は作成されます。

v2.15.2 以降で使用できます。