Building an Incremental iOS Code Coverage Tool Integrated with Git

Background

iOS developers face long App Store review cycles, so detecting bugs early through code coverage is crucial for preventing production incidents. Coverage helps assess self‑test thoroughness and code redundancy, yet iOS projects often lack effective coverage tools.

Problems with Existing Tools

Third‑party tools may produce broken reports and developers often do not understand the coverage generation process.

Full‑project reports distract developers from the newly changed code they care about.

Xcode’s built‑in coverage works only for unit tests, which are costly to maintain for fast‑changing features.

Most tools cannot be seamlessly integrated into existing CI pipelines.

Coverage Generation Basics

When compiling with Clang, the compiler emits .gcno files that map source lines to counters, and runtime execution creates .gcda files containing execution counts. The LLVM GCOVPass inserts counting instructions into the IR without modifying source files.

.gcno Generation

The pass creates a .gcno file by writing a magic number, then for each function records its name, source range, and basic‑block (BB) information, including BB IDs, start/end lines, and successor edges.

IR Instrumentation Logic

LLVM treats each basic block as a single‑entry, single‑exit unit; inserting a counter at the block’s entry ensures all instructions in the block are counted once. The instrumentation loops over functions and their BBs, allocating an array ctr[n] for each BB’s successors and recording execution counts.

void __gcov_flush() { struct flush_fn_node *curr = flush_fn_head; while (curr) { curr->fn(); curr = curr->next; } }

.gcda Generation

The runtime calls __gcov_flush(), which traverses a linked list of flush functions and writes coverage data to .gcda. The process includes creating the file, emitting function info, arcs (BB execution counts), summary info, and an end marker.

Design of an Incremental Coverage Tool

To avoid the drawbacks of full‑project instrumentation, the team chose to filter coverage at the .info stage (the intermediate file produced by lcov). This approach keeps the workflow transparent, allows incremental reports, and can be added to existing pipelines without modifying the build system.

Implementation Highlights

Only local Pods (identified via Podfile) are instrumented, reducing compile‑time impact.

A Git pre‑push hook is automatically injected via CocoaPods’ script_phase, ensuring coverage data is flushed before pushes.

When a branch or loop change adds new edges, the tool discards stale .gcda files because the old .gcno no longer matches, preventing merge conflicts.

Overall Workflow

Developers commit code as usual; the pre‑push hook triggers coverage collection, filters the .info file to retain only the changed lines, generates an HTML report via lcov’s genhtml, and optionally blocks pushes if coverage falls below a configurable threshold (e.g., 80%).

Conclusion

The incremental iOS coverage tool demonstrates how deep understanding of LLVM’s gcov instrumentation, combined with Git‑aware filtering, can provide developers with precise, change‑focused coverage metrics, improving code quality and reducing production risk.