企业官网建设流程全解析

ecapture E2E 测试套件实战指南：70+ 场景端到端验证 eBPF 捕获能力

【免费下载链接】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

本文基于 ecapture 仓库的test/e2e/README.md及其配套的测试脚本、Makefile 目标与公共测试库，完整讲解 ecapture 端到端（E2E）测试套件的设计结构、运行方式与结果判定方法。读完本文，你将能够独立搭建 E2E 测试环境、按模块运行 70+ 个测试场景、读懂测试输出并定位失败原因，还能按官方模板向套件中扩展新的测试脚本。

E2E 测试套件概览

ecapture 的核心能力是通过 eBPF 无侵入地捕获 SSL/TLS 明文（无需 CA 证书），支持 OpenSSL/BoringSSL、GoTLS、GnuTLS、NSPR/NSS 等 TLS 库，以及 Bash/Zsh 命令、MySQL/PostgreSQL 查询等 8 个核心模块。要验证这些捕获能力真实可用，仓库提供了位于 test/e2e/ 目录的综合 E2E 测试套件：

• 覆盖全部 8 个核心模块及多种参数组合；
• 测试需在具有 root 权限、内核版本合适的 Linux 系统上运行；
• 按“基础测试 + 高级测试 + 边界用例”三层组织，总计 70+ 个测试场景。

套件目录中的关键文件如下（相对于仓库根目录）：

环境前置条件与构建 eCapture

系统要求

• 操作系统：Linux，x86_64 内核 ≥ 4.18，或 aarch64 内核 ≥ 5.5（CO-RE 模式的最低要求）；
• 权限：必须使用 ROOT 权限运行测试；
• 工具：curl、go、bash为必需；mysql、postgresql、zsh、tshark、tcpdump为可选（缺失时相应测试降级或跳过）。

构建 ecapture

make all # Build with eBPF CO-RE support # or make nocore # Build without CO-RE (fallback)

构建产物为bin/ecapture，所有 E2E 脚本默认以$ROOT_DIR/bin/ecapture作为被测二进制。值得注意的一点是：公共库 common.sh 中的build_ecapture函数会自动处理构建——若二进制不存在，先尝试make all -j 4，失败后回退到make nocore -j 4，只有两者都失败才报错退出。这意味着测试脚本对 CO-RE 支持不佳的旧环境有一定的自动容错能力。

测试结构：基础测试、高级测试与边界用例

1. 基础测试（test/e2e/*_e2e_test.sh）

每个模块一个基础功能脚本：

• bash_e2e_test.sh— Bash 命令捕获；
• zsh_e2e_test.sh— Zsh 命令捕获；
• mysql_e2e_test.sh— MySQL 查询捕获；
• postgres_e2e_test.sh— PostgreSQL 查询捕获；
• tls_e2e_test.sh— TLS 模块的 text/pcap/keylog 三种模式；
• gnutls_e2e_test.sh— GnuTLS 捕获；
• gotls_e2e_test.sh— GoTLS 捕获。

以 tls_e2e_test.sh 为例，脚本先source common.sh引入公共工具，定义TEST_URL="https://api.github.com"作为流量源，然后依次执行三个模式测试函数：

• test_text_mode：后台启动ecapture tls -m text，sleep 3等待 eBPF 挂载完成后用curl -v发起 HTTPS 请求，再通过kill -0确认进程未死机，并校验输出中包含 HTTP 明文特征；
• test_pcap_mode：验证 pcapng 输出文件生成；
• test_keylog_mode：校验 keylog 文件中包含标准的CLIENT_RANDOM条目（标准 NSS keylog 格式）。

脚本还实现了cleanup_handler清理函数：通过kill_by_pattern按命令模式杀掉残留的 ecapture 进程，测试失败时自动打印ecapture.log与client.log便于调试，成功后删除临时目录。

2. 高级测试（test/e2e/*_advanced_test.sh）

高级测试针对参数变体和边界条件，具体覆盖如下：

TLS 模块（24 个场景，3 个脚本各 8 个测试）：

• tls_text_advanced_test.sh：HTTP/1.1 与 HTTP/2 捕获、PID/UID 过滤、并发连接、文本截断（-t参数）、调试模式（-d）、十六进制输出（--hex）；
• tls_pcap_advanced_test.sh：pcapng 基础模式、端口/host 过滤器、网卡指定（-i）、并发连接、PID 过滤、tshark 兼容性验证、--mapsize配置；
• tls_keylog_advanced_test.sh：keylog 基础模式、TLS 1.2 与 TLS 1.3 连接、并发连接、PID/UID 过滤、keylog 格式校验（CLIENT_RANDOM）、tcpdump 集成验证。

GoTLS 模块：gotls_advanced_test.sh共 7 个测试，覆盖 text/pcap/keylog 三种模式、Go client-server 通信、多并发连接、静态 vs 动态链接（CGO_ENABLED=0）、调试模式。Go 测试客户端由脚本动态编译（见 go_https_client.go 与 examples 下的示例客户端）。

Bash 模块：bash_advanced_test.sh共 8 个测试，覆盖管道命令（|）、重定向（>、>>）、后台任务（&）、子 shell（()、$()）、超长命令行、特殊字符处理、错误码过滤（-e参数）、交互式会话模拟。

MySQL 模块：mysql_advanced_test.sh共 7 个测试，覆盖 SELECT/INSERT/UPDATE/DELETE、事务处理（BEGIN/COMMIT）、长 SQL 语句、并发查询。

3. 边界用例与错误处理（15 个场景）

edge_cases_test.sh 验证 ecapture 在非法输入与异常环境下的健壮性。从源码可以看到 15 个独立测试函数，每个对应一类异常：

• 不存在的 PID / UID、负数 PID 值；
• 无效的库路径（--libssl指向不存在的文件）；
• 无效网卡、非法 BPF 过滤器表达式；
• 信号处理（SIGINT、SIGTERM优雅退出）；
• 只读输出目录、空 pcap 文件名；
• 非法 BTF 模式值、超大--mapsize；
• 不存在的 GoTLS 二进制（-e）、无数据库服务时运行 MySQL 探测、截断大小为 0 的边界值。

这类测试的价值在于：eBPF 工具对错误参数的表现（是崩溃、报错还是静默忽略）直接影响生产环境中的运维体验，边界用例保证了“失败得体的”行为被持续回归验证。

测试覆盖矩阵与参数覆盖

模块覆盖

总计：70+ 个测试场景。

参数覆盖

套件覆盖的 CLI 参数可对照 cli/cmd/ 下各子命令源码逐一印证：

全局参数：-d/--debug（调试日志）、-p/--pid（进程过滤）、-u/--uid（用户过滤）、--hex（十六进制输出）、--mapsize（eBPF map 大小）、-t/--tsize（文本截断长度）。

TLS 模块参数：-m/--model（text/pcap/pcapng/key/keylog 模式）、-w/--pcapfile、-k/--keylogfile、-i/--ifname、--libssl（自定义 libssl 路径，边界用例中覆盖）、pcap 过滤器表达式。

GoTLS 模块参数：-e/--elfpath（Go 二进制路径）、-m、-w、-k。

Bash/Zsh 模块参数：-e/--errnumber（错误码过滤）、--bash/--zsh（自定义 shell 路径，边界用例覆盖）。

MySQL/Postgres 模块参数：--pid（数据库服务 PID）、-m/--mysqld与-m/--postgres（数据库二进制路径）。

运行测试：Makefile 目标与直接执行

一键运行全部测试

# Run all basic + advanced tests (requires root) sudo make e2e

运行基础测试

sudo make e2e-basic # 运行全部基础测试 sudo make e2e-bash # 指定模块 sudo make e2e-zsh sudo make e2e-mysql sudo make e2e-postgres sudo make e2e-tls sudo make e2e-gnutls sudo make e2e-gotls

从 Makefile 实际的目标依赖看，e2e-basic聚合的是e2e-bash e2e-tls e2e-gnutls e2e-gotls四个不依赖数据库服务的基础测试，zsh/mysql/postgres 需要各自环境就绪，通常单独运行。

运行高级测试

sudo make e2e-advanced sudo make e2e-tls-text-advanced sudo make e2e-tls-pcap-advanced sudo make e2e-tls-keylog-advanced sudo make e2e-gotls-advanced sudo make e2e-bash-advanced sudo make e2e-mysql-advanced sudo make e2e-edge-cases

Makefile 中e2e-advanced目标实际依赖链还包含e2e-ecaptureq（Makefile），即 ecaptureq_e2e_test.sh 也会随之运行。该测试验证--ecaptureq标志下 ecapture 打开 WebSocket 服务（默认端口 28257），examples/ecaptureq_client中的示例客户端连接后能收到 protobuf 编码的 TLS 捕获事件——这是验证事件转发链路（pkg/ecaptureq的 hub/server 实现）的端到端用例。

此外，Makefile 还定义了 Android 目标：e2e-android-tls、e2e-android-gotls与e2e-android-all，对应 test/e2e/android/ 下的设备端测试脚本。

直接执行单个脚本

sudo bash ./test/e2e/tls_text_advanced_test.sh sudo bash ./test/e2e/gotls_advanced_test.sh

轻量级 smoke 测试

run_e2e.sh 提供一条不依赖完整环境的路径：环境检查（go/clang）、make clean后重新构建、验证bin/ecapture存在，然后运行--help、--version、tls -h等无侵入命令，并把输出保存到/tmp/ecapture_*.txt。适合在权限受限的环境里快速验证构建产物可用。

测试输出与日志规范

结果指示符

• ✓（绿色）：测试通过。通过的判据包括：进程成功启动、捕获到预期数据模式、输出文件（pcap/keylog）已创建、格式校验通过（pcap 魔数、CLIENT_RANDOM等）；
• ⚠（黄色）：测试完成但验证受限，如可选工具缺失（tshark 未安装）或环境特定限制；
• ✗（红色）：测试失败，常见原因包括：进程启动期间死亡、未捕获到任何输出、预期模式未找到。

日志与清理策略

• 临时输出目录形如/tmp/ecapture_<module>_<test>_<pid>/output/（各脚本内以/tmp/ecapture_tls_e2e_$$这类$$后缀目录实现）；
• 测试失败时日志自动保留，供调试；测试成功时自动清理——这一策略由每个脚本的cleanup_handler与trap ... EXIT INT TERM（setup_cleanup_trap）实现；
• 失败时脚本会直接catecapture 日志与客户端日志，快速定位问题。

三个常见测试模式

以下模式是所有测试脚本的骨架，编写新测试时可直接复用：

模式 1：基础捕获测试

# Start ecapture ecapture <module> -m text > output.log 2>&1 & sleep 3 # Generate traffic curl https://example.com # Stop ecapture kill -INT $pid sleep 2 # Verify output grep -q "HTTP" output.log

要点：sleep 3是等待 eBPF 程序挂载与库偏移检测完成的关键窗口；“进程完成太快”是“无输出”类失败的第一嫌疑，需要延长等待。

模式 2：参数校验测试

# Test with invalid parameter timeout 5 ecapture <module> --invalid-param > output.log 2>&1 # Verify error message grep -qi "error" output.log

模式 3：信号处理测试

ecapture <module> > output.log 2>&1 & pid=$! kill -INT $pid sleep 2 # Verify graceful shutdown ! kill -0 $pid 2>/dev/null

验证发送 SIGINT 后进程能在合理时间内优雅退出，而不是挂死或被外部强杀。

公共测试基础设施：common.sh 源码解析

common.sh 是所有测试脚本共享的工具库，其关键函数决定了测试的一致性：

• check_root（common.sh）：通过$EUID判断是否 root，非 root 直接报错退出；
• check_kernel_version 4 18（common.sh）：解析uname -r并按主次版本号比较，低于 4.18 拒绝运行——对应 CO-RE 构建的最低内核要求；
• build_ecapture（common.sh）：二进制不存在时先make all -j 4，失败回退make nocore -j 4；
• verify_text_in_output/verify_content_match（common.sh）：grep -q校验捕获文件中是否存在预期模式，未命中时打印完整输出辅助排查；
• print_captured_content（common.sh）：先剔除带INF/DBG/WRN/ERR时间戳的日志行，再匹配 HTTP 请求头特征（GET、POST、Host:等）打印前 N 行预览，让测试报告直观展示“到底抓到了什么”；
• check_library_linkage（common.sh）：用ldd确认被测二进制确实链接了目标 TLS 库——避免“被测程序根本没用到被测库”导致的假阴性；
• kill_by_pattern/setup_cleanup_trap：按pgrep -f模式清理残留进程，先kill后kill -9，保证测试间互不污染。

故障排查

"Root privileges required"：使用sudo运行测试。

"Kernel version check failed"：升级内核至 x86_64 ≥ 4.18 或 aarch64 ≥ 5.5。

"eCapture binary not found"：先执行make all或make nocore构建。

"MySQL/PostgreSQL not available"：安装并启动数据库服务，或单独跳过数据库测试（e2e-mysql/e2e-postgres独立于e2e-basic聚合链）。

"No output captured"：可能原因包括——目标进程结束过快（延长 sleep）、未生成匹配的流量、权限问题、eBPF 程序挂载失败（可查看dmesg确认）。

调试模式：

ecapture <module> -d > debug.log 2>&1

调试日志可用于确认：eBPF 程序挂载状态、hook 函数位置、事件捕获细节与错误信息。也可以sudo bash -x ./test/e2e/tls_text_advanced_test.sh追踪测试脚本自身的执行流。

CI 集成

测试套件对 CI 友好的设计考虑：

• 测试需要特权容器或 VM（eBPF 挂载要求）；
• 部分测试对特定内核版本敏感；
• 数据库测试需要正在运行的服务；
• 网络测试可能受防火墙规则影响。

示例的 CI workflow（摘自 README，可按需裁剪）：

jobs: e2e-tests: runs-on: ubuntu-latest steps: - name: Checkout uses: actions/checkout@v3 - name: Install dependencies run: | sudo apt-get update sudo apt-get install -y clang llvm golang - name: Build ecapture run: make nocore - name: Run basic e2e tests run: sudo make e2e-basic

CI 中选择make nocore是因为 CI 镜像的内核未必提供 BTF（CO-RE 依赖），无 CO-RE 构建是更保守的选择。

扩展测试套件：模板与规范

测试文件模板

官方给出的新测试脚本骨架（节选自 README 模板，可直接复制改写）：

#!/usr/bin/env bash set -euo pipefail SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" ROOT_DIR="$(cd "$SCRIPT_DIR/../.." && pwd)" source "$SCRIPT_DIR/common.sh" # Configuration TEST_NAME="My New Test" ECAPTURE_BINARY="$ROOT_DIR/bin/ecapture" TMP_DIR="/tmp/ecapture_mytest_$$" # Cleanup cleanup_handler() { kill_by_pattern "$ECAPTURE_BINARY" || true rm -rf "$TMP_DIR" } setup_cleanup_trap # Tests test_something() { log_info "=== Test: Something ===" # Test implementation } # Main main() { check_root || exit 1 check_kernel_version 4 18 || exit 1 mkdir -p "$TMP_DIR" build_ecapture "$ECAPTURE_BINARY" || exit 1 test_something || true log_success "✓ All tests PASSED" } main

注册到 Makefile

.PHYONY: e2e-mytest e2e-mytest: bash ./test/e2e/my_new_test.sh

十条测试编写准则

1. 使用common.sh工具函数保证一致性；
2. 始终实现 cleanup handler；
3. 让脚本可执行（chmod +x test.sh）；
4. 使用描述性测试名；
5. 清晰记录测试进度；
6. 同时验证成功与失败两种情况；
7. 成功时清理，失败时保留现场；
8. 使用合适的超时；
9. 优雅处理缺失依赖（降级为 warn/skip 而非整体失败）；
10. 文档化特殊要求。

测试维护与未来规划

定期维护事项

• 新增 CLI 参数时同步更新测试（参数覆盖矩阵是回归基线）；
• 为新版本 OpenSSL/其他 TLS 库补充测试；
• 随内核演进更新内核版本检查；
• 外部测试 URL 变更时刷新（当前如https://api.github.com）；
• 捕获输出格式变化时更新预期模式（如CLIENT_RANDOM校验逻辑）。

规划中的测试（README 中的 Planned 清单）

• NSPR/NSS 模块综合测试（当前 0 覆盖）；
• GnuTLS 进阶场景、PostgreSQL 进阶测试（事务、存储过程）、Zsh 进阶测试；
• 性能基准与长时间稳定性测试；
• BTF 模式变体（-b 0/1/2）、日志转发（-l）、事件采集（--eventaddr）、HTTP 配置更新（--listen）、文件轮转、资源占用校验、多进程协同捕获。

问题反馈所需信息

排查或提交 issue 时，附上：内核版本（uname -r）、完整测试输出/日志、系统信息、复现步骤；现场日志优先检查/tmp/ecapture_*目录。

小结

ecapture 的 E2E 测试套件以test/e2e/README.md为总纲，用“基础功能 → 参数变体 → 非法输入”三层递进的结构，把 8 个捕获模块、20+ 个 CLI 参数和 15 个边界场景纳入了可重复的回归验证中。配合 Makefile 中清晰的 target 划分、common.sh 统一的校验与清理工具、以及失败保留日志的策略，开发者既可以用sudo make e2e一键跑全量，也可以按模块、按参数维度做精准回归；新增测试时照官方模板实现并注册 Makefile 目标，即可无缝融入现有体系。

【免费下载链接】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