Integration testsConcept

Explanation

An integration test exercises a crate the same way an outside caller would: it lives in a top-level tests/ directory rather than alongside the implementation, and each file under tests/ is compiled as its own separate crate that depends on the library the same way any published consumer would. That single fact — a real crate boundary, not just a different module — is why an integration test can only reach pub items. Where a unit test can see private helpers because it's compiled inside the same module, an integration test is deliberately locked out of them, which is exactly the point: it proves the crate works when used from outside, not merely that its internals are individually correct. The Crates page covers that crate-boundary mechanics in more depth; this page's angle is the testing methodology it enables.

That methodology angle matters because a unit test's job is to isolate one function; an integration test's job is to check that several public functions still cooperate correctly once wired together — a realistic, multi-step use of the crate rather than a single call. A suite made entirely of unit tests can pass in full while the public API is nevertheless awkward or subtly broken to actually use end-to-end; an integration test catches exactly that gap, because it has no shortcut into internals to fall back on.

Shared setup that several integration test files need — building a sample dataset, spinning up a fixture — commonly lives in tests/common/mod.rs rather than in a file directly under tests/: a plain mod.rs isn't itself compiled as a test crate, so it can hold helper functions without contributing spurious test binaries.

Basic usage example

// src/lib.rs
pub struct Order {
    pub total_cents: u32,
}

pub fn apply_discount(order: &Order, percent_off: u8) -> u32 { // <- part of the crate's public API
    order.total_cents - (order.total_cents * percent_off as u32 / 100)
}

// tests/discount.rs — compiled as its own crate, linked against the library
use order_lib::{Order, apply_discount};

#[test]
fn discount_reduces_total() {
    let order = Order { total_cents: 2000 };
    assert_eq!(apply_discount(&order, 25), 1500);
}

Best practices & deeper information

// src/lib.rs
pub struct Cart { pub subtotal_cents: u32 }

pub fn new_cart(subtotal_cents: u32) -> Cart {
    Cart { subtotal_cents }
}

pub fn apply_coupon(cart: Cart, percent_off: u8) -> Cart {
    Cart { subtotal_cents: cart.subtotal_cents - (cart.subtotal_cents * percent_off as u32 / 100) }
}

pub fn total_with_tax(cart: &Cart, tax_percent: u8) -> u32 {
    cart.subtotal_cents + (cart.subtotal_cents * tax_percent as u32 / 100)
}

// tests/checkout_flow.rs
use shop::{new_cart, apply_coupon, total_with_tax};

#[test] // <- exercises the public workflow end to end, not one function at a time
fn checkout_applies_coupon_then_tax() {
    let cart = new_cart(10_000);
    let cart = apply_coupon(cart, 10);
    assert_eq!(total_with_tax(&cart, 8), 9_720);
}

// src/lib.rs
#[derive(Debug, PartialEq)]
pub struct ConfigError(pub String);

pub fn parse_timeout_seconds(raw: &str) -> Result<u32, ConfigError> {
    raw.parse().map_err(|_| ConfigError(format!("invalid timeout: {raw:?}")))
}

// tests/config_parsing.rs
use app_config::{parse_timeout_seconds, ConfigError};

#[test]
fn rejects_non_numeric_timeout() {
    let result = parse_timeout_seconds("soon");
    assert_eq!(result, Err(ConfigError("invalid timeout: \"soon\"".into())));
}

// tests/common/mod.rs — shared setup, not itself a test file
pub fn sample_order() -> order_lib::Order {
    order_lib::Order { total_cents: 4599 }
}

// tests/pricing.rs
mod common;
use order_lib::apply_discount;

#[test]
fn applies_discount_to_a_sample_order() { // <- calling the crate exactly like an external user would
    let order = common::sample_order();
    assert_eq!(apply_discount(&order, 10), 4139);
}