eCapture E2E 测试实战：从 `make e2e` 一键验证到 CI 集成的完整操作指南

eCapture E2E 测试实战从make e2e一键验证到 CI 集成的完整操作指南【免费下载链接】ecaptureCapturing SSL/TLS plaintext without a CA certificate using eBPF. Supported on Linux/Android kernels for amd64/arm64.项目地址: https://gitcode.com/GitHub_Trending/ec/ecapture本文基于 test/e2e/QUICK_REFERENCE.md 编写面向需要验证 eCapture 各模块TLS、GoTLS、Bash、Zsh、MySQL、PostgreSQL、GnuTLS抓包能力或将端到端测试接入 CI 流水线的开发者。读完后你可以掌握如何按基础/高级/单模块三级粒度运行测试、如何解读测试结果与定位失败原因、各测试参数的覆盖边界以及如何用仓库提供的模板规范地新增测试脚本。一、前置条件与环境要求E2E 测试在真实内核上验证 eBPF 探针的实际抓包效果因此对运行环境有明确要求见 test/e2e/README.md 与 README.md操作系统Linux内核要求x86_64 ≥ 4.18或aarch64 ≥ 5.5按 CPU 架构分别适用权限必须使用root权限运行eBPF 探针加载与挂载需要必备工具curl、go、bash可选工具mysql、postgresql、zsh、tsharkpcap 结果校验、tcpdumpkeylog 集成验证。缺少可选工具时对应场景会降级为跳过或部分验证而非整体失败。构建二进制bin/ecapturemake all # 构建完整 eCapture含 CO-RE eBPF 字节码 # 或 make nocore # 不构建 CO-RE 字节码的回退方式从 Makefile 可见all目标会依次执行ebpf、ebpf_noncore、assets、build四个阶段Makefile#L6用 clang 编译kern/下的各 eBPF C 文件、将字节码打包进assets/ebpf_probe.go后再生成 Go 二进制。测试脚本自身也内置了构建回退逻辑build_ecapture() 会优先尝试make all -j 4失败后自动降级为make nocore -j 4与上面的两种构建方式一一对应。二、快速上手三级运行入口QUICK_REFERENCE.md 给出的最小上手命令如下# Build eCapture make all # or: make nocore # Run all tests (requires root) sudo make e2e # Run only basic tests sudo make e2e-basic # Run only advanced tests sudo make e2e-advanced三个聚合目标在 Makefile#L304-L316 中定义实际编排关系为e2e-basic→e2e-bash、e2e-tls、e2e-gnutls、e2e-gotlse2e-advanced→ 三个 TLS 高级测试、e2e-gotls-advanced、e2e-bash-advanced、e2e-edge-cases、e2e-ecaptureqe2e→e2e-basice2e-advanced。此外e2e-zsh、e2e-mysql、e2e-postgres、e2e-mysql-advanced作为独立目标单独存在Makefile#L229-L296需要数据库服务或特定 shell 环境时可单独触发。除 Linux 外Makefile#L319-L329 还提供了e2e-android-tls、e2e-android-gotls等 Android 真机测试目标属于文档未展开的额外能力此处仅作提示。三、测试分类与场景规模整套测试划分为**基础测试11 个场景与高级测试61 个场景**两类合计72 场景、覆盖 8 个模块全量执行约需10-20 分钟。基础测试*_e2e_test.sh7 个脚本sudo make e2e-bash # Bash command capture sudo make e2e-zsh # Zsh command capture sudo make e2e-mysql # MySQL query capture sudo make e2e-postgres # PostgreSQL query capture sudo make e2e-tls # TLS text/pcap/keylog modes sudo make e2e-gnutls # GnuTLS capture sudo make e2e-gotls # GoTLS capture高级测试*_advanced_test.sh7 个脚本模块Make 目标场景数覆盖点TLSe2e-tls-text-advanced—HTTP/1.1、HTTP/2、PID/UID 过滤、并发、debug、hexTLSe2e-tls-pcap-advanced—端口/host 过滤、网卡指定、tshark 校验、mapsizeTLSe2e-tls-keylog-advanced—TLS 1.2/1.3、keylog 格式校验、tcpdump 集成GoTLSe2e-gotls-advanced7text/pcap/keylog 三种模式、client-server、静态二进制Bashe2e-bash-advanced8管道、重定向、后台任务、子 shell、特殊字符MySQLe2e-mysql-advanced7SELECT/INSERT/UPDATE/DELETE、事务、并发边界场景e2e-edge-cases15非法输入、信号处理、权限、边界值其中 TLS 模块高级测试共 24 个场景3 个脚本 × 8 个测试各脚本的具体测试点见 test/e2e/README.md。以 test/e2e/tls_text_advanced_test.sh 为例其测试 1 的流程可以直观看到 e2e 用例的通用写法tls_text_advanced_test.sh#L41-L75# 1. 后台启动 ecapture text 模式输出重定向到日志 $ECAPTURE_BINARY tls -m text $mode_log 21 local pid$! sleep 3 # 2. 确认进程存活未立即退出即认为探针挂载成功 if ! kill -0 $pid 2/dev/null; then log_error eCapture died during startup; ... fi # 3. 用 curl 产生受控流量 curl -v --http1.1 $test_url /dev/null 21 || true sleep 2 # 4. 发送 SIGINT 优雅退出等待收尾 kill -INT $pid 2/dev/null || true sleep 2 # 5. 校验输出中是否出现预期明文GET/POST/HTTP if [ -s $mode_log ] grep -iq GET\|POST\|HTTP $mode_log; then log_success ✓ HTTP/1.1 capture test PASSED fi这个启动 → 探活 → 打流量 → 信号退出 → 正则断言的模式在 test/e2e/README.md 的 Common Testing Patterns 一节被总结为三类通用模式基础抓包测试、参数合法性验证timeout 5 ecapture module --invalid-param、信号优雅退出验证。目录结构test/e2e/ ├── common.sh # 共享工具函数 ├── README.md # 完整文档 ├── QUICK_REFERENCE.md # 快速参考本文对应的源文档 ├── run_e2e.sh # 轻量 smoke 测试入口 ├── *_e2e_test.sh # 基础测试7 个脚本 │ ├── bash_e2e_test.sh / zsh_e2e_test.sh / mysql_e2e_test.sh │ ├── postgres_e2e_test.sh / tls_e2e_test.sh / gnutls_e2e_test.sh │ └── gotls_e2e_test.sh └── *_advanced_test.sh # 高级测试7 个脚本 ├── tls_text_advanced_test.sh / tls_pcap_advanced_test.sh ├── tls_keylog_advanced_test.sh / gotls_advanced_test.sh └── bash_advanced_test.sh / mysql_advanced_test.sh / edge_cases_test.sh所有测试脚本统一source同目录的 test/e2e/common.sh它提供了标准化的基础设施check_rootroot 校验、check_kernel_version默认校验 ≥4.18common.sh#L41-L59、check_prerequisites工具链检查、kill_by_pattern按模式清理进程失败时kill -9兜底、setup_cleanup_trapEXIT/INT/TERM 统一清理、verify_text_in_output/verify_content_match输出断言、extract_plaintext按GET|POST|HTTP提取明文以及print_captured_content剥离INF/DBG/WRN/ERR日志行后预览捕获内容。四、测试结果图例与输出解读测试脚本通过四符号图例标注每个场景的结果符号含义说明✓PASS测试按预期完成⚠WARN测试完成但验证受限如缺少 tshark/tcpdump 等可选工具✗FAIL测试失败需查看日志⊘SKIP因依赖缺失而跳过对应的典型输出样例引自 QUICK_REFERENCE.md# 成功 [INFO] Test 1: HTTP/1.1 Capture [INFO] Starting ecapture in text mode [INFO] Making HTTP/1.1 request to https://www.github.com [SUCCESS] ✓ HTTP/1.1 capture test PASSED # 警告进程过快退出导致未捕获到数据 [INFO] Test 3: PID Filtering [WARN] ⚠ PID filtering test produced no output (process may have completed too quickly) # 失败 [INFO] Test 5: Concurrent Connections [ERROR] eCapture died during startup [ERROR] ✗ Concurrent connections test FAILEDWARN 并不等价于失败它通常表示环境缺少可选验证工具或目标进程生命周期太短。FAIL 则要重点看进程启动即退出eBPF 挂载失败或输出文件为空无匹配流量两类原因。五、测试日志位置与失败排查日志保留规则每个测试脚本的临时目录遵循/tmp/ecapture_module_test_pid/命名输出落在其下的output/子目录例如/tmp/ecapture_tls_text_advanced_12345/output/ ├── http11.log ├── http2.log ├── pid_filter.log └── ...以 tls_text_advanced_test.sh#L24-L38 的cleanup_handler为准保留策略是测试失败TEST_FAILED1时保留日志供排查测试通过时rm -rf清理临时目录。因此失败后应第一时间检查/tmp/ecapture_*下的日志CI 中也是按此路径上传产物见下文 CI 示例。常见问题速查报错/现象处理方式Root privileges required加sudo重跑如sudo make e2e-tlsKernel version check faileduname -r查看内核版本要求 x86_64 ≥ 4.18 或 aarch64 ≥ 5.5eCapture binary not found先执行make all或make nocore构建bin/ecaptureMySQL not available安装并启动数据库sudo apt-get install mysql-server mysql-client sudo systemctl start mysql测试无输出依次排查① 进程过快完成加大 sleep② 未产生匹配流量③ eBPF 程序挂载失败查dmesg④ 权限问题六、调试模式文档推荐两种互补的调试手段# 1. 用 bash -x 逐行跟踪测试脚本本身 sudo bash -x ./test/e2e/tls_text_advanced_test.sh # 2. 打开 ecapture 自身的 debug 日志-d/--debug sudo ecapture tls -m text -d debug.log 21-d对应的 flag 定义见 cli/cmd/root.go#L162enable debug logging。开启后可观察 eBPF 程序挂载状态、hook 函数定位结果与事件捕获详情配合dmesg可区分脚本逻辑问题与内核挂载问题。此外仓库还有一个轻量级的独立入口 test/e2e/run_e2e.sh它先做环境检查go/clang、make clean后尝试构建make all失败自动降级make nocore再对二进制执行--help、--version、tls -h等非侵入式 smoke 检查不加载 eBPF、不要求 root最后打印完整测试的运行提示。适合在无法跑完整 e2e 的环境里做构建冒烟验证。七、各模块依赖要求模块必需可选/备注TLS / GoTLScurltsharkpcap 校验、tcpdumpkeylog 集成Bash / Zshbash或zshbash 与 readline 链接效果最佳MySQLmysql-client 运行中的 MySQL/MariaDB测试库自动创建/清理PostgreSQLpostgresql-client 运行中的 PostgreSQL测试库自动创建/清理数据库类测试会自动创建并清理测试用库无需手工准备数据TLS 类测试依赖外部 HTTPS 站点产生流量网络受限时可考虑本地起 HTTPS 服务替代见下文性能建议。八、参数覆盖清单已测与待测这是快速参考中最具检索价值的一张表它标明了 e2e 套件实际验证过哪些 CLI 参数。已被 e2e 覆盖的参数 ✓参数作用源码中的定义默认值-d, --debug调试日志cli/cmd/root.go#L162默认关闭-p, --pid按 PID 过滤cli/cmd/root.go#L166默认 0 表示全部进程-u, --uid按 UID 过滤cli/cmd/root.go#L167默认 0 表示全部用户-m, --model捕获模式 text/pcap/keylogcli/cmd/tls.go#L53TLS 默认text-w, --pcapfilepcap 输出文件cli/cmd/tls.go#L55默认save.pcapng-k, --keylogfilekeylog 输出文件cli/cmd/tls.go#L54默认ecapture_openssl_key.log-i, --ifname指定网卡TC 挂载点cli/cmd/tls.go#L56默认空-t, --tsizetext 模式截断长度cli/cmd/root.go#L172默认 0 表示不截断-e, --elfpathGoTLS指定 Go 二进制路径见 cli/cmd/gotls.go-e, --errnumberBash/Zsh只展示 exec 结果等于该错误码的命令cli/cmd/bash.go#L38默认 128--hex十六进制输出cli/cmd/root.go#L164--mapsizeeBPF 每 CPU map 大小KBcli/cmd/root.go#L165默认 1024pcap 过滤表达式端口/host 过滤pcap 模式参数尚未覆盖的参数文档标注为 Future Work-b/--btfBTF 模式 0/1/2、-l/--logaddr日志转发、--eventaddr事件收集、--listenHTTP 运行时配置更新、--eventroratesize/--eventroratetime事件文件轮转、--libssl/--gnutls/--nspr自定义库路径仅个别 edge case 涉及、--cgroup_path、--ssl_version。这些 flag 在 cli/cmd/root.go#L168-L172 与 cli/cmd/tls.go#L51-L57 中均有定义属于测试补全的明确缺口对想贡献测试的同学是现成的选题清单。九、执行时间与性能建议测试类别大致耗时备注基础测试2-5 分钟依赖网络速度TLS advanced3-5 分钟依赖网络GoTLS advanced2-4 分钟含 Go 编译耗时Bash advanced1-2 分钟快MySQL advanced2-3 分钟需要 MySQL 运行中Edge cases1-2 分钟快全量10-20 分钟完整 e2e 套件文档给出的四条提速建议并行跑不同模块默认串行执行sudo make e2e-tls sudo make e2e-gotls wait跳过可选测试在脚本中注释掉不需要的用例缩短 sleep 时间适合开发期快速迭代但可能造成误报失败使用本地缓存预下载测试 URL 或改用本地 HTTPS 服务消除外网依赖。十、CI 集成QUICK_REFERENCE.md 给出了可直接套用的 GitHub Actions 示例节选# .github/workflows/e2e-tests.yml name: E2E Tests on: [push, pull_request] jobs: basic-tests: runs-on: ubuntu-latest steps: - uses: actions/checkoutv3 - name: Install dependencies run: | sudo apt-get update sudo apt-get install -y clang llvm golang-go curl - name: Build eCapture run: make nocore - name: Run basic e2e tests run: sudo make e2e-basic - name: Upload test logs on failure if: failure() uses: actions/upload-artifactv3 with: name: test-logs path: /tmp/ecapture_*两个落地要点其一e2e 测试要求特权容器或 VMeBPF 挂载普通 unprivileged runner 跑不了make nocoree2e-basic是文档推荐的 CI 最小集其二失败时按/tmp/ecapture_*上传日志产物正好利用了失败保留日志的清理策略。更完整的 CI 注意事项数据库服务、防火墙对网络用例的影响等见 test/e2e/README.md 的 Continuous Integration 一节。十一、手动执行单个测试脚本不经 Makefile 也可以直接跑脚本适合调试单个场景# 直接执行 cd /path/to/ecapture sudo bash ./test/e2e/tls_text_advanced_test.sh # 带 bash 逐行跟踪 sudo bash -x ./test/e2e/tls_text_advanced_test.sh # 只跑脚本内某几个测试编辑脚本注释掉其他用例后执行 sudo bash ./test/e2e/tls_text_advanced_test.sh注意脚本开头的set -euo pipefail与check_root || exit 1前置检查参见 tls_text_advanced_test.sh#L5-L18root 缺失或工具链不齐时脚本会在入口处直接失败并给出明确日志。十二、新增测试官方模板与规范QUICK_REFERENCE.md 提供了一个最小可用模板完整指引见 test/e2e/README.md 的 Contributing New Tests#!/usr/bin/env bash set -euo pipefail SCRIPT_DIR$(cd $(dirname ${BASH_SOURCE[0]}) pwd) source $SCRIPT_DIR/common.sh TEST_NAMEMy Test ECAPTURE_BINARY$ROOT_DIR/bin/ecapture cleanup_handler() { kill_by_pattern $ECAPTURE_BINARY || true } setup_cleanup_trap main() { check_root || exit 1 build_ecapture $ECAPTURE_BINARY || exit 1 # Your tests here log_success ✓ Tests PASSED } main模板背后的强制约定对照 common.sh 的工具函数即可一一落实统一使用common.sh的工具函数日志、清理、断言不手写彩色 echo必须实现 cleanup handler 并注册trap确保进程与临时目录被清理check_root、build_ecapture放在main入口环境不满足时快速失败断言用verify_content_match等函数失败时自动打印输出样例成功即清理临时目录、失败保留日志与现有脚本的TEST_FAILED约定一致新增 Make 目标形如.PHONY: e2e-mytest e2e-mytest: bash ./test/e2e/my_new_test.sh结语eCapture 的 E2E 套件以 test/e2e/QUICK_REFERENCE.md 为操作入口、test/e2e/README.md 为详细规格、test/e2e/common.sh 为共享基础设施72 个场景覆盖 8 个模块sudo make e2e全量约 10-20 分钟参数覆盖清单明确列出了已测与待测边界CI 只需特权执行环境加/tmp/ecapture_*日志上传即可接入。排障时记住三条主线——内核版本x86_64 ≥ 4.18 / aarch64 ≥ 5.5、root 权限、失败现场日志保留在/tmp/ecapture_module_test_pid/output/配合-d调试日志与dmesg基本可以定位绝大多数挂载与流量问题。环境要求速记Linux 内核 ≥ 4.18按架构、root 权限、curl/go/bash必备MySQL/PostgreSQL/Zsh/tshark/tcpdump 按模块可选。【免费下载链接】ecaptureCapturing SSL/TLS plaintext without a CA certificate using eBPF. Supported on Linux/Android kernels for amd64/arm64.项目地址: https://gitcode.com/GitHub_Trending/ec/ecapture创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考