Keploy 快速上手：基于 eBPF 的 API 录制-回放测试从零到一

Keploy 快速上手：基于 eBPF 的 API 录制-回放测试从零到一

【免费下载链接】keployOpen-source platform for creating safe, isolated production sandboxes for API, integration, and E2E testing.项目地址: https://gitcode.com/GitHub_Trending/ke/keploy

Keploy 是一个面向开发者的 API 与集成测试工具：它把真实的 API 调用连同数据库等依赖交互一起录制下来，并在回放阶段自动生成带 mock 的测试用例。本文以 Keploy 官方文档（法语版 README）为主线，走通「安装 Agent → 录制用例 → 离线回放测试」的完整流程，并结合仓库源码（安装脚本、CLI 命令实现、配置参数定义）深入解释每个步骤背后的机制与关键参数的取值。

一、Keploy 定位：比单元测试更快的 API 测试

Keploy 的核心理念可以用两句话概括：

• 测试比单元测试更快生成：不写测试代码，把用户流量（API 调用）直接转成测试用例；
• 不仅录制 API，还录制依赖：Keploy 会同时捕获数据库等下游调用，并在回放时自动用 mock/stub 顶替，因此回放时不再需要真实的数据库、Redis、Kafka。

文档原文强调：

Keploy 是一个面向开发者的 API 测试工具，它创建自带 mock 的测试，速度比编写单元测试更快。Keploy 不仅记录 API 调用，还记录数据库调用，并在测试时回放。

这与仓库的英文 README 描述一致：Keploy 在底层使用 eBPF 在网络层捕获流量，对用户而言是零代码侵入、语言无关的。

二、快速安装：一条命令安装本地 Agent

文档给出的官方安装命令：

curl --silent -O -L https://keploy.io/install.sh && source install.sh

安装完成后，本地即拥有keploy命令，不需要修改任何业务代码。

2.1 安装脚本做了什么（源码级解读）

仓库中保留了一份可审计的安装脚本 keploy.sh，它揭示了安装流程的细节：

• 版本与安装模式参数（installKeploy()，keploy.sh#L160-L192）：
  • -v v<semver>：指定安装的版本号（需匹配^v[0-9]+.*），默认latest；
  • -noRoot：不使用 sudo，把二进制装到$HOME/.keploy/bin并把该目录写入PATH（macOS 默认走此分支）；
  • -platform <shell>：指定当前 shell（默认取$SHELL的 basename），用于决定写.zshrc、.bashrc还是.profile；
  • -isCI：CI 模式，跳过交互式 UI（下载进度条、加载动画）。
• 平台分发：
  • macOS（Darwin）：下载keploy_darwin_all.tar.gz，强制NO_ROOT=true，二进制解包路径为/tmp/keploy/keploy；
  • Linuxx86_64/aarch64：分别下载keploy_linux_amd64.tar.gz/keploy_linux_arm64.tar.gz，默认安装到/usr/local/bin/keploy；
  • Linux 下若/sys/kernel/debug未挂载会尝试mount -t debugfs debugfs /sys/kernel/debug（eBPF 运行所需，见 keploy.sh#L443-L448）；
  • Windows 环境：脚本明确提示 OSS 构建没有原生 Windows 后端（eBPF 仅 Linux 可用），建议走 WSL2 或使用 Docker 运行应用。
• 默认路由说明：脚本末尾默认安装 Keploy Community Edition，需要 OSS 版时传--oss参数（keploy.sh#L493-L511）。
• 体验细节：脚本实现了下载进度条（轮询文件大计算百分比）、spinner 加载动画，安装结束后自动执行keploy example展示示例用法。

2.2 无本地安装的自动运行

文档还提供了一条免安装路径：借助 GitHub Codespace 等云端开发环境直接配置并运行 Keploy，无需在本地机器上安装二进制。适合只想快速体验流程的读者。

三、录制测试用例：keploy record

文档核心操作：

keploy record -c "CMD_TO_RUN_APP"

把CMD_TO_RUN_APP换成你的应用启动命令即可，各语言的典型写法（文档原文示例）：

运行期间，Keploy 会把真实流量转换成测试用例 + mocks/stubs并落盘保存。

3.1record命令的源码实现

cli/record.go 定义了该命令：

• 命令注册名record，用途描述为 “record the keploy testcases from the API calls”，官方示例即keploy record -c "/path/to/user/app"；
• PreRunE阶段通过cmdConfigurator.Validate校验参数，RunE阶段从ServiceFactory取出recordSvc.Service（对应 pkg/service/record 中的录制服务）并调用Start(ctx)启动整个录制流水线。

3.2 支持 Docker/Compose 场景

当应用以容器方式启动时，record支持 Docker 命令作为-c参数，并可用--buildDelay指定容器构建等待时间（cli/provider/cmd.go#L79-L82）：

keploy record -c "docker run -p 8080:8080 --name <containerName> --network <networkName> <applicationImage>" --buildDelay 60

源码中还有贴心提示：若buildDelay≤ 30 秒，CLI 会主动提醒你为慢构建调大--buildDelay（cli/provider/cmd.go#L1366-L1369）。

四、运行测试：keploy test --delay

文档给出的回放命令：

keploy test -c "CMD_TO_RUN_APP" --delay 10

关键前置步骤：先停掉应用依赖的数据库、Redis、Kafka 等所有外部服务——回放阶段 Keploy 用录制的 mock 顶替它们，真实服务不参与测试。

4.1--delay参数与就绪探测

--delay（简写-d）表示“应用就绪前等待的秒数”（cli/provider/cmd.go#L421："User provided time to run its application"；Kubernetes 场景下的语义是"Seconds to wait for the runner to be ready before it starts issuing calls"）。源码中还有一个默认值提醒逻辑：若Delay <= 5，CLI 会提示你根据应用启动耗时调大--delay（cli/provider/cmd.go#L1627-L1628）。

从 config/config.go#L386-L391 的配置结构看，Delay之外还提供了更精细的就绪探测选项：

• HealthURL：可选的 HTTP(S) 健康检查地址，在发起第一个测试前先轮询它；为空则保持固定的--delay行为；
• HealthPollTimeout：健康轮询的超时上限，超时后回退到--delay；
• AppReadyProbeAddr：对没有 HTTP 健康端口的应用，用host:portTCP 探测代替，且只用于就绪探测、绝不影响请求路由；
• KeepAppAlive：只启动一次用户应用、跨所有测试集复用（跳过每个测试集的重新启动和--delay等待），适用于需要长连接跨测试集暴露的问题（如 asyncpg 连接池、JDBC HikariCP 池）。

4.2test命令的源码实现

cli/test.go 定义了回放命令：

• 描述为 “run the recorded testcases and execute assertions”，官方示例keploy test -c "/path/to/user/app" --delay 6；
• RunE中取出replaySvc.Service（对应 pkg/service/replay），并defer了一个兜底清理：无论测试出错还是上下文取消，都会调用utils.ExecCancel()停掉 Keploy，避免残留进程。

五、覆盖率：与单元测试框架组合

文档建议把 Keploy 的集成测试与你现有的单元测试框架（go test、JUnit、pytest、jest 等）结合使用，获得合并后的覆盖率视图。这对应官方特性中的 “Couverture de Tests Combinés / Combined Test Coverage”：Keploy 负责 API 集成层面的覆盖，单元测试框架负责语句/分支级覆盖，二者合并后覆盖率指标更客观。

六、魔法如何运作：代理 + eBPF

文档「Comment la magie opère」一节的原文要点：

Keploy 的代理会捕获并回放你应用所有的网络交互（包括非幂等 API 的 CRUD 操作）。

结合仓库源码可以进一步印证这条链路：

• eBPF 钩子：Linux 平台的流量拦截基于 eBPF，编译产物位于 pkg/agent/hooks/linux（含bpf_x86_bpfel.o、bpf_arm64_bpfel.o等内核对象），负责在系统调用/网络层挂钩并收集连接信息；这也是为什么安装脚本要挂载debugfs，以及 eBPF 仅支持 Linux 的根本原因；
• 代理捕获：捕获与转发逻辑集中在 pkg/agent/proxy，其中 pkg/agent/proxy/relay 负责连接中继、pkg/agent/proxy/tls 负责 TLS 场景的 CA 与握手处理；按协议划分的捕获器包括 pkg/agent/proxy/incoming/http.go、gRPC 捕获（pkg/agent/proxy/incoming/gRPC）以及 MySQL 等数据库协议的检测与分发（pkg/agent/proxy/mysql_detect.go）；
• mock 存储与匹配：落盘的 mock 通过 pkg/agent/proxy/mockmanager.go 与 pkg/platform/yaml/mockdb 的 YAML 存储管理，回放时按请求特征匹配并返回录制响应。

从源码结构看，「录制 → 落盘 → 回放匹配」这条流水线被拆成了 agent（捕获）、service（record/replay 编排）、matcher（请求匹配）三层，与文档「捕获并重放所有网络交互」的描述相互印证。

七、关键特性一览

文档列出的五项核心能力，逐条说明：

1. 组合测试覆盖率（♻️）：将 Keploy 测试与任意测试库（JUnit、go test、pytest、jest）的结果合并，得到统一的覆盖率视图；
2. eBPF 插桩（🤖）：eBPF 是实现「零代码集成、语言无关、轻量」的关键技术，无需在任何服务中注入 SDK；
3. CI/CD 集成（🌐）：测试可在本地 CLI、CI 流水线（Jenkins、GitHub Actions 等）或 Kubernetes 集群中运行，mock 随用例一起流转；
4. 复杂流录制-回放（📽️）：分布式、多跳的 API 流程可整体捕获并回放为 mock/stub，相当于给测试配了一台「时间机器」；
5. 多用途 Mock（🎭）：Keploy 生成的 mock 不仅可以做测试回放，还可以直接当作服务器测试（server test）使用，即独立起一个由 mock 驱动的假服务。

八、支持的语言

由于捕获发生在网络层，Keploy 对应用语言无要求。文档列出的支持语言包括：Go、Java、Node.js、Rust、C#、Python（英文 README 进一步列出了 C/C++、TypeScript、Scala、Kotlin、Swift、Dart、PHP、Ruby、Elixir、.NET 等，以及 gRPC、GraphQL、HTTP/REST、Kafka、RabbitMQ、PostgreSQL、MySQL、MongoDB、Redis 等常见协议与基础设施）。

九、当前限制（如实说明）

文档专门列出了两条限制，使用时应提前知悉：

• 单元测试：Keploy 生成的是集成测试而非单元测试，其定位是补充Go test、JUnit 等单元测试框架以提升总覆盖率，而不是替代；
• 生产高负载环境：Keploy 当前聚焦于开发者的测试生成场景。用例可以从任意环境捕获，但尚未在高负载生产环境验证过——那需要强健的去重机制来避免捕获过多冗余用例（文档引用了 issue #27 跟踪这一方向）。

十、延伸阅读与社区

• 贡献指南：CODE_OF_CONDUCT.md 与贡献文档（文档中指向仓库内的贡献规范文件）；
• 「Keploy 如何工作」的深度解释与 FAQ 在官方文档站（docs.keploy.io）对应章节；
• 项目使用 Go 编写，入口为 main.go，CLI 层位于 cli 目录（record、test等子命令均在此注册），测试用例可参考各目录下的*_test.go（如 cli/record.go 配套的 cli/provider/cmd_test.go）。

适用前提小结：eBPF 流量拦截要求 Linux 环境（Windows 需 WSL2 或 Docker 方式运行应用），eBPF 场景通常需要挂载 debugfs；回放阶段应停止真实依赖服务以获得确定性的离线测试。按照本文的三步流程——安装 Agent、keploy record -c "<启动命令>"、keploy test -c "<启动命令>" --delay 10——即可在不改一行代码的前提下，把真实流量变成可重复执行的集成测试。

【免费下载链接】keployOpen-source platform for creating safe, isolated production sandboxes for API, integration, and E2E testing.项目地址: https://gitcode.com/GitHub_Trending/ke/keploy