Testing Strategy and CI/CD ​

The eCapture project employs a multi-layered testing strategy to ensure the reliability of eBPF-based capture across diverse Linux kernels and architectures. This strategy spans from local Go unit tests for userspace logic to comprehensive End-to-End (E2E) tests running on real hardware/virtualized kernels, integrated into a robust GitHub Actions CI/CD pipeline.

1. Testing Layers ​

1.1 Go Unit Tests ​

Unit tests focus on the userspace control plane and event processing logic. These tests do not require root privileges or eBPF capabilities as they use mocked data or recorded event streams.

• Event Processor: Validates the scheduling loop, UUID-based affinity, and event reconstruction. The TestEventProcessor_Serve function uses JSON-serialized events and binary payloads to simulate kernel-to-userspace data flow pkg/event_processor/processor_test.go:31-114.
• Protocol Parsers: Tests the IParser implementations (HTTP/1.1, HTTP/2) against known byte streams to ensure correct plaintext extraction pkg/event_processor/processor_test.go:97-101.
• Truncation Logic: Ensures that large payloads are correctly handled according to configuration limits pkg/event_processor/processor_test.go:116-196.

1.2 End-to-End (E2E) Tests ​

E2E tests are the core of eCapture's validation. They run on real Linux environments and execute actual captures against target applications.

• TLS/OpenSSL: Uses curl to generate traffic and verifies that eCapture extracts the expected plaintext (e.g., "GitHub" from an API response) test/e2e/tls_e2e_test.sh:59-145.
• GnuTLS: Verifies hooks on libgnutls by using compatible versions of wget or curl test/e2e/gnutls_e2e_test.sh:125-220.
• GoTLS: Employs a custom Go HTTPS client to test the gotls probe, verifying support for Go's internal ABI test/e2e/gotls_e2e_test.sh:118-213.
• eCaptureQ: Tests the WebSocket streaming mechanism by running ecaptureq_client alongside the main probe .github/workflows/e2e.yml:95-101.

1.3 Security and Quality Scans ​

• CodeQL: Automated static analysis for Go and C (eBPF) code to detect security vulnerabilities and logic errors .github/workflows/codeql-analysis.yml:24-35.
• Codecov: Tracks test coverage to identify untested paths in the userspace logic .github/workflows/codeql-analysis.yml:90-93.

2. CI/CD Architecture ​

The CI/CD system is built on GitHub Actions, automating the build, test, and release cycles for multiple architectures (x86_64 and arm64).

Build and Test Pipeline Data Flow ​

This diagram illustrates the flow from a Pull Request to a verified build artifact.

Diagram: PR Validation and E2E Pipeline

Sources: .github/workflows/e2e.yml:1-22, .github/workflows/pr_build_debug.yml:1-22, .github/workflows/codeql-analysis.yml:12-35

Multi-Arch Build Strategy ​

eCapture uses a matrix strategy to build for both Linux and Android across different CPU architectures.

Sources: .github/workflows/pr_build_debug.yml:19-22, .github/workflows/pr_build_debug.yml:33-60

3. Implementation Details ​

3.1 E2E Test Framework ​

The E2E tests are orchestrated via Bash scripts that manage the lifecycle of the eCapture process and the target client.

• Setup: Checks for root privileges and kernel version compatibility test/e2e/common.sh:32-59.
• Execution: Launches eCapture in the background, waits for initialization, then triggers the network event test/e2e/tls_e2e_test.sh:66-83.
• Verification: Uses grep to verify plaintext patterns and checks for "Failed to decode event" errors to catch struct alignment regressions test/e2e/tls_e2e_test.sh:101-110.
• Cleanup: A trap-based cleanup_handler ensures that eCapture processes are killed and temporary logs are handled test/e2e/tls_e2e_test.sh:29-48.

3.2 Automated Release Pipeline ​

When a tag is pushed, the builder/Makefile.release is invoked to create production-ready binaries.

1. Environment Prep: Installs llvm, clang, and linux-source .github/workflows/pr_build_debug.yml:33-47.
2. Compilation: Runs make release which compiles both CO-RE and non-CO-RE versions .github/workflows/pr_build_debug.yml:67-75.
3. Packaging: Bundles binaries into .tar.gz and generates checksums.

Diagram: Event Processor Unit Test Data Flow

Sources: pkg/event_processor/processor_test.go:44-77, pkg/event_processor/base_event.go:76-87

4. Key Testing Files ​

Sources: .github/workflows/e2e.yml:1-22, test/e2e/common.sh:1-12, pkg/event_processor/processor_test.go:1-30, test/e2e/tls_text_advanced_test.sh:1-15