{"id":27939611,"url":"https://github.com/maxgio92/xcover","last_synced_at":"2026-02-27T13:15:14.869Z","repository":{"id":290043217,"uuid":"949030769","full_name":"maxgio92/xcover","owner":"maxgio92","description":"Profile coverage of functional tests without instrumenting your binaries.","archived":false,"fork":false,"pushed_at":"2025-08-22T18:20:52.000Z","size":23670,"stargazers_count":6,"open_issues_count":6,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-08-22T20:59:56.549Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/maxgio92.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-03-15T14:16:34.000Z","updated_at":"2025-08-22T18:20:53.000Z","dependencies_parsed_at":null,"dependency_job_id":"d7f869b9-a2db-43a8-af80-4923c5a78e09","html_url":"https://github.com/maxgio92/xcover","commit_stats":null,"previous_names":["maxgio92/xcover"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/maxgio92/xcover","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maxgio92%2Fxcover","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maxgio92%2Fxcover/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maxgio92%2Fxcover/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maxgio92%2Fxcover/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/maxgio92","download_url":"https://codeload.github.com/maxgio92/xcover/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maxgio92%2Fxcover/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":274949581,"owners_count":25379446,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-13T02:00:10.085Z","response_time":70,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-05-07T09:55:33.490Z","updated_at":"2026-02-27T13:15:14.853Z","avatar_url":"https://github.com/maxgio92.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"# xcover\n\n[![CI](https://github.com/maxgio92/xcover/actions/workflows/ci.yml/badge.svg)](https://github.com/maxgio92/xcover/actions/workflows/ci.yml)\n[![Release](https://img.shields.io/github/v/tag/maxgio92/xcover)](https://github.com/maxgio92/xcover/releases)\n[![License](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)\n\n**Profile functional test coverage without instrumenting your binaries.**\n\n`xcover` (pronounced \"cross cover\") revolutionizes functional test coverage profiling by leveraging kernel instrumentation to probe userland functions. This cross-language approach measures coverage directly from ELF binaries, eliminating the need for ecosystem-specific tools like [Go cover](https://go.dev/doc/build-cover) or [LLVM cov](https://llvm.org/docs/CommandGuide/llvm-cov.html).\n\n[![asciicast](https://asciinema.org/a/GyzGzTTEP63GJzAG.svg)](https://asciinema.org/a/GyzGzTTEP63GJzAG)\n\n## Quickstart\n\nGet started with xcover in seconds. Launch the profiler in daemon mode, run your tests, then collect comprehensive coverage metrics:\n\n```shell\n$ xcover run --detach --path /path/to/bin\n$ xcover wait\nxcover is ready\n$ /path/to/bin test1\n$ /path/to/bin test2\n$ /path/to/bin test3\n$ xcover stop\nxcover is stopped\n$ cat xcover_report.json | jq .cov_by_func\n89.9786897\n```\n\n## How It Works\n\nxcover operates at the kernel level, instrumenting your binary's functions through eBPF probes. This unique approach provides several advantages:\n\n- **Language-agnostic profiling**: Works with any compiled binary\n- **Non-invasive instrumentation**: No source code modifications required\n- **Production-ready**: Minimal overhead with kernel-level efficiency\n- **Comprehensive coverage**: Traces all function calls in real-time\n\nThe profiler runs as a daemon, monitoring function invocations as your tests execute. Once complete, xcover generates detailed coverage reports showing exactly which functions were exercised.\n\n## Filter\n\nTarget specific processes, binaries, or functions to focus your coverage analysis.\n\n### Filter by Process\n\nProfile a specific running process by PID:\n\n```shell\nxcover run --pid PID\n```\n\n### Filter by Binary\n\nTarget a specific executable path:\n\n```shell\nxcover run --path EXE_PATH\n```\n\n### Filter Functions\n\nInclude specific functions using regex patterns:\n\n```shell\nxcover run --path EXE_PATH --include \"^github.com/maxgio92/xcover\"\n```\n\nExclude functions you don't want to trace:\n\n```shell\nxcover run --path EXE_PATH --exclude \"^runtime.|^internal\"\n```\n\n## Symbolization\n\nxcover relies on symbolization to discover function names and addresses within target binaries. Understanding how symbolization works helps you maximize coverage profiling effectiveness.\n\n### Symbol Table\n\nELF binaries contain a symbol table with function metadata, including names and memory addresses. xcover consumes this table to identify traceable functions. When you apply filters (`--include`, `--exclude`), they operate against these discovered symbols.\n\n### Stripped Binaries\n\nProduction binaries often strip the standard symbol table (`.symtab`) to reduce size, removing the metadata xcover needs for standard profiling. To handle stripped binaries, xcover implements language-specific fallback mechanisms.\n\n#### Go\n\nxcover seamlessly supports stripped Go binaries by reading the `.gopclntab` (Go Program Counter Line Table) section. This metadata structure persists even after stripping, providing complete function information for coverage analysis.\n\nThe Go symbolization fallback:\n- Activates automatically when `.symtab` is unavailable\n- Supports Go 1.2+ binaries\n- Maintains full compatibility with symbol filtering\n- Requires no additional configuration\n\n## Daemon Mode\n\nRun xcover as a background daemon for flexible test execution. This mode enables you to start the profiler, run multiple test suites, and collect results when complete.\n\nLaunch the daemon with the `--detach` flag:\n\n```shell\n$ xcover run --detach --path /path/to/bin\n```\n\nCheck the profiler status:\n\n```shell\n$ xcover status\nxcover is running (PID 1234)\n```\n\nStop the daemon and collect results:\n\n```shell\n$ xcover stop\nxcover is stopped\n```\n\n## Report\n\nxcover automatically generates comprehensive coverage reports in JSON format, detailing traced functions, acknowledged functions, coverage percentages, and executable information.\n\n### Report Structure\n\nThe coverage report follows this schema:\n\n```go\ntype CoverageReport struct {\n\tFuncsTraced []string `json:\"funcs_traced\"`\n\tFuncsAck    []string `json:\"funcs_ack\"`\n\tCovByFunc   float64  `json:\"cov_by_func\"`\n\tExePath     string   `json:\"exe_path\"`\n}\n```\n\n### Generating Reports\n\nEnable reporting with the `--report` flag when running your profiler:\n\n```shell\n$ xcover run --path myapp --verbose=false --report\n^C5:02PM INF written report to xcover-report.json\n$ cat xcover-report.json | jq '.cov_by_func'\n15.601900739176347\n```\n\n## Synchronization\n\nSynchronize test execution with xcover's readiness state to ensure accurate coverage capture. The `wait` command blocks until the profiler has fully initialized and begun tracing all target functions.\n\n### Synchronization Workflow\n\nUse the `wait` command to coordinate profiler initialization with test execution:\n\n```shell\n$ xcover run --detach --path /path/to/bin\n$ xcover wait\n1:30PM INF waiting for the profiler to be ready\n1:30PM INF profiler is ready\n$ /path/to/bin test_1\n$ /path/to/bin test_2\n$ /path/to/bin test_3\n$ xcover stop\n```\n\nThe coverage report will be available as `xcover-report.json` after stopping the profiler.\n\n## CLI Reference\n\n## xcover\n\nxcover is a functional test coverage profiler\n\n### Synopsis\n\n\nxcover is a functional test coverage profiler.\n\nRun the 'run' command to run the profiler that will trace all the functions of the tracee program.\nWait for the profiler to be ready before running your tests, with the 'wait' command.\nOnce the profiler is ready to trace all the functions, you can start running your tests.\nAt the end of your tests, the profiler can be stopped and a report being collected.\n\n\n### Options\n\n```\n  -h, --help               help for xcover\n      --log-level string   Log level (trace, debug, info, warn, error, fatal, panic) (default \"info\")\n```\n\n### SEE ALSO\n\n* [xcover run](docs/xcover_run.md)\t - Run the coverage profiling for a program\n* [xcover status](docs/xcover_status.md)\t - Check the the xcover profiler status\n* [xcover stop](docs/xcover_stop.md)\t - Stop the xcover profiler daemon\n* [xcover wait](docs/xcover_wait.md)\t - Wait for the xcover profiler to be ready\n\n\n\n## Development\n\n### Prerequisites\n\n- `bpftool` (to generate vmlinux.h for CORE)\n- `clang`\n- `go`\n- `libbf-dev`\n\n### Build All\n\nBy default, xcover compiles statically with libbpfgo, linking libbpfgo with libbpf:\n\n```shell\nmake xcover\n```\n\n### Build BPF Only\n\nCompile only the BPF components:\n\n```shell\nmake xcover/bpf\n```\n\n### Build Frontend Only\n\nCompile only the frontend application:\n\n```shell\nmake xcover/frontend\n```\n\n### Run Tests\n\nExecute the test suite:\n\n```shell\nmake test\n```\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmaxgio92%2Fxcover","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmaxgio92%2Fxcover","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmaxgio92%2Fxcover/lists"}