{"meta":{"title":"测试运行","intro":"针对 QL 查询运行单元测试。","product":"安全性和代码质量","breadcrumbs":[{"href":"/zh/enterprise-server@3.20/code-security","title":"安全性和代码质量"},{"href":"/zh/enterprise-server@3.20/code-security/reference","title":"Reference"},{"href":"/zh/enterprise-server@3.20/code-security/reference/code-scanning","title":"代码扫描"},{"href":"/zh/enterprise-server@3.20/code-security/reference/code-scanning/codeql","title":"CodeQL"},{"href":"/zh/enterprise-server@3.20/code-security/reference/code-scanning/codeql/codeql-cli-manual","title":"CodeQL CLI 手册"},{"href":"/zh/enterprise-server@3.20/code-security/reference/code-scanning/codeql/codeql-cli-manual/test-run","title":"测试运行"}],"documentType":"article"},"body":"# 测试运行\n\n针对 QL 查询运行单元测试。\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\n针对 QL 查询运行单元测试。\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\n `json`：测试结果对象的流式 JSON 数组。\n\n `betterjson`：事件对象的流式 JSON 数组。\n\n `jsonz`：零终止的 JSON 测试结果对象流。\n\n `betterjsonz`：零终止的 JSON 事件对象流。\n```\n\n对于 `betterjson` 和 `betterjsonz` 格式，每个事件都有一个 `type` 属性，用于指定事件的类型。 将来可能会添加新的事件类型，因此使用者应忽略具有无法识别的 `kind` 属性的任何事件。\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 \\[高级] 包含将为每个测试数据库运行的一致性查询的目录。 这些查询不应生成任何输出（它们发现问题的情况除外），除非测试目录包含带有 `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在其 `qlpack.yml` 声明 `tests` 目录的 QL 包中，该目录中的所有 `.ql` 文件都被视为测试，其外部的 `.ql` 文件会被忽略。 在未声明 `tests` 目录的 QL 包中，`.ql` 文件仅在具有相应的 `.expected` 文件时才会被标识为测试。\n\n为了保持一致性，`.qlref` 文件受到与 `.ql` 文件相同的规则限制，即使 `.qlref` 文件实际上不能是“非测试”也是如此。\n\n### 用于查找测试使用的库和提取程序的选项\n\n#### `--search-path=[:...]`\n\n可在其中找到 QL 包的目录列表。 每个目录可以是一个 QL 包（或在根目录下包含一个 `.codeqlmanifest.json` 文件的多个包），也可以是一个或多个此类目录的直接父目录。\n\n如果路径包含多个目录，则它们的顺序定义了它们之间的优先级：当必须解析的包名称在多个目录树中匹配时，给定的第一个目录树优先。\n\n在查询其中一种语言时，将其指向开源 CodeQL 存储库的签出应该是可行的。\n\n如果已将 CodeQL 存储库签出为未打包的 CodeQL 工具链的同级，则无需提供此选项；将始终在此类同级目录中搜索以其他方式找不到的 QL 包。 （如果此默认值不起作用，强烈建议在每用户配置文件中一次性设置 `--search-path`）。\n\n（注意：在 Windows 上，路径分隔符为 `;`）。\n\n#### `--additional-packs=[:...]`\n\n如果给定了此目录列表，则先在这些目录中的搜索包，然后在 `--search-path` 中的目录搜索包。 它们之间的顺序并不重要；如果在此列表的两个不同位置发现同一个包名称，这是一个错误。\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通过传递逗号分隔的 \\=\\ 对列表，向 GitHub Enterprise Server 容器注册表进行身份验证。\n\n例如，可以传递 `https://containers.GHEHOSTNAME1/v2/=TOKEN1,https://containers.GHEHOSTNAME2/v2/=TOKEN2`\n向两个 GitHub Enterprise Server 实例进行身份验证。\n\n这会替代 CODEQL\\_REGISTRIES\\_AUTH and GITHUB\\_TOKEN 环境变量。 如果只需向 github.com 容器注册表进行身份验证，则可以改用更简单的 `--github-auth-stdin` 选项进行身份验证。\n\n#### `--github-auth-stdin`\n\n通过标准输入传递 github.com GitHub 应用令牌或个人访问令牌，对 github.com 容器注册表进行身份验证。\n\n要向 GitHub Enterprise Server 容器注册表进行身份验证，请传递 `--registries-auth-stdin` 或使用 CODEQL\\_REGISTRIES\\_AUTH 环境变量。\n\n这会替代 GITHUB\\_TOKEN 环境变量。\n\n### 用于控制查询编译的选项\n\n#### `--no-release-compatibility`\n\n```\n \\[高级] 使用最新的编译器功能，但会牺牲可移植性。\n```\n\nQL 评估器的部分版本将时不时支持新的 QL 语言功能和计算器优化并会在 QL 编译器中默认启用它们。 这有助于确保你在最新的 CodeQL 版本中开发查询时体验到的性能可以与代码扫描或 CI 集成中可能仍在使用的稍旧版本相匹配。\n\n如果你不关心查询是否与其他 CodeQL 版本（更低版本或更高版本）兼容，有时可以通过使用此标志提前在编译器中启用最新改进来实现少量的额外性能。\n\n如果版本中最近没有要启用的改进，此选项以无提示方式不执行任何操作。 因此，可以安全地在全局 CodeQL 配置文件中一劳永逸地设置它。\n\n自 `v2.11.1` 起可用。\n\n### 用于控制测试查询评估的选项\n\n#### `--[no-]tuple-counting`\n\n```\n \\[高级] 在查询计算器日志中显示每个评估步骤的元组计数。 如果提供了 `--evaluator-log` 选项，则元组计数将包含在命令生成的基于文本的 JSON 日志和结构化 JSON 日志中。 （这对复杂 QL 代码的性能优化非常有用）。\n```\n\n#### `--timeout=`\n\n```\n \\[高级] 设置查询评估的超时时间（以秒为单位）。\n```\n\n超时功能旨在捕获复杂查询需要“长久时间”来评估的情况。 这不是限制查询评估可花费的总时间的有效方法。 只要计算的每个单独计时部分在超时时间内完成，就允许评估继续进行。 目前，这些单独计时部分是已优化查询的“RA 层”，但将来可能会变化。\n\n如果未指定超时或将其指定为 0，则不会设置超时（codeql test run 除外，默认超时为 5 分钟）。\n\n#### `-j, --threads=`\n\n使用如此多的线程来评估查询。\n\n默认值为 1。 可以传递 0 以在机器上每个内核使用一个线程，或传递 -*N* 以保留 *N* 个内核不使用（但仍至少使用一个线程）。\n\n### 用于控制结构化计算器日志输出的选项\n\n#### `--evaluator-log=`\n\n```\n \\[高级] 将有关计算器性能的结构化日志输出到指定文件。 此日志文件的格式可能会更改，恕不通知，但是它将是一连串用两个换行符（默认）或一个换行符（通过传递了 `--evaluator-log-minify` 选项）分隔的 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 \\[高级] 如果 TRAP 导入期间发生错误，退出时返回非零代码。\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 dataset import](/code-security/reference/code-scanning/codeql/codeql-cli-manual/dataset-import) 是否支持链接 _（默认）_。 对于在数据库创建这一部分占用过多内存的项目，禁用此选项可能有助于其运行，但会牺牲数据库的完整性。\n```\n\n自 `v2.15.3` 起可用。\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+++ 之一。 重写 `-v` 和 `-q`。\n```\n\n#### `--logdir=`\n\n```\n \\[高级] 将详细日志写入指定目录中的一个或多个文件，生成的文件名包含时间戳和正在运行的子命令名称。\n```\n\n（要使用可以完全控制的名称编写日志文件，请根据需要提供 `--log-to-stderr` 并重定向 stderr。）\n\n#### `--common-caches=`\n\n```\n \\[高级] 控制磁盘上缓存数据的位置，这些数据将在 CLI 的多次运行之间保留，例如下载的 QL 包和编译的查询计划。 如果未明确设置，则默认为用户主目录中名为 `.codeql` 的目录；如果尚不存在，则会创建该目录。\n```\n\n自 `v2.15.2` 起可用。"}