Code & Doc Coverage

Rust에서 코드 커버리지와 문서 커버리지 관리하기

Rust 프로젝트를 운영하다 보면 커버리지(Coverage)라는 용어를 자주 보게 된다.

커버리지는 크게 두 종류로 나뉜다.

• 코드 커버리지 (Code Coverage)
• 문서 커버리지 (Docstring Coverage)

둘은 완전히 다른 지표이며 각각 별도로 관리해야 한다.

코드 커버리지는 코드 품질 관리를 위해 꼭 필요하다. (평균: 80% ~ 90%)
문서 커버리지는 오픈소스 프로젝트를 운영한다면 다른 기여자를 위해 또는 crates.io를 통해 사용하게 되는 사용자를 위해서 꼭 필요하다.

1. 코드 커버리지 (Code Coverage)

코드 커버리지는 테스트가 실제 코드를 얼마나 실행했는지 측정하는 지표이다.

예를 들어 다음과 같은 코드가 있다고 가정하자.

pub fn add(a: i32, b: i32) -> i32 {
    a + b
}

pub fn sub(a: i32, b: i32) -> i32 {
    a - b
}

테스트가 add()만 실행한다면 sub()는 테스트되지 않은 상태가 된다.

설치

cargo install cargo-llvm-cov

커버리지 확인

cargo llvm-cov

워크스페이스 전체 확인

cargo llvm-cov --workspace

HTML 리포트 생성

cargo llvm-cov --workspace --html

생성 위치

target/llvm-cov/html/index.html

HTML 리포트를 열어보면 실행된 코드는 초록색, 실행되지 않은 코드는 빨간색으로 표시된다.

LCOV 생성 (CI 용도)

cargo llvm-cov --workspace --lcov --output-path lcov.info

Codecov 등의 서비스와 연동할 때 사용한다.

---

2. 문서 커버리지 (Docstring Coverage)

문서 커버리지는 공개 API에 문서가 얼마나 작성되어 있는지 측정하는 지표이다.

다음 코드는 문서가 없는 상태이다.

pub struct NoteService;

pub fn add_note() {}

문서를 추가하면 다음과 같다.

/// Service for managing notes.
pub struct NoteService;

/// Adds a new note.
pub fn add_note() {}

---

공개 API 문서 강제하기

Rust에서는 missing_docs lint를 사용할 수 있다.

경고 수준

#![warn(missing_docs)]

오류 수준

#![deny(missing_docs)]

문서가 없는 공개 API에 대해 경고 또는 오류를 발생시킨다.

---

문서 생성

API 문서 생성

cargo doc --no-deps

문서 열기

cargo doc --open

생성된 Rust API 문서를 브라우저에서 확인할 수 있다.

---

공개 API 목록 확인

설치

cargo install cargo-public-api

실행

cargo public-api

예시

pub struct Note
pub struct NoteService
pub fn add_note
pub fn delete_note

문서화해야 할 공개 API를 빠르게 확인할 수 있다.

---

개인적인 권장 기준

작은 오픈소스 프로젝트 기준

코드 커버리지

60% 이상   : 양호
70~80%     : 권장
80~90%     : 우수

문서 커버리지

• 공개 API (pub)는 문서 작성
• 내부 구현 (fn, pub(crate))은 필요할 때만 작성

---

자주 사용하는 명령어 정리

# 코드 커버리지
cargo llvm-cov

# 워크스페이스 커버리지
cargo llvm-cov --workspace

# HTML 리포트
cargo llvm-cov --workspace --html

# LCOV 생성
cargo llvm-cov --workspace --lcov --output-path lcov.info

# API 문서 생성
cargo doc --no-deps

# API 문서 열기
cargo doc --open

# 공개 API 확인
cargo public-api

Rust 오픈소스 프로젝트에서는 일반적으로 테스트 커버리지와 공개 API 문서화를 함께 관리한다. 코드 커버리지는 기능의 안정성을, 문서 커버리지는 사용성과 유지보수성을 높여준다.