coroboros/karate
GitHub: coroboros/karate
一个轻量级的 Karate API 测试 Docker 镜像及 GitLab CI/CD 组件，用于在持续集成中运行 REST、GraphQL 等接口测试并生成报告。
Stars: 0 | Forks: 0
# karate
**在 CI 中运行 Karate API 和集成测试 — REST、GraphQL、WebSocket、mock server。**
基于 Alpine 的镜像，在 `eclipse-temurin:21-jre-alpine` 之上打包了 [Karate](https://github.com/karatelabs/karate) fat jar，并附带 `bash` 和 `ca-certificates`，用于 shell wrapper 和 HTTPS 测试目标。内置一个 CI/CD 组件 — 只需一个 include 即可运行 `.feature` 测试套件，并将 HTML 报告发布为 job artifact。
[](https://gitlab.com/coroboros/infrastructure/karate/-/releases)
[](https://gitlab.com/coroboros/infrastructure/karate/-/pipelines)
[](https://github.com/orgs/coroboros/packages/container/package/karate)
[](https://hub.docker.com/r/coroboros/karate)
[](LICENSE.md)
[](https://gitlab.com/coroboros/infrastructure/karate)
[](https://github.com/coroboros/agent-skills)
[](https://coroboros.com)
## 目录
- [要求](#requirements)
- [镜像](#image)
- [标签](#tags)
- [命令](#commands)
- [运行](#run)
- [报告](#reports)
- [Agents](#agents)
- [包](#packages)
- [来源证明](#provenance)
- [与替代方案比较](#compared-to-alternatives)
- [安全性](#security)
- [贡献](#contributing)
- [许可证](#license)
## 要求
Docker、BuildKit 或任何能够从 GitHub Container Registry（或 Docker Hub 镜像）拉取的 OCI runtime。
## 镜像
`ghcr.io/coroboros/karate:{tag}` — 镜像同步至 `docker.io/coroboros/karate:{tag}`，以及位于 `registry.gitlab.com/coroboros/infrastructure/karate:{tag}` 的 GitLab Container Registry。
- **架构**: `linux/amd64`, `linux/arm64`
- **工作目录**: `/karate`
- **Entrypoint**: `karate`
- **默认命令**: `/karate/features`
- **用户**: 非 root 用户 `karate` (uid 10000)
- **Volumes**: `/karate/features` (挂载 feature 文件), `/karate/target` (测试输出)
## 标签
| Tag | Karate | JRE base | 架构 | 大小 | 来源 | 可变性 |
| --- | --- | --- | --- | --- | --- | --- |
| `2.0.9-temurin21` | [`2.0.9`](images/2.0.9-temurin21/image.env) | [`eclipse-temurin:21-jre-alpine`](images/2.0.9-temurin21/image.env) | `amd64`, `arm64` | 99.7 MB (amd64), 99.4 MB (arm64) | 当前矩阵行 | 滚动 |
| `
-2.0.9-temurin21` | 取决于构建 | 取决于构建 | 取决于构建 | 取决于构建 | 每次 `2.0.9-temurin21` 构建 | 不可变 |
大小是来自 GitLab Container Registry 的压缩层总和。镜像 tag 决定了 Karate runner 和 Java runtime；仓库的 SemVer tag 对 GitLab CI/CD 组件进行版本控制。请固定 digest 以实现可复现的构建；参见[来源证明](#provenance)。
## 命令
`karate [options] [feature_path]`
feature_path
一个或多个 `.feature` 文件或目录。默认为 `/karate/features`（镜像暴露的 volume）。
options
转发给 Karate runner。完整参考：[Karate CLI 选项](https://github.com/karatelabs/karate/wiki/Karate-Options)。最常用的 flag：
| Flag | 用途 |
| --- | --- |
| `-h` | 打印帮助并退出。 |
| `-t @tag` | 仅运行标记为 `@tag` 的场景。可组合使用：`-t @smoke,~@wip`。 |
| `-T ` | 并行运行 `` 个 feature。 |
| `-o ` | 覆盖输出目录（默认为 `/karate/target`）。 |
| `-e ` | 设置 `karate.env`（基于环境的配置）。 |
环境变量
| 变量 | 默认值 | 用途 |
| --- | --- | --- |
| `LANG` | `C.UTF-8` | 区域设置，在镜像中设定以确保 JVM 行为一致。 |
| `JAVA_TOOL_OPTIONS` | 未设置 | 标准的 JVM 调优 hook — 堆、GC、系统属性 (`-Dkarate.env=...`)。 |
示例
```
karate /karate/features
```
```
karate -T 4 -t @smoke /karate/features/api
```
## 运行
GitLab CI
```
api-tests:
image:
name: registry.gitlab.com/coroboros/infrastructure/karate:
entrypoint: [""]
stage: test
script:
- karate features
artifacts:
when: always
paths:
- target/
```
```
parallel-tests:
image:
name: registry.gitlab.com/coroboros/infrastructure/karate:
entrypoint: [""]
stage: test
script:
- karate -T 4 -t @smoke features
```
CI/CD 组件
只需一个 include 即可运行测试套件并将 HTML 报告发布为 job artifact。测试失败会导致 job 失败；设置 `allow_failure: true` 可使其仅作为建议保留。
```
include:
- component: gitlab.com/coroboros/infrastructure/karate/karate@
inputs:
feature_path: features
parallel: 4
tags: "@smoke,~@wip"
```
最后的 `/karate` 部分是来自 `templates/karate.yml` 的组件名称；GitLab 组件引用的格式为 `//@`。
输入项：`job_name`、`stage`、`feature_path`、`parallel`、`tags`、`env`、`output_dir`、`options`、`java_tool_options`、`allow_failure`、`image` — 参见 [`templates/karate.yml`](templates/karate.yml)。组件版本是此仓库的 SemVer，独立于镜像 tag。
Docker
挂载 features 目录并运行：
```
docker run --rm \
-v "$PWD/features:/karate/features" \
-v "$PWD/target:/karate/target" \
registry.gitlab.com/coroboros/infrastructure/karate:
```
```
docker run --rm \
-v "$PWD/features:/karate/features" \
-v "$PWD/target:/karate/target" \
registry.gitlab.com/coroboros/infrastructure/karate: \
-T 4 -t @smoke
```
## 报告
Karate 会将 HTML 报告（`karate-summary.html`、各 feature 页面、时间线）写入输出目录（`-o`，默认为 `target`）。[CI/CD 组件](#run)会将其作为 job artifact 收集；打开 `karate-summary.html` 可查看每个场景的通过/失败状态。失败的场景会以非零状态码退出，因此无论如何 job 都会失败。
## Agents
karate 为 coding agent 提供了一个 agent skill — 这是一份专供 coding agent 使用的 Karate feature 测试编写与运行指南。将其安装到 agent 中：
```
npx skills add https://gitlab.com/coroboros/infrastructure/karate
```
或者不安装直接阅读：[`skills/karate/SKILL.md`](skills/karate/SKILL.md)。
## 包
所有 Karate tag 中保持一致。
| Package | 用途 |
|---|---|
| `eclipse-temurin` (JRE) | Java runtime |
| `karate` | 位于 `/karate/karate.jar` 的 Karate fat jar + 位于 `/bin/karate` 的 `karate` wrapper |
| `bash` | Shell |
| `ca-certificates` | 用于 Karate HTTPS 测试请求的 TLS 证书包 |
镜像行定义在 [`images/`](images) 中。Dfile 的默认设置与本地构建保持同步。Renovate 会在一个合并请求中维护当前的 Karate 行及其 JAR 校验和，并刷新当前的 JRE base digest。
## 来源证明
通过共享的 [`coroboros/ci`](https://gitlab.com/coroboros/ci) `container-images` 模板发布的每一个镜像都：
- **多架构** — BuildKit, `linux/amd64,linux/arm64`;
- **受控** — 通过 `gitleaks` 获取源密钥，通过 Trivy 在已发布的 `:sha` 上扫描镜像 CVE，并在 tag 晋升前运行离线的 Karate smoke feature；
- **已签名** — 在不可变的 digest 上进行 cosign keyless 签名，并附带 **CycloneDX SBOM** 证明。
签名的 digest 会发布到 `ghcr.io/coroboros/karate`，并同步到 `docker.io/coroboros/karate` 上的版本 tag。
### 固定版本
`2.0.9-temurin21` 是一个**针对该 Karate/JRE 组合的滚动镜像 tag**。基础镜像的 CVE 修复可能会导致其变动；精确的可复现性需使用签名的 digest。CI 矩阵即支持列表：新的 Karate 版本会获得新的 `-` 行，只有在验证兼容性后，不同的 Java runtime 才会有其单独的行。
要进行可复现、防篡改的构建，请通过 `image` 输入项固定 **manifest-list digest**（多架构），并让 Renovate 保持其为最新状态：
```
include:
- component: gitlab.com/coroboros/infrastructure/karate/karate@
inputs:
image: registry.gitlab.com/coroboros/infrastructure/karate:@sha256:
```
cosign 签名绑定的是 digest 而不是 tag，因此请验证所固定的 digest：
```
cosign verify \
--certificate-identity-regexp 'https://gitlab.com/coroboros/infrastructure/karate//.*' \
--certificate-oidc-issuer https://gitlab.com \
ghcr.io/coroboros/karate@sha256:
```
## 与替代方案比较
### 与其他 API 测试框架对比
| 功能 | `cucumber-jvm` | `rest-assured` | `postman` / `newman` | `playwright` (API) | **`karate`** |
| --- | :---: | :---: | :---: | :---: | :---: |
| BDD 风格的 feature 语法 | 是 | 否 | 否 | 否 | 是 |
| HTTP / REST 测试 | 通过库 | 是 | 是 | 是 | 是 |
| GraphQL 测试 | 通过库 | 作为原生 HTTP | 是 (UI / 脚本) | 作为原生 HTTP | 是 |
| 内置匹配断言 (模糊 / schema) | 否 | 否 | 否 | 否 | 是 |
| 并行执行 | 取决于 runner | 取决于 runner | 是 | 是 | 是 (`-T`) |
| 内置 Mock server | 否 | 否 | 是 (UI) | 否 | 是 |
| 单一二进制执行 | 否 | 否 | 是 | 否 | 是 (fat jar) |
| 无需 glue code (Java / JS) | 否 | 否 | 是 | 否 | 是 |
区别：karate 将 BDD 风格的 feature 文件与内置的 HTTP / GraphQL / WebSocket 客户端、感知 schema 的 `match` 断言以及 mock server 结合在一起 — 所有这些都包含在一个无需 glue code 的单一 fat jar 中。
### 与其他 Karate Docker 镜像对比
| 镜像 | Base | 大小 | 最后更新 | 侧重点 |
| --- | --- | --- | --- | --- |
| `karatelabs/karate-chrome` (官方) | Ubuntu + Chrome + Xvfb + VNC | ~800 MB | 约 6 个月前 | 浏览器自动化 |
| `tgintegrationtests/karate` (社区) | 未指定 | — | 约 7 个月前 | 通用 |
| `remarkableas/karate` (社区) | 未指定 | — | 约 5 年前 | 已陈旧 |
| `ibmurai/karate` (社区) | 未指定 | — | 约 7 年前 | 已陈旧 |
| **`coroboros/infrastructure/karate`** | `eclipse-temurin:21-jre-alpine` | 99.7 MB (amd64), 99.4 MB (arm64) | 滚动 | API / 集成测试 |
区别：官方的 `karatelabs/karate-chrome` 捆绑了 Chrome + Xvfb + VNC 用于浏览器自动化 — 约 800 MB，对于纯 API 测试来说过于臃肿。社区镜像早已陈旧（5-7 年）。本镜像精简为 Alpine 上的 JRE 21 + Karate fat jar：体积缩小了约 8 倍，保持最新，使用非 root 用户，并将 `features` / `target` 暴露为 volume。
## 安全性
请通过[安全策略](SECURITY.md)私下报告漏洞 — **ob@coroboros.com**，请勿使用公开的 issue。
## 贡献
欢迎提交 Bug 报告和合并请求。
- 在提交非简单的合并请求之前，请先创建一个 issue。
- 提交须遵循 [Conventional Commits](https://www.conventionalcommits.org/)。
- 对每个 commit 进行 sign off (DCO)：`git -s`。
- 请将合并目标设定为 `main` 分支。
## 许可证
[Apache 2.0](LICENSE.md)标签：API测试, Docker容器, 开源框架, 持续集成, 攻击面发现, 测试框架, 请求拦截, 集成测试