测试运行

此内容描述了 CodeQL CLI 的最新版本。有关此版本的更多信息，请参阅 https://github.com/github/codeql-cli-binaries/releases。

要在较早版本中查看此命令可用的选项的详细信息，请在终端中使用 --help 选项运行该命令。

概要

Shell

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

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）使用，这些工具需要识别目录树中的所有单元测试，而无需依赖于先前关于如何排列其中的文件的知识。

在声明了`tests`目录的`qlpack.yml`文件的QL包中，该目录下的所有`.ql`文件都被视为测试文件，目录外的`.ql`文件将被忽略。在未声明`tests`目录的QL包中，只有当`.ql`文件存在对应的`.expected`文件时，该`.ql`文件才会被识别为测试文件。

为保持一致性，即使`.qlref`文件实际上不可能是非测试文件，其也遵循与`.ql`文件相同的规则。

查找测试使用的库和提取器的选项

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

可以在其下查找QL包的目录列表。每个目录可以是一个QL包（或包含根目录下` .codeqlmanifest.json`文件的包集合），也可以是直接包含一个或多个此类目录的父目录。

如果路径包含多个目录，则它们的顺序定义了它们之间的优先级：当必须解析的包名在多个目录树中匹配时，首先给出的目录树优先。

在查询其中包含的语言之一时，将其指向开源CodeQL存储库的检出应该可以工作。

如果已将CodeQL存储库检出为解压的CodeQL工具链的同级目录，则无需提供此选项；始终会搜索此类同级目录以查找无法以其他方式找到的QL包。（如果此默认设置不起作用，强烈建议在每个用户的配置文件中设置一次`--search-path`。）

（注意：在Windows上，路径分隔符为`;`。）

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

如果提供了此目录列表，则会在`--search-path`中的目录之前搜索这些目录中的包。这些目录之间的顺序无关紧要；如果通过此列表在两个不同位置找到包名，则会发生错误。

如果您暂时正在开发一个也出现在默认路径中的新版本包，这将非常有用。另一方面，**不建议**在配置文件中覆盖此选项；某些内部操作将动态添加此选项，从而覆盖任何已配置的值。

（注意：在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`

通过传递以逗号分隔的`=`对列表来验证GitHub Enterprise Server容器注册表。

例如，您可以传递`https://containers.GHEHOSTNAME1/v2/=TOKEN1,https://containers.GHEHOSTNAME2/v2/=TOKEN2`来验证两个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评估器中默认启用之前几个版本就得到支持。这有助于确保在最新CodeQL版本中开发查询时获得的性能可以与可能仍在用于代码扫描或CI集成的稍旧版本相匹配。

如果您不关心查询与其他（较早或较晚）CodeQL版本的兼容性，则有时可以通过使用此标志尽早启用编译器中的最新改进，从而获得少量额外的性能。

在没有最新改进可启用的版本中，此选项会静默地不做任何操作。因此，可以在全局CodeQL配置文件中一次性设置它。

从`v2.11.1`版本开始可用。

控制测试查询评估的选项

`--[no-]tuple-counting`

[高级]在查询评估器日志中显示每个评估步骤的元组计数。如果提供了`--evaluator-log`选项，则元组计数将包含在命令生成的基于文本和结构化JSON日志中。（这对于复杂的QL代码的性能优化很有用。）

`--timeout=<seconds>`

[高级]设置查询评估的超时长度（以秒为单位）。

超时功能旨在捕获复杂查询需要“无限”时间才能评估的情况。它不是限制查询评估可花费的总时间的有效方法。只要计算的每个单独计时部分都在超时时间内完成，评估就可以继续进行。当前，这些单独计时的部分是优化查询的“RA层”，但这将来可能会改变。

如果没有指定超时，或指定为0，则不会设置超时（codeql test run除外，其默认超时时间为5分钟）。

谁可以使用此功能？

本文档中