Rust Documentation TestsIntegration TestsRustTestingUnit Tests

Article & Tutorial

Testing Rust Applications: Unit, Integration and Documentation Tests

Learn Rust testing with unit tests, integration tests, assertions, Result-based tests, test organization, documentation tests and practical CI workflows.

Melochip Editorial

@melochip-editorial

Published Sep 15, 2026 3 min read
React Comments Share More
Testing Rust Applications: Unit, Integration and Documentation Tests article illustration
Testing Rust Applications: Unit, Integration and Documentation Tests article illustration
Contents

Rust Learning Path — Chapter 20. Rust ships with testing support through Cargo, so there is no separate test framework required for the basics. This chapter covers unit tests, integration tests, documentation tests, assertions, expected failures, test organization and a production-friendly validation workflow.

1. Your first test

bash
fn add(a: i32, b: i32) -> i32 { a + b } #[cfg(test)] mod tests { use super::*; #[test] fn adds_numbers() { assert_eq!(add(2, 3), 5); } }

Run tests with:

bash
cargo test

2. Common assertions

bash
assert!(value > 0); assert_eq!(actual, expected); assert_ne!(left, right);

3. Custom assertion messages

bash
assert!(port <= 65535, "invalid port: {port}");

4. Testing panics

bash
#[test] #[should_panic(expected = "invalid configuration")] fn rejects_bad_config() { panic!("invalid configuration"); }

5. Tests can return Result

bash
#[test] fn parses_port() -> Result<(), Box<dyn std::error::Error>> { let port: u16 = "8080".parse()?; assert_eq!(port, 8080); Ok(()) }

6. Unit vs integration tests

Unit tests usually live beside the code they test. Integration tests live in the top-level tests/ directory and exercise the library through its public API.

bash
my_app/ ├── src/ │ └── lib.rs └── tests/ └── api_tests.rs

7. Test private implementation details carefully

Unit tests inside the same module can test private helpers, but prefer testing observable behavior instead of locking tests to every internal refactor.

8. Test filtering

bash
cargo test user cargo test -- --show-output cargo test -- --test-threads=1

9. Ignored tests

bash
#[test] #[ignore = "requires external database"] fn database_roundtrip() {}

Run ignored tests explicitly:

bash
cargo test -- --ignored

10. Documentation tests

Rust code examples inside documentation comments can be compiled and tested:

bash
/// Adds two integers. /// /// ``` /// assert_eq!(my_lib::add(2, 3), 5); /// ``` pub fn add(a: i32, b: i32) -> i32 { a + b }

Run them as part of cargo test.

11. Testing error cases

bash
fn parse_port(input: &str) -> Result<u16, String> { input.parse().map_err(|_| "invalid port".into()) } #[test] fn invalid_port_returns_error() { assert!(parse_port("abc").is_err()); }

12. Arrange, Act, Assert

A simple structure keeps tests readable:

bash
#[test] fn user_can_be_activated() { // Arrange let mut user = User::new("Ada"); // Act user.activate(); // Assert assert!(user.is_active()); }

13. Test boundaries, not only happy paths

  • Empty input
  • Minimum and maximum values
  • Malformed values
  • Repeated operations
  • Permission failures
  • Timeout/error paths

14. A good local quality gate

bash
cargo fmt --check cargo clippy --all-targets --all-features -- -D warnings cargo test --all-features cargo build --release

15. Keep tests deterministic

Avoid relying on wall-clock timing, random external services or shared mutable global state unless the test intentionally covers those behaviors. Deterministic tests are easier to trust in CI.

16. Mini lab

Build a small configuration parser with successful and failing cases. Add unit tests for parsing helpers, integration tests for the public API, and one documentation example.

Key takeaways

Rust makes testing part of the normal Cargo workflow. Focus tests on behavior, cover failure paths, keep them deterministic and make formatting/linting/testing a repeatable quality gate.

Did this help?

Yes No

Join the discussion

0 Comments

Ask questions, add context, or share what worked.

Sign in to join the discussion

No comments yet. Start the discussion.

More from Melochip Editorial

Related articles

Stay in the loop. Get new Melochip articles

Receive Melochip article updates when new articles are available. Explicit opt-in only.

No pre-checked boxes. Unsubscribe support is part of the subscriber foundation.