이번 글에서 다룰 내용
테스트와 문서화는 코드 신뢰도를 높이는 가장 직접적인 방법입니다. cargo test 명령 흐름, #[test] 함수 작성법, 문서 주석으로 예제를 남기는 법을 차근차근 따라갑니다.
cargo test 살펴보기
Rust 프로젝트를 생성했다면 별도 설정 없이도 cargo test를 실행할 수 있습니다.
cargo new calculator
cd calculator
cargo test
기본 템플릿에는 자동으로 하나의 예시 테스트가 들어 있어서, 위 명령을 실행하면 바로 테스트 러너가 동작하는 것을 확인할 수 있습니다. 실패 메시지가 아니라면 러닝타임, 테스트 개수, 패키지 이름이 출력됩니다.
#[test] 함수 작성하기
src/lib.rs에 기능 함수를 추가하고 함께 테스트를 작성해 보겠습니다.
pub fn add(a: i32, b: i32) -> i32 {
a + b
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn adds_two_numbers() {
assert_eq!(add(2, 3), 5);
}
}
#[cfg(test)]모듈은cargo test일 때만 컴파일되어 바이너리 크기를 줄입니다.#[test]속성이 붙은 함수는 반환값이 없어도 되며, 패닉이 발생하면 실패로 기록됩니다.
assert_eq! 매크로는 기대값과 실제 값을 비교합니다. 실패 시 양쪽 값과 소스 위치를 함께 보여 주므로 디버깅이 빠릅니다.
문서 주석 안 코드도 사실상 테스트의 한 형태입니다. 즉, 문서 예제는 "설명"이면서 동시에 "실제로 돌아가는 검증 코드"라는 점이 Rust의 큰 장점입니다.
경계 조건 테스트
한 함수에 대한 여러 테스트를 작성할 때는 명확한 시나리오 이름을 붙여야 이후 리팩토링에서도 의미가 유지됩니다.
#[test]
fn add_handles_negative() {
assert_eq!(add(-3, 1), -2);
}
#[test]
fn add_with_zero_returns_other() {
assert_eq!(add(0, 7), 7);
}
테스트 이름만 보고 어떤 입력을 검증하는지 유추할 수 있도록 작성하면 나중에 실패 로그만 보고도 상황을 이해할 수 있습니다.
문서 주석과 예제
앞으로 만들 라이브러리가 다른 사람에게도 쓰이려면 문서 주석(///)이 필요합니다. 문서 주석 안에 ``` 코드 블록을 넣으면, cargo test가 해당 예제를 직접 실행해 검증합니다.
/// 두 정수의 합을 반환합니다.
///
/// # Examples
///
/// ```
/// use calculator::add;
/// assert_eq!(add(2, 2), 4);
/// ```
pub fn add(a: i32, b: i32) -> i32 {
a + b
}
도큐먼트 테스트는 실제 사용 예제를 유지보수하는 데 큰 도움이 됩니다. 코드가 바뀌면 주석 속 예제도 함께 실패하므로, 문서와 구현의 괴리가 줄어듭니다.
cargo doc --open
작성한 문서를 HTML로 미리보기 하려면 다음 명령을 실행합니다.
cargo doc --open
이 명령은 프로젝트의 공개 API를 문서화하고, 시스템 기본 브라우저로 문서를 열어 줍니다. pub이 아닌 항목은 기본적으로 표시되지 않으므로 공개 범위를 의도적으로 관리해야 합니다.
자주 막히는 부분
#[test]함수에 인자를 선언하면 컴파일 오류가 납니다. 테스트 함수는 인자를 받을 수 없습니다.- 비동기 테스트를 작성하려면
#[tokio::test]와 같은 별도 런타임이 필요합니다. 이번 편에서는 동기 테스트만 다룹니다. cargo test -- --nocapture를 사용해야println!출력이 보입니다. 기본 설정은 테스트 통과 시 출력을 숨깁니다.- 출력 순서가 섞여 헷갈리면
cargo test -- --test-threads=1로 테스트를 하나씩 순차 실행할 수 있습니다.
CodeSandbox로 이어서 실습하기
아래 샌드박스는 CodeSandbox의 Rust starter입니다. 이번 글의 핵심 코드를 src/main.rs에 옮기고, cargo check와 cargo run 결과를 나란히 보면서 컴파일 메시지와 실행 출력을 비교해 보세요.
💬 댓글
이 글에 대한 의견을 남겨주세요