buildkite/test-engine-client
GitHub: buildkite/test-engine-client
Buildkite Test Engine Client 是一款利用历史测试数据智能拆分和并行化测试套件的 CI 测试编排工具。
Stars: 24 | Forks: 15
# Buildkite Test Engine Client
Buildkite Test Engine Client (bktec) 是一个开源工具，用于编排您的测试套件。它利用您的 Buildkite Test Engine 套件数据来智能地对测试进行分区和并行化。
bktec 支持多种测试运行器，并提供各种功能来增强您的测试工作流。以下是各测试运行器支持的功能对比：
| 功能 | RSpec | Jest | Playwright | Cypress | pytest | pytest-pants | gotest | Cucumber | NUnit | 自定义测试运行器 |
| --- | :---: | :---: | :---: | :---: | :---: | :---: | :---: | :---: | :---: | :---: |
| 按文件拆分测试[^1] | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ | ✅ | ✅ | ✅ |
| [按单个测试用例拆分慢速文件](https://github.com/buildkite/test-engine-client/blob/main/docs/rspec.md#split-slow-files-by-individual-test-example) | ✅ | ❌ | ✅ | ❌ | ✅ | ❌ | ❌ | ✅ | ❌ | ❌ |
| 过滤测试文件 | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ | ✅ | ✅ | ✅ |
| 按 tag 过滤测试 | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
| 自动重试失败的测试 | ✅ | ✅ | ✅ | ❌ | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ |
| 静默测试（忽略测试失败） | ✅ | ✅ | ✅ | ❌ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| 跳过测试 | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ |
## 安装
最新版本的 bktec 可以从 https://github.com/buildkite/test-engine-client/releases 下载
### 支持的操作系统/架构
支持 linux、darwin 和 windows 的 ARM 和 AMD 架构
可用的 Go 二进制文件
- bktec-darwin-amd64
- bktec-darwin-arm64
- bktec-linux-amd64
- bktec-linux-arm64
- bktec-windows-amd64.exe
- bktec-windows-arm64.exe
## 使用 bktec
### Buildkite Pipeline 环境变量
bktec 使用以下 Buildkite Pipeline 提供的环境变量。
| 环境变量 | 描述|
| -------------------- | ----------- |
| `BUILDKITE_BUILD_ID` | Buildkite build 的 UUID。bktec 使用此 UUID 和 `BUILDKITE_STEP_ID` 来唯一标识测试计划。 |
| `BUILDKITE_JOB_ID` | Buildkite build 中 job 的 UUID。 |
| `BUILDKITE_ORGANIZATION_SLUG` | 您的 Buildkite organization 的 slug。 |
| `BUILDKITE_PARALLEL_JOB` | 由 Buildkite 并行 build 步骤创建的并行 job 的索引号。
请确保在您的 pipeline 定义中配置了 `parallelism`。您可以在此[页面](https://buildkite.com/docs/pipelines/controlling-concurrency#concurrency-and-parallelism)阅读更多关于 Buildkite 并行 build 步骤的信息。| | `BUILDKITE_PARALLEL_JOB_COUNT` | 由 Buildkite 并行 build 步骤创建的并行 job 总数。
请确保在您的 pipeline 定义中配置了 `parallelism`。您可以在此[页面](https://buildkite.com/docs/pipelines/controlling-concurrency#concurrency-and-parallelism)阅读更多关于 Buildkite 并行 build 步骤的信息。 | | `BUILDKITE_STEP_ID` | Buildkite build 中步骤组的 UUID。bktec 使用此 UUID 和 `BUILDKITE_BUILD_ID` 来唯一标识测试计划。 ### 身份验证 从 bktec 2.6.0 开始，bktec 会自动请求 [Buildkite Agent OIDC token](https://buildkite.com/docs/agent/cli/reference/oidc) 进行身份验证。您无需创建或配置 API access token。您需要[为您的 Test Engine suite 配置 OIDC 策略](https://buildkite.com/docs/pipelines/configure/tests/test-collection/oidc) 来允许此操作。 如果您运行的是 2.6.0 之前的 bktec，或者您想改用 API access token，可以在 Buildkite 的[个人设置](https://buildkite.com/user/api-access-tokens)中创建一个具有 `read_suites`、`read_test_plan` 和 `write_test_plan` scope 的 Buildkite API access token，然后设置： ``` export BUILDKITE_TEST_ENGINE_API_ACCESS_TOKEN=token ``` ### 配置 Test Engine suite slug 要使用 bktec，您需要配置 `BUILDKITE_TEST_ENGINE_SUITE_SLUG` 环境变量为您的 Test Engine suite slug。您可以在 suite 的 URL 中找到该 slug。例如，在 URL `https://buildkite.com/organizations/my-organization/analytics/suites/my-suite` 中，slug 就是 `my-suite`。 ``` export BUILDKITE_TEST_ENGINE_SUITE_SLUG=my-slug ``` ### 将测试结果上传到 Test Engine bktec 需要收集您的测试数据以启用智能测试拆分、重试和静默等功能。有两种方法可以做到这一点： **选项 1：使用 bktec 的内置上传功能（需要 bktec 2.7.0 或更高版本）** 将 `BUILDKITE_TEST_ENGINE_UPLOAD_RESULTS` 设置为 `true`： ``` export BUILDKITE_TEST_ENGINE_UPLOAD_RESULTS=true ``` 您可以使用 `--tag` 或 `BUILDKITE_TEST_ENGINE_TAGS` 为每次上传附加键/值对 tag。tag 有助于在 Test Engine 中过滤和分组测试结果。 ``` # 作为 CLI flags (repeatable) bktec run --tag env=production --tag region=us-east-1 # 作为 environment variable (comma-separated) export BUILDKITE_TEST_ENGINE_TAGS="env=production,region=us-east-1" ``` **选项 2：安装 [Buildkite Test Collector](https://buildkite.com/docs/test-engine/test-collection)** 许多语言和框架都有可用的 test collector。某些 collector 还提供更丰富的数据收集，例如执行级别的 tag 和 span 追踪。有关适用于您的框架的详细信息，请参阅 [test collector 文档](https://buildkite.com/docs/test-engine/test-collection)。 ### Plan identifier `--plan-identifier`（或 `BUILDKITE_TEST_ENGINE_PLAN_IDENTIFIER`）设置 `plan` 命令生成计划所用的 identifier。该 identifier 是 计划的服务器端缓存 key：不同的值会产生不同的计划，而 重用一个值则会返回之前为该 identifier 缓存的计划。 在 Buildkite build 内部，您不需要设置此项；identifier 默认为 `${BUILDKITE_BUILD_ID}/${BUILDKITE_STEP_ID}`。在 **off-agent** 生成计划时（例如，在您的 本地开发环境或您自己的机器上运行），请显式提供 `--plan-identifier`。 这样做还消除了设置 `BUILDKITE_BUILD_ID` 和 `BUILDKITE_STEP_ID` 的必要，否则 它们是必需的。 ``` # 通过 Python (3.14+) 生成 UUIDv7；在旧版本上使用 uuid4() ./bktec plan --json --plan-identifier "$(python3 -c 'import uuid; print(uuid.uuid7())')" # 通过 uuidgen 生成 UUIDv4 (预装于 macOS 和大多数 Linux) ./bktec plan --json --plan-identifier "$(uuidgen)" ``` `bktec run` 接受相同的 flag。它会获取在该 identifier 下缓存的计划，或者在缓存未命中时，创建一个并将其缓存。因此，即使输入发生了 改变，重用的 identifier 也会返回之前缓存的计划，因此请确保每个不同的计划具有唯一的值。 ### 检查完整计划 `--plan-out` 使 `bktec plan` 写入完整的测试计划，而不运行任何 测试。与仅输出计划 identifier 和 parallelism 的 `--json` 不同， `--plan-out` 会写入整个计划：任务、每个节点的测试细分、 静默和跳过的测试，以及时间元数据。它接受一个目标位置： `-` 表示标准输出，或者一个文件路径。 ``` ./bktec plan --plan-out - # stdout ./bktec plan --plan-out plan.json # a file ``` 人类可读的拆分摘要和任何警告都会写入标准错误，因此 标准输出只包含计划。`--json`、`--plan-out` 和 `--pipeline-upload` 是互斥的；请选择其中一个。 `--plan-out` 原样写入服务器返回的内容。如果服务器无法 生成计划，它会返回一个空计划，该计划会原样输出（警告会 打印到标准错误）。只有当根本无法连接到服务器时，`bktec` 才会回退到本地生成的最小计划；它包含 identifier 和 parallelism，但没有任务（它不是计算出的拆分），并会在标准错误中注明。 ### 预览：测试选择 您可以将测试选择策略配置和额外的变更上下文传递给测试计划 API 请求。 仅当 `BKTEC_PREVIEW_SELECTION` 为真值（`1`、`true`、`yes` 或 `on`）时，才会启用此预览。 此功能正在开发中，这些 flag 目前具有未定义的行为。 环境变量： ``` export BKTEC_PREVIEW_SELECTION=true export BUILDKITE_TEST_ENGINE_SELECTION_STRATEGY=percent ``` 命令行 flag： ``` BKTEC_PREVIEW_SELECTION=true ./bktec plan --json --selection-strategy percent \ --selection-param percent=40 ``` #### 自动收集 git 元数据 当设置了 `--selection-strategy` 时，`plan` 命令会自动从当前仓库收集 git 元数据，并将其与 API 请求一起发送。 这包括提交信息（SHA、author、committer、message）、diff 数据（更改的文件、numstat、完整 diff）以及上下文字段（branch 名称、base branch、pipeline slug、build UUID）。 对于使用 `plan` 而没有 `--selection-strategy` 的 pipeline，您可以使用 `--collect-git-metadata` flag（或 `BUILDKITE_TEST_ENGINE_COLLECT_GIT_METADATA=true`）选择开启元数据收集。这会收集相同的 git 元数据，而无需配置选择功能： ``` BKTEC_PREVIEW_SELECTION=true ./bktec plan --json --collect-git-metadata ``` 用于 diff 计算的 base branch 使用回退链进行解析： 1. 通过 `--metadata base_branch=` 显式覆盖
2. `BUILDKITE_PULL_REQUEST_BASE_BRANCH`（在 PR build 中由 Buildkite 自动设置）
3. 通过 `/HEAD` 自动检测，然后是 `/main`，再然后是 `/master`
大多数用户不需要配置任何内容。仅当您的仓库使用非标准的默认 branch（例如 `develop` 或 `trunk`）并且未配置 `/HEAD` 时，才需要覆盖 `base_branch`。
`--remote` flag（默认为 `origin`）控制用于
base branch 检测的 git remote。您也可以设置
`BUILDKITE_TEST_ENGINE_REMOTE`。
自动收集的值会与您提供的任何显式 `--metadata` flag
合并。您的显式值始终优先。
#### 手动元数据覆盖
使用 `--metadata key=value` 传递额外的元数据或覆盖
自动收集的值。使用 `--selection-param key=value` 传递策略
参数。这两个 flag 都可以重复使用。值可以很大并且支持多行。
```
BKTEC_PREVIEW_SELECTION=true ./bktec plan --json --selection-strategy percent \
--selection-param percent=40 \
--metadata base_branch=develop
```
`--selection-param` 和 `--metadata` 仅支持作为可重复的 CLI flag。
### 预览：提交元数据回填
bktec 可以从您的仓库收集历史 git 提交元数据并将其上传到 Buildkite，以训练测试选择模型。这对于使用历史 changeset 数据引导模型非常有用，以便测试选择能够识别哪些测试与您的代码更改相关。
默认情况下，`tools` 子命令在 `bktec --help` 中是隐藏的。将 `BKTEC_PREVIEW_SELECTION` 设置为真值（`1`、`true`、`yes` 或 `on`）会使它们在帮助输出中可见。无论此设置如何，始终可以直接调用这些命令。
在 `bktec tools` 下有两个可用的命令：
**收集并上传提交元数据：**
```
bktec tools backfill-commit-metadata \
--access-token "bkua_..." \
--organization-slug "my-org" \
--suite-slug "my-suite"
```
**在本地生成 tarball 以便在上传前进行检查：**
```
bktec tools backfill-commit-metadata --output commit-metadata.tar.gz
# 查看内容
tar tzf commit-metadata.tar.gz
# commit-metadata.jsonl
# metadata.json
# 准备好后上传
bktec tools backfill-commit-metadata \
--upload commit-metadata.tar.gz \
--suite-slug "my-suite"
```
API access token 需要 `read_suites` 和 `write_suites` scope。
有关详细的用法、flag 和配置选项，请参阅 [提交元数据回填](./docs/commit-metadata-backfill.md) 指南。
### 配置测试运行器
要为 bktec 配置测试运行器，请参考每个受支持的测试运行器提供的详细指南。您可以在以下链接中找到这些指南：
- [Jest](./docs/jest.md)
- [Playwright](./docs/playwright.md)
- [Cypress](./docs/cypress.md)
- [pytest](./docs/pytest.md)
- [pytest pants](./docs/pytest-pants.md)
- [go test](./docs/gotest.md)
- [RSpec](./docs/rspec.md)
- [Cucumber](./docs/cucumber.md)
- [NUnit](./docs/nunit.md)
- [自定义测试运行器](./docs/custom-test-runner.md)
### 运行 bktec
请下载可执行文件并使其在您的测试环境中可用。
要在您的 Buildkite build 中并行化您的测试，您可以将您的 pipeline 步骤配置修改为：
```
steps:
- name: "Rspec"
command: ./bktec run
parallelism: 10
env:
BUILDKITE_TEST_ENGINE_SUITE_SLUG: my-suite
BUILDKITE_TEST_ENGINE_TEST_RUNNER: rspec
BUILDKITE_TEST_ENGINE_RESULT_PATH: tmp/result.json
```
### 调试
要启用调试模式，请将 `BUILDKITE_TEST_ENGINE_DEBUG_ENABLED` 环境变量设置为 `true`。这将打印详细的输出以协助调试 bktec。
### 可能的退出状态
bktec 可能会以多种退出状态退出，如下所示：
- 如果存在配置错误，bktec 将以
状态 16 退出。
- 如果测试运行器（例如 RSpec）正常退出，将返回该运行器的
退出状态。对于成功的测试运行，这很可能是 0，对于
失败的测试运行，很可能是 1，但也可能是运行器返回的
任何其他错误状态。
- 如果测试运行器被操作系统级别的信号（例如 SIGSEGV 或
SIGABRT）终止，返回的状态将等于 128 加上信号编号。
例如，如果运行器引发了 SIGSEGV，退出状态将是 (128 +
11) = 139。
## 开发
确保您的环境中安装了 Go、Ruby 和 Node.js。您可以按照以下这些工具的安装指南进行操作：
- [Go 安装指南](https://golang.org/doc/install)
- [Ruby 安装指南](https://www.ruby-lang.org/en/documentation/installation/)
- [Node.js 安装指南](https://nodejs.org/en/download/package-manager/)
安装好这些依赖项后，运行 `bin/setup` 来为测试用的示例项目安装依赖项。
要进行测试，请运行：
```
./bin/test
```
[^1]: 注意：Pants 不支持测试拆分，因为 Pants 会决定运行哪些测试。对于 go test，测试拆分是按 package 而不是按文件进行的。
请确保在您的 pipeline 定义中配置了 `parallelism`。您可以在此[页面](https://buildkite.com/docs/pipelines/controlling-concurrency#concurrency-and-parallelism)阅读更多关于 Buildkite 并行 build 步骤的信息。| | `BUILDKITE_PARALLEL_JOB_COUNT` | 由 Buildkite 并行 build 步骤创建的并行 job 总数。
请确保在您的 pipeline 定义中配置了 `parallelism`。您可以在此[页面](https://buildkite.com/docs/pipelines/controlling-concurrency#concurrency-and-parallelism)阅读更多关于 Buildkite 并行 build 步骤的信息。 | | `BUILDKITE_STEP_ID` | Buildkite build 中步骤组的 UUID。bktec 使用此 UUID 和 `BUILDKITE_BUILD_ID` 来唯一标识测试计划。 ### 身份验证 从 bktec 2.6.0 开始，bktec 会自动请求 [Buildkite Agent OIDC token](https://buildkite.com/docs/agent/cli/reference/oidc) 进行身份验证。您无需创建或配置 API access token。您需要[为您的 Test Engine suite 配置 OIDC 策略](https://buildkite.com/docs/pipelines/configure/tests/test-collection/oidc) 来允许此操作。 如果您运行的是 2.6.0 之前的 bktec，或者您想改用 API access token，可以在 Buildkite 的[个人设置](https://buildkite.com/user/api-access-tokens)中创建一个具有 `read_suites`、`read_test_plan` 和 `write_test_plan` scope 的 Buildkite API access token，然后设置： ``` export BUILDKITE_TEST_ENGINE_API_ACCESS_TOKEN=token ``` ### 配置 Test Engine suite slug 要使用 bktec，您需要配置 `BUILDKITE_TEST_ENGINE_SUITE_SLUG` 环境变量为您的 Test Engine suite slug。您可以在 suite 的 URL 中找到该 slug。例如，在 URL `https://buildkite.com/organizations/my-organization/analytics/suites/my-suite` 中，slug 就是 `my-suite`。 ``` export BUILDKITE_TEST_ENGINE_SUITE_SLUG=my-slug ``` ### 将测试结果上传到 Test Engine bktec 需要收集您的测试数据以启用智能测试拆分、重试和静默等功能。有两种方法可以做到这一点： **选项 1：使用 bktec 的内置上传功能（需要 bktec 2.7.0 或更高版本）** 将 `BUILDKITE_TEST_ENGINE_UPLOAD_RESULTS` 设置为 `true`： ``` export BUILDKITE_TEST_ENGINE_UPLOAD_RESULTS=true ``` 您可以使用 `--tag` 或 `BUILDKITE_TEST_ENGINE_TAGS` 为每次上传附加键/值对 tag。tag 有助于在 Test Engine 中过滤和分组测试结果。 ``` # 作为 CLI flags (repeatable) bktec run --tag env=production --tag region=us-east-1 # 作为 environment variable (comma-separated) export BUILDKITE_TEST_ENGINE_TAGS="env=production,region=us-east-1" ``` **选项 2：安装 [Buildkite Test Collector](https://buildkite.com/docs/test-engine/test-collection)** 许多语言和框架都有可用的 test collector。某些 collector 还提供更丰富的数据收集，例如执行级别的 tag 和 span 追踪。有关适用于您的框架的详细信息，请参阅 [test collector 文档](https://buildkite.com/docs/test-engine/test-collection)。 ### Plan identifier `--plan-identifier`（或 `BUILDKITE_TEST_ENGINE_PLAN_IDENTIFIER`）设置 `plan` 命令生成计划所用的 identifier。该 identifier 是 计划的服务器端缓存 key：不同的值会产生不同的计划，而 重用一个值则会返回之前为该 identifier 缓存的计划。 在 Buildkite build 内部，您不需要设置此项；identifier 默认为 `${BUILDKITE_BUILD_ID}/${BUILDKITE_STEP_ID}`。在 **off-agent** 生成计划时（例如，在您的 本地开发环境或您自己的机器上运行），请显式提供 `--plan-identifier`。 这样做还消除了设置 `BUILDKITE_BUILD_ID` 和 `BUILDKITE_STEP_ID` 的必要，否则 它们是必需的。 ``` # 通过 Python (3.14+) 生成 UUIDv7；在旧版本上使用 uuid4() ./bktec plan --json --plan-identifier "$(python3 -c 'import uuid; print(uuid.uuid7())')" # 通过 uuidgen 生成 UUIDv4 (预装于 macOS 和大多数 Linux) ./bktec plan --json --plan-identifier "$(uuidgen)" ``` `bktec run` 接受相同的 flag。它会获取在该 identifier 下缓存的计划，或者在缓存未命中时，创建一个并将其缓存。因此，即使输入发生了 改变，重用的 identifier 也会返回之前缓存的计划，因此请确保每个不同的计划具有唯一的值。 ### 检查完整计划 `--plan-out` 使 `bktec plan` 写入完整的测试计划，而不运行任何 测试。与仅输出计划 identifier 和 parallelism 的 `--json` 不同， `--plan-out` 会写入整个计划：任务、每个节点的测试细分、 静默和跳过的测试，以及时间元数据。它接受一个目标位置： `-` 表示标准输出，或者一个文件路径。 ``` ./bktec plan --plan-out - # stdout ./bktec plan --plan-out plan.json # a file ``` 人类可读的拆分摘要和任何警告都会写入标准错误，因此 标准输出只包含计划。`--json`、`--plan-out` 和 `--pipeline-upload` 是互斥的；请选择其中一个。 `--plan-out` 原样写入服务器返回的内容。如果服务器无法 生成计划，它会返回一个空计划，该计划会原样输出（警告会 打印到标准错误）。只有当根本无法连接到服务器时，`bktec` 才会回退到本地生成的最小计划；它包含 identifier 和 parallelism，但没有任务（它不是计算出的拆分），并会在标准错误中注明。 ### 预览：测试选择 您可以将测试选择策略配置和额外的变更上下文传递给测试计划 API 请求。 仅当 `BKTEC_PREVIEW_SELECTION` 为真值（`1`、`true`、`yes` 或 `on`）时，才会启用此预览。 此功能正在开发中，这些 flag 目前具有未定义的行为。 环境变量： ``` export BKTEC_PREVIEW_SELECTION=true export BUILDKITE_TEST_ENGINE_SELECTION_STRATEGY=percent ``` 命令行 flag： ``` BKTEC_PREVIEW_SELECTION=true ./bktec plan --json --selection-strategy percent \ --selection-param percent=40 ``` #### 自动收集 git 元数据 当设置了 `--selection-strategy` 时，`plan` 命令会自动从当前仓库收集 git 元数据，并将其与 API 请求一起发送。 这包括提交信息（SHA、author、committer、message）、diff 数据（更改的文件、numstat、完整 diff）以及上下文字段（branch 名称、base branch、pipeline slug、build UUID）。 对于使用 `plan` 而没有 `--selection-strategy` 的 pipeline，您可以使用 `--collect-git-metadata` flag（或 `BUILDKITE_TEST_ENGINE_COLLECT_GIT_METADATA=true`）选择开启元数据收集。这会收集相同的 git 元数据，而无需配置选择功能： ``` BKTEC_PREVIEW_SELECTION=true ./bktec plan --json --collect-git-metadata ``` 用于 diff 计算的 base branch 使用回退链进行解析： 1. 通过 `--metadata base_branch=
标签：EVTX分析, SOC Prime, 安全规则引擎, 并行计算, 开发工具, 开源框架, 持续集成, 日志审计, 测试工具, 测试编排, 特征检测