bencher run CLI 子命令
bencher run
是最受欢迎的 CLI 子命令。
它被用来运行基准测试并报告结果。
因此,它是最复杂的子命令之一。
本页面将解释可以传递给 bencher run
的选项,标志和参数。
基准命令
bencher run
的第一个参数是可选的基准命令。
这是将被执行的命令,用以调用您的基准测试环节。
也可以通过设置 BENCHER_CMD
环境变量来指定。
默认情况下,这个命令在一个 shell 中执行,
可以通过 --shell
和 --flag
选项来配置。
其输出由一个 基准测试适配器 解析,
可以使用 --adapter
选项来设置。
然而,如果基准测试装置输出到一个文件,则必须同时使用 --file
选项
来指定输出文件路径。
如果您希望跟踪输出文件的大小(即二进制大小)而不是其内容,
则使用 --file-size
选项来指定输出文件路径。
如果您更希望不在 shell 中执行命令,您可以使用 --exec
标志,或者简单地将额外的命令参数作为 bencher run
的附加参数提供。
Shell 表单:
Exec 表单:
使用 --iter
选项,可以多次运行基准命令,
并且可以使用 --fold
选项将这些结果折叠成一个结果。
如果任何迭代失败,则除非设置了 --allow-failure
标志,
整个命令都被视为失败。
如果没有指定基准命令但指定了 --file
选项,
那么 bencher run
将只读取指定的输出文件路径。
类似地,如果没有指定基准命令但指定了 --file-size
选项,
那么 bencher run
将只读取给定文件路径处文件的大小。
如果没有指定基准命令、--file
选项
或 --file-size
选项,
那么 bencher run
将改为从 stdin
读取。
这允许您将另一个命令的输出保存到文件中或者管道传输到 bencher run
。
选项
--project <项目>
必须设置 --project
选项或 BENCHER_PROJECT
环境变量
为已经存在的项目的 slug 或 UUID。
如果两者都被定义,--project
选项优先于 BENCHER_PROJECT
环境变量。
--token <令牌>
必须设置 --token
选项或 BENCHER_API_TOKEN
环境变量为有效的 API 令牌。
如果两者都被定义,--token
选项优先于 BENCHER_API_TOKEN
环境变量。
--branch <BRANCH>
--branch-start-point <BRANCH>
--branch-start-point-hash <HASH>
--branch-reset
请参阅 分支选择 以获取完整的概述。
--hash <HASH>
可选:40个字符的 SHA-1 提交哈希值。 如果两个报告具有相同的分支和哈希,他们将被认为是来自同一次提交。 因此,他们将有相同的分支版本号。
如果未提供,Bencher CLI会尝试查找当前的git哈希。 它首先在当前工作目录中寻找git仓库。 如果查找不成功,它会继续在其父目录中查找,并一直重试到根目录。 如果找到了git仓库,那么将会使用当前分支的HEAD git哈希。
--no-hash
可选项:不尝试寻找 git
提交哈希。
此选项与 --hash
冲突,
并覆盖其默认行为,即搜索 git
仓库。
--testbed <测试环境>
可选:可以设置 --testbed
选项或 BENCHER_TESTBED
环境变量
为已经存在的测试环境的 slug 或 UUID。
如果两者都被定义,--testbed
选项优先于 BENCHER_TESTBED
环境变量。
如果两者都未定义,则使用 localhost
作为默认测试环境。
--adapter <ADAPTER>
--average <AVERAGE>
--file <FILE>
--file-size <FILE>
请参阅 基准测试工具适配器 以获取完整的概述。
--iter <迭代次数>
可选:运行迭代的次数。默认为 1
。
--fold <合并>
可选:把多个结果合并为一个结果,需要设置 --iter
选项。
可能的值为:
min
: 最小值max
: 最大值mean
: 值的平均数median
: 值的中位数
--backdate <返回日期时间_秒>
可选:将报告的日期时间回溯(自纪元以来的秒数)。 注:这将不会影响过去报告的顺序! 在_按时间顺序_将历史数据初始化到项目中时,这非常有用。
--allow-failure
可选:允许基准测试失败。
--err
可选:当生成警报时报错。请参阅 阈值和警报 以获取完整的概述。
--html
可选:以 HTML 格式输出结果。
--quiet
可选:安静模式,只输出最终的报告 JSON。默认为false
。
--github-actions <GITHUB_TOKEN>
可选:设置 GitHub API 验证令牌 (即 --github-actions ${{ secrets.GITHUB_TOKEN }}
)。
当此选项被设置并且 bencher run
在一个的拉请求中作为 GitHub 操作的一部分被使用时,
那么结果将以评论的形式添加到拉请求中。
这样做最方便的方式是 GitHub 操作的 GITHUB_TOKEN
环境变量。
🐰 如果你在 GitHub 操作中的 Docker 容器内运行,你将需要传入以下环境变量,并挂载由
GITHUB_EVENT_PATH
指定的路径:
GITHUB_ACTIONS
GITHUB_EVENT_NAME
GITHUB_EVENT_PATH
--ci-only-thresholds
可选:只有在 一个阈值 存在于度量标准种类,分支和测试环境时,才将结果提交到 CI。
如果没有阈值存在,那么什么也不会被提交。
需要:--github-actions
--ci-only-on-alert
可选:只有在 一个警报 生成时,才开始将结果提交到 CI。
如果生成了一个警报,那么后续的结果,即使它们不包含任何警报,也会被提交。
需要:--github-actions
--ci-id
可选:自定义 ID 用于将结果提交到 CI。
默认情况下,Bencher 将自动按组合:项目,分支,测试环境,和 适配器 段出结果。
在 Bencher 被多次在同一个 CI 工作流中针对同一个项目,分支,测试环境,和适配器组合运行时,设置自定义 ID 很有用。
需要:--github-actions
--ci-number
可选:将结果提交到 CI 的问题编号。
Bencher 将尽最大努力检测出需要提交结果的 CI 问题编号。
然而,这并不总是可用的,在复杂的设置中,像在 GitHub 执行 workflow_run
。
需要:--github-actions
--shell <SHELL>
可选:Shell 命令路径。在类 Unix 环境中默认为 /bin/sh
,在 Windows 上默认为 cmd
。
--flag <标志>
可选:Shell 命令标志。在类 Unix 环境中默认为 -c
,在 Windows 上默认为 /C
。
--exec
可选项:作为一个可执行命令而不是shell命令运行。
如果 bencher run
的参数数量大于一,则默认执行此操作。
--host <主机>
可选:后端主机 URL。默认为 https://api.bencher.dev。
--attempts <尝试次数>
可选:最大请求重试次数。默认为 10
。
--retry-after <重试延迟>
可选:在给定的秒数后重试请求 (指数退避)。默认为 1
。
--dry-run
可选:执行一次干运行。这不会将任何数据存储到后端。 在 分支选择 中详述的报告或分支都不会被创建。
-h
--help
可选:打印帮助。
🐰 恭喜!你已经学会了
bencher run
的基础知识!🎉