Integration tests and doc tests

Two more kinds of test

Unit tests check small pieces from the inside. But you also need to know that the pieces work together, through the public interface other people actually call. And if you write examples in your documentation, you want them to stay correct. Rust handles both with built-in tools.

Integration tests: the outside view

my_shop/
├── Cargo.toml
├── src/
│   └── lib.rs          // pub fn cart_total(...), pub struct Cart ...
└── tests/
    ├── checkout.rs     // integration tests
    └── common/
        └── mod.rs      // shared helpers (not a test file itself)

// tests/checkout.rs
use my_shop::Cart;

#[test]
fn full_checkout_with_coupon() {
    let mut cart = Cart::new();
    cart.add("kurta", 1200);
    cart.add("dupatta", 400);
    cart.apply_coupon("FESTIVE10");
    assert_eq!(cart.total(), 1440);
}

Each file in tests/ is compiled as its own separate crate. It imports your library by its package name, and it can only see items marked pub, exactly like an outside user. If something is awkward to test from here, it is probably awkward to use too, which is useful feedback on your API design.

Helpers shared by several test files go in tests/common/mod.rs and are brought in with mod common;. Using the folder form stops cargo from treating the helper file as a test file of its own.

cargo test --test checkout   # only tests/checkout.rs
cargo test --lib             # only unit tests in the library

Doc comments and doc tests

Comments starting with /// are documentation comments. They are written in Markdown and describe the item below them. cargo doc turns them into an HTML website like the one on docs.rs. Any code block inside them is compiled and run as a test by cargo test.

/// Adds GST to an amount in whole rupees.
///
/// # Examples
///
/// ```
/// let total = my_shop::with_gst(1000, 18);
/// assert_eq!(total, 1180);
/// ```
pub fn with_gst(amount: u32, rate: u32) -> u32 {
    amount + amount * rate / 100
}

cargo test --doc   # run only the doc tests
cargo doc --open   # build the docs and open them in the browser

How the three fit together

Common mistakes

• Trying to write integration tests for a binary-only crate (just main.rs). Move the logic into src/lib.rs and keep main.rs thin.
• Putting helpers in tests/common.rs, which cargo runs as an empty test file. Use tests/common/mod.rs.
• Doc examples that only compile on your machine (absolute paths, network). Keep examples self-contained.
• Forgetting the crate name in doc examples: inside docs you must write my_shop::with_gst, as an outside user would.