Workspace, Trait, Test and Run

Setting up a Cargo workspace is the cleanest way to manage both your aggregator library and the aggregator_app binary in one place.

Ⅰ. Setting Up a Cargo workspace

1. Create a new workspace folder

Make a parent folder (say aggregator_workspace):

mkdir aggregator_workspace
cd aggregator_workspace

2. Create the workspace manifest

Inside it, create a Cargo.toml file:

[workspace]
members = [
    "aggregator",
    "aggregator_app",
]

This tells Cargo that both crates are part of one workspace.

3. Add your crates

Now create the two crates inside the workspace:

cargo new aggregator --lib
cargo new aggregator_app

Now the folder structure looks like this:

aggregator_workspace
├── Cargo.toml      # Workspace manifest
├── aggregator      # Library crate
│   ├── Cargo.toml
│   └── src/lib.rs
└── aggregator_app  # Binary crate
    ├── Cargo.toml
    └── src/main.rs

4. Define the library

Edit aggregator/src/lib.rs:

pub fn summarize(text: &str) -> String {
    format!("Summary: {}", text)
}

5. Link the binary to the library

In aggregator_app/Cargo.toml, add the dependency:

[dependencies]
aggregator = { path = "../aggregator" }

6. Use it in the binary

Edit aggregator_app/src/main.rs:

use aggregator::summarize;

fn main() {
    let text = "Rust makes systems programming fun and safe!";
    let summary = summarize(text);
    println!("{}", summary);
}

7. Build and run

From the workspace root:

cargo run -p aggregator_app

Output:

Summary: Rust makes systems programming fun and safe!

✅ Now you have:

aggregator → library crate
aggregator_app → binary crate
managed together in one workspace.

Ⅱ. How to Test the Library

Let’s extend the workspace so you can test your aggregator library while also running the app. There are two ways to test library, one is adding tests inside the library and the other is adding separate integration tests in a tests/ directory

1. Add tests inside the library

Edit aggregator/src/lib.rs:

/// Summarize a given text by prefixing it.
pub fn summarize(text: &str) -> String {
    format!("Summary: {}", text)
}

// Unit tests go in a special `tests` module.
#[cfg(test)]
mod tests {
    // Bring outer functions into scope
    use super::*;

    #[test]
    fn test_summarize_simple() {
        let text = "Hello Rust";
        let result = summarize(text);
        assert_eq!(result, "Summary: Hello Rust");
    }

    #[test]
    fn test_summarize_empty() {
        let text = "";
        let result = summarize(text);
        assert_eq!(result, "Summary: ");
    }
}

2. Run the tests

From the workspace root:

cargo test -p aggregator

Output (example):

running 2 tests
test tests::test_summarize_simple ... ok
test tests::test_summarize_empty ... ok

test result: ok. 2 passed; 0 failed

3. Run the app

From the same root:

cargo run -p aggregator_app

Output:

Summary: Rust makes systems programming fun and safe!

4. (Optional) Integration tests

You can also add separate integration tests in a tests/ directory inside the aggregator crate:

aggregator/
├── Cargo.toml
├── src/lib.rs
└── tests
    └── integration_test.rs

tests/integration_test.rs:

use aggregator::summarize;

#[test]
fn integration_summary() {
    let text = "Integration testing is easy!";
    let result = summarize(text);
    assert_eq!(result, "Summary: Integration testing is easy!");
}

Run all tests in the workspace:

cargo test

✅ Now you have:

Unit tests inside src/lib.rs
Integration tests in tests/
Ability to run tests and app from the same workspace.

Rust의 attribute 종류 및 의미

Rust에서의 attribute(속성)는 컴파일러에게 특정 코드에 대한 추가적인 정보를 제공하여, 코드의 컴파일 방식 또는 동작 방식을 제어하거나, 경고/에러 메시지를 제어하는 데 사용됩니다. derive, allow, warn, cfg, test 등 다양한 종류가 있습니다.

1. attribute의 적용 범위별 종류

Rust의 attribute는 크게 다음과 같은 종류로 나눌 수 있습니다:

종류	형태 예시	설명
Item attribute	#[derive(Debug)]	함수, 구조체 등 개별 항목에 적용
Crate attribute	#![allow(dead_code)]	크레이트 전체에 적용, 보통 파일 상단에 위치
Inner attribute	#![cfg(test)]	모듈 또는 크레이트 내부에 선언, 내부 항목에 영향을 줌
Outer attribute	#[test]	특정 항목(함수 등)에만 적용

2. 주요 attribute

가. 컴파일러 관련 attribute

Attribute	설명	예시
#[allow(…)]	특정 경고를 무시	#[allow(dead_code)]
#[warn(…)]	경고를 표시 (기본값)	#[warn(unused_variables)]
#[deny(…)]	해당 사항이 있으면 컴파일 에러	#[deny(missing_docs)]
#[forbid(…)]	deny보다 강하게 재정의 불가	#[forbid(unsafe_code)]

나. 파생(derive) 관련 attribute

Rust의 많은 기능은 trait을 자동으로 구현해주는 #[derive(…)]를 통해 사용합니다.

#[derive(Debug, Clone, PartialEq)]
struct Point {
    x: i32,
    y: i32,
}

Debug, Clone, PartialEq 트레이트를 자동 구현합니다.

다. 조건부 컴파일 관련 attribute

Attribute	설명	예시
#[cfg(…)]	조건에 따라 컴파일 여부 결정	#[cfg(target_os = “windows”)]
#[cfg_attr(…)]	조건이 참일 때에만 다른 attribute 적용	#[cfg_attr(test, derive(Debug))]

[cfg_attr(test, derive(Debug))]는 테스트를 실행할 때만 Debug 트레이트를 자동 구현합니다.

라. 테스트/벤치마크 관련 attribute

Attribute	설명	예시
#[test]	단위 테스트 함수임을 표시	#[test] fn test_add() { … }
#[bench]	벤치마크 함수 표시 (불안정)	#[bench] fn bench_sort(…)
#[ignore]	테스트 실행 시 무시됨	#[test] #[ignore] fn test_heavy() {}

마. 매크로 관련 attribute

Attribute	설명	예시
#[macro_use]	외부 크레이트의 매크로를 현재 스코프로 불러옴 (Rust 2015 방식)	#[macro_use] extern crate log;
#[proc_macro]	프로시저 매크로 정의	프로시저 매크로 crate에서 사용됨

바. 기타 유용한 attribute

Attribute	설명	예시
#[inline], #[inline(always)]	함수 인라인화 힌트	#[inline(always)] fn fast_fn() {}
#[repr(C)]	구조체 메모리 레이아웃 C와 호환	#[repr(C)] struct MyStruct { … }
#[non_exhaustive]	미래 확장을 위해 열거형 등의 exhaustive 검사 방지	#[non_exhaustive] enum MyEnum { … }
#[must_use]	반환값을 사용하지 않으면 경고	#[must_use] fn compute() -> i32 { … }

※ 함수를 호출할 때 일반적으로는 함수 본문은 어딘가에 있고 호출하면 그 함수로 점프(jump)해서 실행한 뒤 다시 돌아옵니다. 하지만 인라인화는 이런 점프 없이 함수의 코드를 호출한 곳에 ‘복붙’하듯 직접 삽입하는 방식입니다.

사. #![…]과 #[…] 차이

구분	형태	설명
Inner attribute	#![…]	모듈, 크레이트 전체에 적용 (파일 상단에 위치)
Outer attribute	#[…]	특정 항목(함수, struct 등)에 적용

3. attribute 예제

가. #[derive(…)] — 트레이트 자동 구현

(1) 설명: 구조체(struct)나 열거형(enum)에 대해, 특정 트레이트의 기본 구현을 자동 생성합니다.

(2) 자주 사용되는 트레이트:

Debug : {:?} 포맷으로 출력 가능
Clone, Copy : 값 복사 가능
PartialEq, Eq : 값 비교 가능
PartialOrd, Ord : 정렬 가능
Hash : 해시 사용 가능

(3) 예제:

#[derive(Debug, Clone, PartialEq)]
struct Point {
    x: i32,
    y: i32,
}

fn main() {
    let p1 = Point { x: 1, y: 2 };
    let p2 = p1.clone(); // Clone 사용
    println!("{:?}", p2); // Debug 사용
    println!("p1 == p2? {}", p1 == p2); // PartialEq 사용
}

나. #[allow(…)], #[warn(…)], #[deny(…)], #[forbid(…)]

(1) 설명: 컴파일 경고/에러를 제어합니다. => 위 2.의 가. 컴파일러 관련 attribute 설명 참고

(2) 주요 옵션:

dead_code : 사용되지 않는 코드
unused_variables : 사용되지 않는 변수
non_snake_case : snake_case 규칙 위반

(3) 예제:

#[allow(dead_code)]
fn unused() {
    println!("사용되지 않지만 경고 없음");
}

#[deny(unused_variables)]
fn foo() {
    let x = 5; // 컴파일 에러 발생: 변수 사용 안 함
}

다. #[test], #[ignore] — 테스트 함수 지정

(1) 설명: 테스트 프레임워크를 위한 attribute입니다.

(2) 예제:

#[cfg(test)]
mod tests {
    #[test]
    fn it_works() {
        assert_eq!(2 + 2, 4);
    }

    #[test]
    #[ignore]
    fn heavy_test() {
        // 실행하려면 `cargo test -- --ignored`
    }
}

라. #[cfg(…)] — 조건부 컴파일

(1) 설명: 플랫폼, 기능 등에 따라 코드 포함 여부 결정

(2) 예제:

#[cfg(target_os = "windows")]
fn run_on_windows() {
    println!("Windows 전용 코드");
}

#[cfg(not(target_os = "windows"))]
fn run_on_unix() {
    println!("Unix 계열 전용 코드");
}

(3) Cargo.toml에서 feature와 연계:

[features]
my_feature = []

#[cfg(feature = "my_feature")]
fn my_func() {
    println!("my_feature가 활성화됨");
}

“my_feature”라는 기능(feature)이 활성화됐을 때만 my_func() 함수의 정의 자체를 컴파일에 포함시키고, 아니면 아예 없는 코드처럼 무시해버립니다.

마. #[inline] — 인라인 최적화 힌트

(1) 설명: 컴파일러에게 해당 함수를 인라인하도록 유도

(2) 예제:

#[inline(always)]
fn fast_add(a: i32, b: i32) -> i32 {
    a + b
}

fn main() {
    let x = add(3, 4);
}

일반 호출: main에서 add 함수로 점프하고, 결과를 받아와서 x에 저장
인라인: 컴파일할 때 add(3, 4)를 그냥 3 + 4로 바꿔서 main 함수 안에 넣어버림

바. #[repr(…)] — 메모리 레이아웃 제어

(1) 설명: 구조체/열거형의 메모리 정렬 방법을 지정(repr은 representation(표현)의 약어)

(2) 종류:

C: C 언어와 동일한 레이아웃
packed: 패딩 없이 압축
transparent: 단일 필드 감싸기

(3) 예제:

#[repr(C)]
struct MyStruct {
    a: u8,
    b: u32,
}

사. #[non_exhaustive] — 미래 확장을 위한 열거형

(1) 설명: 나중에 항목이 더 생길 수 있으니, “지금 있는 것만 가지고 match를 완벽하게 쓰지 마세요“라는 의미입니다.

(2) 예제:

#[non_exhaustive]
pub enum Error {
    Io,
    Parse,
}

이 코드는 다음과 같은 의미를 가집니다.

Error enum은 지금은 Io와 Parse 두 가지 variant만 있지만, 앞으로 새로운 variant가 추가될 수 있으므로 다른 크레이트에서는 이 enum을 match할 때 지금 있는 것만으로 열거하지 못하게 제한하는 것입니다.

그래서 #[non_exhaustive]를 붙이면, 사용자는 반드시 _를 이용한 default arm을 추가해야만 컴파일이 가능하며, 이것은 다른 크레이트가 match를 지금 있는 것만으로 exhaustively(완전하게) 작성하면, 나중에 enum에 새로운 variant를 추가했을 때 컴파일이 깨질 수 있기 때문입니다.

아. #[must_use] — 반환값 사용하지 않으면 경고

(1) 설명: 실수로 무시하면 안 되는 반환값을 경고로 알려줌

(2) 예제:

#[must_use]
fn important_result() -> Result<(), String> {
    Err("Error".into())
}

fn main() {
    important_result(); // 경고 발생!
}

위 코드는 important_result 함수의 반환 값을 사용하지 않아 warning(경고)이 발생하므로 아래와 같은 식으로 수정해야 합니다.

fn main() {
    let result = important_result(); // OK
    if let Err(e) = result {
        println!("에러 발생: {}", e);
    }
}

자. #[macro_use], #[macro_export] — 매크로 관련

(1) 설명: 외부 crate의 매크로를 가져오거나 내보낼 때 사용

(2) 예제:

// 외부 매크로 사용
#[macro_use]
extern crate log;

// 매크로 정의 및 export
#[macro_export]
macro_rules! hello {
    () => {
        println!("Hello, macro!");
    };
}

#[macro_use] : 외부 크레이트 log에서 정의된 매크로(log!, info!, warn! 등)들을 이 파일 안에서 직접 사용할 수 있도록 가져오라는 의미로서, 예전 Rust 스타일 (Rust 2018 이전)의 방식이며, 최신 Rust (2018 edition 이후)에서는 use log::info; 식으로 가져오는 게 일반적입니다.
#[macro_export] : 이 매크로를 다른 모듈/크레이트에서 사용할 수 있게 공개(export) 하겠다는 의미입니다. 따라서, 이 매크로를 crate_name::hello!() 식으로 다른 crate에서도 쓸 수 있습니다.

Rust에서 테스트(test) 작성하기

Rust는 안정성과 신뢰성을 강조하는 언어답게 테스트를 매우 중요하게 여깁니다. 표준 라이브러리에는 테스트를 쉽게 작성하고 실행할 수 있도록 test 프레임워크가 기본 내장되어 있으며, cargo test 명령어로 손쉽게 실행할 수 있습니다. 오늘은 단위 테스트, 통합 테스트, 그리고 테스트 관련 어노테이션 및 모범 사례에 대해 알아보겠습니다.

1. 기본적인 단위 테스트 구조

Rust의 테스트는 일반적으로 소스 파일 내에 다음과 같은 구조로 작성됩니다.

// 실제 함수
pub fn add(a: i32, b: i32) -> i32 {
    a + b
}

// 테스트 모듈
#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_add() {
        assert_eq!(add(2, 3), 5);
    }
}

#[cfg(test)]: 이 모듈은 테스트 시에만 컴파일되도록 지정합니다.
mod tests { … }: 테스트용 하위 모듈을 의미합니다. 실제 코드와 분리된 테스트 코드입니다.
use super::*;: 상위 모듈(super)의 add 함수를 불러오는 것입니다. 이 줄을 주석처리하면 “add함수가 없다”고 합니다.
#[test]: 테스트 함수임을 표시합니다.
test_add 함수를 만들어서 add(2, 3)의 결과와 5가 같은지 비교해서 맞으면 ok, 다르면 failed가 발생합니다.
assert_eq!: 기대값과 실제값이 같은지 검사합니다.

가. 실행 방법

cargo test

cargo는 프로젝트 전체를 빌드하고 #[test] 함수들을 자동으로 실행합니다.

나. lib.rs 파일 작성 및 실행

(1) assert_eq!의 결과 두 값이 같은 경우

src 폴더 아래에 lib.rs란 파일로 작성했습니다.

day21 폴더에서 cargo test를 실행하니(VS Code를 보면 함수 위에 Run Test가 있으므로 이걸 눌러도 됨)
컴파일되고 실행되는데 먼저 unittests src\lib.rs라고 표시되어 lib.rs의 test annotation을 먼저 실행하고, 그 다음은 main.rs를 실행합니다.

lib.rs의 테스트 결과는
test tests::test_add … ok라고 표시되고,
그 아래 test result: ok. 1 passed; 0 failed… 등 내용이 표시되는데,

main.rs의 테스트 결과는 test 어노테이션이 없어서 0으로 표시됩니다.

그리고, assert_eq! 구문만 실행되고, main.rs에 있는 println!(“Hello, world!”);문은 실행되지 않습니다. lib.rs에 println!문이 있어도 실행되지 않습니다.

cargo test –lib라고 하면 lib.rs의 test annotation만 실행하고, main.rs에 test 어노테이션이 있는지 체크하지 않습니다.

(2) assert_eq!의 결과 두 값이 다른 경우

add(2, 3)의 결과는 5인데, 6과 비교하면 두 값이 다르므로 FAILED라고 결과가 표시되고,

그 아래를 보면 thread ‘tests::test_add’ panicked at day21\src\lib.rs:12:9:라고 panic이 발생했고,
왼쪽은 5, 오른쪽은 6으로 “왼쪽과 오른쪽이 같다는 단언(주장)이 실패했다”고 설명합니다.

2. 다양한 assert 매크로

Rust에서는 다음과 같은 다양한 테스트 도구를 제공합니다.

매크로	설명
assert!	조건이 true인지 확인
assert_eq!	두 값이 같은지 확인
assert_ne!	두 값이 다른지 확인(not equal)
dbg!	디버깅 용도로 값을 출력
panic!	강제로 실패시키기

예제:

#[test]
fn test_assertions() {
    let a = 10;
    let b = 20;
    assert!(a < b);
    assert_eq!(a + b, 30);
    assert_ne!(a, b);
}

위 코드를 cargo test –lib로 실행하면
모든 결과가 True이므로 test result: ok인데, 세 번이 아니라 한 번만 표시되고,

assert!(a > b);
assert_eq!(a + b, 40);
으로 수정해서 2개를 False로 만든 후 실행하면
a > b에서 panic이 되기 때문에 a + b와 40을 비교하는 부분은 가지도 못하고 끝납니다.

assert!가 실패하면 panic이 되므로 그 다음 assert_eq!를 실행하지 못함

따라서, a < b로 수정하고 실행하면 a + b = 40에서 실패가 발생합니다.

3. 실패하는 테스트

테스트가 실패했을 경우에는 어떤 테스트가 어떤 이유로 실패했는지 친절히 알려줍니다. 예를 들어:

#[test]
fn test_fail() {
    assert_eq!(1 + 1, 3); // 실패
}

실행 시 다음과 같은 메시지가 출력됩니다.
“왼쪽은 2인데, 오른쪽은 3으로 왼쪽과 오른쪽이 같지 않다”고 합니다.

---- test_fail stdout ----
thread 'test_fail' panicked at day21\src\lib.rs:27:5:
assertion `left == right` failed
  left: 2
 right: 3

4. 테스트 함수에서 panic이 발생하면?

Rust에서는 테스트 함수가 panic을 일으키면 테스트가 실패한 것으로 간주됩니다. 일부러 panic을 유발하는 테스트는 다음처럼 작성할 수 있습니다:

#[test]
#[should_panic]
fn test_panic() {
    panic!("강제로 실패시킴");
}

#[should_panic]: 이테스트는 panic이 발생해야 성공으로 간주됩니다.

테스트 함수에서 panic이 발생하면 :
#[should_panic]: panic이 발생해야 ok

5. 결과 반환형을 이용한 테스트

테스트 함수가 Result<(), E>를 반환할 수도 있습니다.

#[test]
fn test_with_result() -> Result<(), String> {
    if 2 + 2 == 4 {
        Ok(())
    } else {
        Err(String::from("'2 + 2는 4'가 아닙니다!"))
    }
}

가. Ok(성공)인 경우

successes:
test_with_result
라고 test_with_result가 성공임을 표시합니다.

나. 에러인 경우

failures에 Error: “‘2 + 2는 4’가 아닙니다!”라고 표시됩니다.

이 방식은 ? 연산자를 활용할 수 있어 더 깔끔하게 작성할 수 있습니다.

다. ? 연산자를 이용한 구문

fn check_math() -> Result<(), String> {
    if 2 + 2 == 4 {
        Ok(())
    } else {
        Err(String::from("'2 + 2는 4'가 아닙니다!"))
    }
}

#[test]
fn test_with_result() -> Result<(), String> {
    check_math()?; // 실패하면 즉시 반환됨
    Ok(())
}

6. 테스트 분류

가. 단위 테스트 (Unit Test)

하나의 함수나 모듈의 기능을 검사
일반적으로 동일한 파일 내 mod tests 안에 작성

나. 통합 테스트 (Integration Test)

실제 사용 시나리오처럼 여러 모듈이 함께 작동하는지를 테스트
tests/ 디렉터리 하위에 별도의 .rs 파일로 작성

예:

my_project/
├── src/
│   └── lib.rs
└── tests/
    └── integration_test.rs

// src/lib.rs
pub fn add(a: i32, b: i32) -> i32 {
    a + b
}

// tests/integration_test.rs
use my_project::add;

#[test]
fn test_add_integration() {
    assert_eq!(add(10, 20), 30);
}

위 integration_test.rs의 use문에 my_project가 있는데, day21 등으로 프로젝트명에 맞게 수정해야 합니다.

cargo test를 실행하면 src폴더의 lib.rs와 main.rs뿐만 아니라, tests폴더의 integration_test.rs까지 test가 있는지 찾아서 test를 진행하고, day21 폴더의 Doc-tests도 진행합니다.

그러나, tests 폴더의 integration_test.rs에서 Run Test를 누르면
integration_test.rs의 test만 실행합니다.

7. #[ignore]와 특정 테스트만 실행하기

테스트가 너무 오래 걸리거나 특별한 조건에서만 실행하고 싶을 때는 #[ignore] 어노테이션을 붙일 수 있습니다.

#[test]
#[ignore]
fn long_running_test() {
    // 오래 걸리는 테스트
}

cargo test 실행 시 무시되며,
test long_running_test … ignored

아래와 같이 실행하면 #[ignore]가 붙은 테스트만 실행합니다.

cargo test -- --ignored

위 코드를 실행하면 1 passed; … 1 filtered out;이라고 표시되는데, long_running_test는 통과되고, test_add_integration은 제외되었다는 뜻입니다.

특정 테스트만 실행하려면 이름을 지정합니다:

cargo test test_add

8. 테스트 모범 사례

작고 독립적인 테스트를 작성하세요.
각 테스트는 부작용이 없어야 합니다 (예: 파일 시스템 접근, DB 쓰기 등).
테스트 함수 이름은 명확하게 지어야 합니다(test_add, test_divide_by_zero 등).
테스트는 문서화 주석과 함께 유지하면 가독성이 높아집니다.

9. 문서화 테스트 (doctest)

Rust는 문서 주석(///) 안에 포함된 코드도 테스트로 실행합니다.

/// 두 수를 더합니다.
/// 
/// # 예시
/// ```
/// let result = my_crate::add(2, 3);
/// assert_eq!(result, 5);
/// ```
pub fn add(a: i32, b: i32) -> i32 {
    a + b
}

cargo test를 실행하면 이 문서 예제도 자동으로 테스트합니다.

my_crate는 프로젝트명에 맞게 수정해야 하는데, day21 프로젝트이므로 day21로 수정했습니다.

위에서는 Doc-tests시 test 개수가 0이었는데, 여기는 1로 표시되고, ‘add (line 48) … ok’라고 표시됩니다.

10. 마무리

Rust의 테스트 프레임워크는 매우 강력하면서도 간단하게 사용할 수 있습니다. 실수를 미리 잡아내고 코드를 문서화하며 안정성을 높이기 위해 테스트는 필수적인 도구입니다.