11.10. Integration Tests

In Rust, integration tests are placed in a separate `tests` directory alongside `src`, and each test file is compiled as its own crate, meaning they can only access the library's public API. The purpose of these tests is to verify that multiple parts of the library work together correctly, catching issues that unit tests might miss. To create an integration test, you import the library crate (e.g., `use RustStudy;`) and write test functions annotated with `#[test]`, without needing `#[cfg(test)]`.

If you find this helpful, please like, bookmark, and follow. To keep learning along, follow this series. 11.10.1 What Are Integration Tests In Rust, integration tests live completely outside the library being tested. Integration tests call the library the same way other code does, which also means they can only call public APIs. The purpose of integration tests is to verify that multiple parts of the library work together correctly. This differs from unit tests, which are smaller and more focused. Unit tests test a single module in isolation and can also test private interfaces. Sometimes code that works fine on its own can still fail when used together. Integration tests exist to find and solve such problems as early as possible. Therefore, integration test coverage is important . 11.10.2 The tests Directory To create integration tests, first create a tests directory. This directory sits alongside src , and cargo automatically looks for integration test files there. You can create any number of integration test files in this directory. During compilation, cargo treats each test file as a separate package, that is, a separate crate . Here is a demonstration of creating integration test files: 1. Create the tests Directory Create a folder named tests next to src : 2. Create a Test File Create a .rs test file inside tests and give it a name. Here I used integration test.rs : 3. Move the Test Code Into the Test File Using the code from the previous article lib.rs as an example: php pub fn add two a: usize - usize { internal adder a, 2 } fn internal adder left: usize, right: usize - usize { left + right } cfg test mod tests { use super:: ; test fn internal { let result = internal adder 2, 2 ; assert eq result, 4 ; } } Because every integration test file is a separate crate, the file integration test.rs must first import the contents of lib.rs into scope if it wants to test that crate. In this example, since I named the project RustStudy , the package name is RustStudy as well. If you are unsure, check the name field in your Cargo.toml . In this example, you can write use RustStudy; to import it, and you can also import a specific function if you want. After importing, you can write the test function directly. There is no need to write cfg test , because code under the tests directory is only run when you execute cargo test . You only need to annotate the test function with test . The full code looks like this integration test.rs : js use RustStudy; test fn it adds two { let result = RustStudy::add two 2 ; assert eq result, 4 ; } Output: bash $ cargo test Compiling adder v0.1.0 file:///projects/adder Finished test profile unoptimized +debuginfo target s in 1.31s Running unittests src/lib.rs target/debug/deps/adder-1082c4b063a8fbe6 running 1 test test tests::internal ... ok test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s Running tests/integration test.rs target/debug/deps/integration test-1082c4b063a8fbe6 running 1 test test it adds two ... ok test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s Doc-tests adder running 0 tests test result: ok. 0 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s You can see that this output shows two tests being run: one from lib.rs a unit test and one from integration test.rs an integration test . 11.10.3 Running a Specific Integration Test To run a specific integration test function, use cargo test <test name . To run all test functions in a specific test file, use cargo test --test <file name . For example: Now there are two files under tests . If I only want to run the test functions in integration test.rs , I can run: cargo test --test integration test 11.10.4 Submodules in Integration Tests Because each file under tests is compiled as a separate crate, these files do not share behavior with one another, unlike the files under src . So if I want to extract repeated logic in test functions into a helper function to avoid duplication, how should I write it? For example, I create a common.rs file under tests to store helper functions: Try running the tests: bash $ cargo test Compiling adder v0.1.0 file:///projects/adder Finished test profile unoptimized +debuginfo target s in 0.89s Running unittests src/lib.rs target/debug/deps/adder-1082c4b063a8fbe6 running 1 test test tests::internal ... ok test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s Running tests/common.rs target/debug/deps/common-92948b65e88960b4 running 0 tests test result: ok. 0 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s Running tests/integration test.rs target/debug/deps/integration test-92948b65e88960b4 running 1 test test it adds two ... ok test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s Doc-tests adder running 0 tests test result: ok. 0 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s You can see that common.rs appears in the test output. But since common.rs is only meant to store helper functions, it does not need to be tested itself. That is the wrong way to do it. The correct approach is to create a common directory under tests , place a mod.rs file inside it, and move the helper functions there. Then delete the old common.rs : This is another naming convention that Rust understands. Rust will not treat the common module as an integration test file, and common will no longer appear in the test output, because subdirectories under tests are not compiled as separate crates. If you want to use the contents there in an integration test file, just write mod <folder name ; at the top of the file. In this example, that would be mod common; . When using it, write common::your function . In this example, that would be common::setup . 11.10.5 Integration Tests for Binary Crates If a project is a binary crate, meaning it only has src/main.rs and no src/lib.rs , you cannot create integration tests under tests , even if you do, you cannot import functions from main.rs into scope. That is because only a library crate, meaning one with lib.rs , can expose functions for other crates to use. A binary crate means it runs independently. Therefore, Rust binary projects usually put this logic in lib.rs and keep only a simple call in main.rs . In that way, the project is treated as a library crate and can use integration tests to check the code.