DEV Community: SomeB1oody

[Rust Guide]12.8. Writing Error Messages to Standard Error

SomeB1oody — Sat, 23 May 2026 22:19:13 +0000

12.8.0 Before We Begin

Chapter 12 builds a sample project: a command-line program. The program is grep (Global Regular Expression Print), a tool for global regular-expression searching and output. Its function is to search for specified text in a specified file.

This project is divided into these steps:

Receiving command-line arguments
Reading files
Refactoring: improving modules and error handling
Using TDD (test-driven development) to develop library functionality
Using environment variables
Writing error messages to standard error instead of standard output (this article)

If you find this helpful, please like, bookmark, and follow. To keep learning along, follow this series.

12.8.1 Review

Here is all the code written up to the previous article.

lib.rs:

use std::error::Error;
use std::fs;

pub struct Config {
    pub query: String,
    pub filename: String,
    pub case_sensitive: bool,
}

impl Config {
    pub fn new(args: &[String]) -> Result<Config, &'static str> {
        if args.len() < 3 {
            return Err("Not enough arguments");
        }
        let query = args[1].clone();
        let filename = args[2].clone();
        let case_sensitive = std::env::var("IGNORE_CASE").is_err();
        Ok(Config {
            query,
            filename,
            case_sensitive,
        })
    }
}

pub fn run(config: Config) -> Result<(), Box<dyn Error>> {
    let contents = fs::read_to_string(config.filename)?;
    let results = if config.case_sensitive {
        search(&config.query, &contents)
    } else {
        search_case_insensitive(&config.query, &contents)
    };
    for line in results {
        println!("{}", line);
    }
    Ok(())
}

pub fn search<'a>(query: &str, contents: &'a str) -> Vec<&'a str> {
    let mut results = Vec::new();
    for line in contents.lines() {
        if line.contains(query) {
            results.push(line);
        }
    }
    results
}

pub fn search_case_insensitive<'a>(query: &str, contents: &'a str) -> Vec<&'a str> {
    let mut results = Vec::new();
    let query = query.to_lowercase();
    for line in contents.lines() {
        if line.to_lowercase().contains(&query) {
            results.push(line);
        }
    }
    results
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn case_sensitive() {
        let query = "duct";
        let contents = "\
Rust:
safe, fast, productive.
Pick three.
Duct tape.";

        assert_eq!(vec!["safe, fast, productive."], search(query, contents));
    }

    #[test]
    fn case_insensitive() {
        let query = "rUsT";
        let contents = "\
Rust:
safe, fast, productive.
Pick three.
Trust me.";

        assert_eq!(
            vec!["Rust:", "Trust me."],
            search_case_insensitive(query, contents)
        );
    }
}

main.rs:

use std::env;
use std::process;
use minigrep::Config;

fn main() {
    let args: Vec<String> = env::args().collect();
    let config = Config::new(&args).unwrap_or_else(|err| {
        println!("Problem parsing arguments: {}", err);
        process::exit(1);
    });
    if let Err(e) = minigrep::run(config) {
        println!("Application error: {}", e);
        process::exit(1);
    }
}

12.8.2 Standard Output vs. Standard Error

The current code prints all information, including error messages, to the terminal. Most terminals provide two output streams: standard output (stdout) and standard error (stderr).

General information should go to standard output, while error messages should go to standard error. The advantage of this separation is that normal output can be redirected into a file while error messages still appear on the screen.

The println! macro can only print to standard output. The eprintln! macro can print to standard error.

Using the current code, run this command in the terminal:

cargo run > output.txt

This redirects output to output.txt, but the command does not include any arguments, so the program should error. Because the error messages are also written to standard output, they end up in output.txt.

A better approach is to print error messages to standard error, which keeps standard output clean and separate from errors.

12.8.3 Modifying the Code

Changing the code so that error messages go to standard error is quite simple. We only need to change all error printing from println! to eprintln!. Because all error handling is in main.rs, we only need a small change there, and lib.rs does not need to be modified at all:

use std::env;
use std::process;
use minigrep::Config;

fn main() {
    let args: Vec<String> = env::args().collect();
    let config = Config::new(&args).unwrap_or_else(|err| {
        eprintln!("Problem parsing arguments: {}", err);
        process::exit(1);
    });
    if let Err(e) = minigrep::run(config) {
        eprintln!("Application error: {}", e);
        process::exit(1);
    }
}

Now run the previous command again. It still has no arguments, so the program errors, but this time it will not put the error message into output.txt; instead, it will print directly in the terminal:

$ cargo run > output.txt
Problem parsing arguments: not enough arguments

Then try a normal run with arguments:

$ cargo run -- to poem.txt > output.txt

The output is redirected to output.txt. Open it:

Are you nobody, too?
How dreary to be somebody!

That is the result we want: errors are printed directly in the terminal, while normal output is redirected into the file.

[Rust Guide] 12.7. Using Environment Variables

SomeB1oody — Sat, 23 May 2026 22:18:24 +0000

12.7.0 Before We Begin

This project is divided into these steps:

Receiving command-line arguments
Reading files
Refactoring: improving modules and error handling
Using TDD (test-driven development) to develop library functionality
Using environment variables (this article)
Writing error messages to standard error instead of standard output

If you find this helpful, please like, bookmark, and follow. To keep learning along, follow this series.

12.7.1 Review

Here is all the code written up to the previous article.

lib.rs:

use std::error::Error;
use std::fs;

pub struct Config {
    pub query: String,
    pub filename: String,
}

impl Config {
    pub fn new(args: &[String]) -> Result<Config, &'static str> {
        if args.len() < 3 {
            return Err("Not enough arguments");
        }
        let query = args[1].clone();
        let filename = args[2].clone();
        Ok(Config {
            query,
            filename,
        })
    }
}

pub fn run(config: Config) -> Result<(), Box<dyn Error>> {
    let contents = fs::read_to_string(config.filename)?;
    for line in search(&config.query, &contents) {
        println!("{}", line);
    }
    Ok(())
}

pub fn search<'a>(query: &str, contents: &'a str) -> Vec<&'a str> {
    let mut results = Vec::new();
    for line in contents.lines() {
        if line.contains(query) {
            results.push(line);
        }
    }
    results
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn one_result() {
        let query = "duct";
        let contents = "\
Rust:
safe, fast, productive.
Pick three.";
        assert_eq!(vec!["safe, fast, productive."], search(query, contents));
    }
}

main.rs:

use std::env;
use std::process;
use minigrep::Config;

fn main() {
    let args: Vec<String> = env::args().collect();
    let config = Config::new(&args).unwrap_or_else(|err| {
        println!("Problem parsing arguments: {}", err);
        process::exit(1);
    });
    if let Err(e) = minigrep::run(config) {
        println!("Application error: {}", e);
        process::exit(1);
    }
}

In these earlier sections, we completed the move of the business logic into lib.rs. That is very helpful for writing tests, because the logic in lib.rs can be called directly with different arguments without running the program from the command line, and its return values can be checked. In other words, we can test the business logic directly.

12.7.2 What Is TDD?

TDD is short for Test-Driven Development, and it usually follows these steps:

Write a failing test, run it, and make sure it fails for the expected reason
Write or modify just enough code to make the new test pass
Refactor the code you just added or changed, and make sure the tests still pass
Return to step 1 and continue

TDD is only one of many software development methods, but it can guide and support code design. Writing tests first and then writing code that passes them also helps maintain a high level of test coverage during development.

In this article, we will use TDD to implement the search logic for the program: search for a specified string in the file contents and put the matching lines into a list. This function will be called search_case_insensitive.

12.7.3 Write a Failing Test

Let’s start by naming the case-insensitive function search_case_insensitive.

First, modify the test module so that it contains a case-sensitive test and a case-insensitive test:

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn case_sensitive() {
        let query = "duct";
        let contents = "\
Rust:
safe, fast, productive.
Pick three.
Duct tape.";

        assert_eq!(vec!["safe, fast, productive."], search(query, contents));
    }

    #[test]
    fn case_insensitive() {
        let query = "rUsT";
        let contents = "\
Rust:
safe, fast, productive.
Pick three.
Trust me.";

        assert_eq!(
            vec!["Rust:", "Trust me."],
            search_case_insensitive(query, contents)
        );
    }
}

Then write the body of search_case_insensitive:

pub fn search_case_insensitive<'a>(query: &str, contents: &'a str) -> Vec<&'a str> {
    vec![]
}

To make this function callable from outside, it must be declared public with pub
The function needs a lifetime annotation because it has multiple non-self parameters, and Rust cannot determine which parameter’s lifetime should match the lifetime of the return value
The elements in the returned Vector are string slices taken from contents, so the return value should have the same lifetime as contents; that is why both are annotated with the same lifetime 'a, while query does not need a lifetime annotation
The function body only needs to compile, because the first step of TDD is to write a test that fails, so failure is the desired outcome

At this point, running the tests will definitely fail, but that is fine. This is exactly what the first TDD step is supposed to produce.

12.7.4 Write or Modify Just Enough Code for the New Test to Pass

The code for search_case_insensitive is very similar to search, so only a few small changes are needed. The logic is simple: lowercase the query and compare it against lowercase versions of the text:

pub fn search_case_insensitive<'a>(query: &str, contents: &'a str) -> Vec<&'a str> {
    let mut results = Vec::new();
    let query = query.to_lowercase();
    for line in contents.lines() {
        if line.to_lowercase().contains(&query) {
            results.push(line);
        }
    }
    results
}

The to_lowercase method converts a string to all lowercase
The result of to_lowercase is a String, so the new query is owned String rather than &str. Inside the loop, we use &query because contains does not accept String directly, so we pass a reference

Run the tests again:

$ cargo test
   Compiling minigrep v0.1.0 (file:///projects/minigrep)
    Finished `test` profile [unoptimized + debuginfo] target(s) in 1.33s
     Running unittests src/lib.rs (target/debug/deps/minigrep-9cd200e5fac0fc94)

running 2 tests
test tests::case_insensitive ... ok
test tests::case_sensitive ... ok

test result: ok. 2 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s

     Running unittests src/main.rs (target/debug/deps/minigrep-9cd200e5fac0fc94)

running 0 tests

test result: ok. 0 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s

   Doc-tests minigrep

running 0 tests

test result: ok. 0 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s

Both tests pass.

12.7.5 Use This Function in `run`

Now that the function works, we can call it in run.

First, add a field to the Config struct so it can decide whether to use the normal search or the case-insensitive search_case_insensitive:

pub struct Config {
    pub query: String,
    pub filename: String,
    pub case_sensitive: bool,
}

Modify run so it checks the configuration:

pub fn run(config: Config) -> Result<(), Box<dyn Error>> {
    let contents = fs::read_to_string(config.filename)?;
    let results = if config.case_sensitive {
        search(&config.query, &contents)
    } else {
        search_case_insensitive(&config.query, &contents)
    };
    for line in results {
        println!("{}", line);
    }
    Ok(())
}

The new constructor on Config also needs to change so it assigns case_sensitive based on the environment variable:

impl Config {
    pub fn new(args: &[String]) -> Result<Config, &'static str> {
        if args.len() < 3 {
            return Err("Not enough arguments");
        }
        let query = args[1].clone();
        let filename = args[2].clone();
        let case_sensitive = std::env::var("IGNORE_CASE").is_err();
        Ok(Config {
            query,
            filename,
            case_sensitive,
        })
    }
}

Here we use std::env::var (of course, you could also bring std::env into scope first and then use env::var). Its argument is the name of the environment variable, which conventionally is all uppercase. Here I use IGNORE_CASE, which means case-insensitive. If this environment variable is present, the search is treated as case-insensitive; if it is absent, the search is case-sensitive.

std::env::var returns a Result. If the IGNORE_CASE environment variable is set, it returns Ok(String) containing the variable’s value; otherwise it returns Err(std::env::VarError).

After std::env::var, we call is_err. If is_err sees the Err variant, it returns true, which is assigned to case_sensitive; otherwise it assigns false.

PS: honestly, writing this little program in such a rigid way is also a teaching necessity. Halfway through, I was already laughing at how much code there was. When you actually write it, there is no need to be this formal.

12.7.6 The Full Code and a Trial Run

After writing all that, here is the full code up to this point.

lib.rs:

use std::error::Error;
use std::fs;

pub struct Config {
    pub query: String,
    pub filename: String,
    pub case_sensitive: bool,
}

impl Config {
    pub fn new(args: &[String]) -> Result<Config, &'static str> {
        if args.len() < 3 {
            return Err("Not enough arguments");
        }
        let query = args[1].clone();
        let filename = args[2].clone();
        let case_sensitive = std::env::var("IGNORE_CASE").is_err();
        Ok(Config {
            query,
            filename,
            case_sensitive,
        })
    }
}

pub fn run(config: Config) -> Result<(), Box<dyn Error>> {
    let contents = fs::read_to_string(config.filename)?;
    let results = if config.case_sensitive {
        search(&config.query, &contents)
    } else {
        search_case_insensitive(&config.query, &contents)
    };
    for line in results {
        println!("{}", line);
    }
    Ok(())
}

pub fn search<'a>(query: &str, contents: &'a str) -> Vec<&'a str> {
    let mut results = Vec::new();
    for line in contents.lines() {
        if line.contains(query) {
            results.push(line);
        }
    }
    results
}

pub fn search_case_insensitive<'a>(query: &str, contents: &'a str) -> Vec<&'a str> {
    let mut results = Vec::new();
    let query = query.to_lowercase();
    for line in contents.lines() {
        if line.to_lowercase().contains(&query) {
            results.push(line);
        }
    }
    results
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn case_sensitive() {
        let query = "duct";
        let contents = "\
Rust:
safe, fast, productive.
Pick three.
Duct tape.";

        assert_eq!(vec!["safe, fast, productive."], search(query, contents));
    }

    #[test]
    fn case_insensitive() {
        let query = "rUsT";
        let contents = "\
Rust:
safe, fast, productive.
Pick three.
Trust me.";

        assert_eq!(
            vec!["Rust:", "Trust me."],
            search_case_insensitive(query, contents)
        );
    }
}

main.rs:

use std::env;
use std::process;
use minigrep::Config;

fn main() {
    let args: Vec<String> = env::args().collect();
    let config = Config::new(&args).unwrap_or_else(|err| {
        println!("Problem parsing arguments: {}", err);
        process::exit(1);
    });
    if let Err(e) = minigrep::run(config) {
        println!("Application error: {}", e);
        process::exit(1);
    }
}

Let’s try running it:

First, run the program without setting the environment variable and use the query to, which should match any line containing the lowercase word to:

$ cargo run -- to poem.txt
   Compiling minigrep v0.1.0 (file:///projects/minigrep)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.0s
     Running `target/debug/minigrep to poem.txt`
Are you nobody, too?
How dreary to be somebody!

Now set IGNORE_CASE to 1 and keep everything else the same:

$ IGNORE_CASE=1 cargo run -- to poem.txt

You will get:

Are you nobody, too?
How dreary to be somebody!
To tell your name the livelong day
To an admiring bog!

There are no problems.

Note that if you are using powershell, you set an environment variable like this:

PS> $Env:IGNORE_CASE=1; cargo run -- to poem.txt

This keeps the environment variable available for the entire session. If you want to remove it, write:

PS> Remove-Item Env:IGNORE_CASE

[Rust Guide] 12.6. Developing Library Functionality with TDD

SomeB1oody — Sat, 23 May 2026 22:12:45 +0000

12.6.0 Before We Begin

In Chapter 12, we will build a real project: a command-line program. This program is a grep (Global Regular Expression Print), a tool for global regular-expression search and output. Its job is to search for the specified text in the specified file.

This project has several steps:

Receive command-line arguments
Read files
Refactor: improve modules and error handling
Use TDD (test-driven development) to develop library functionality (this article)
Use environment variables
Write error messages to standard error instead of standard output

If you find this helpful, please like, bookmark, and follow. To keep learning along, follow this series.

12.6.1 Review

Here is all the code written up to the previous article.

lib.rs:

use std::error::Error;  
use std::fs;  

pub struct Config {  
    pub query: String,  
    pub filename: String,  
}  

impl Config {  
    pub fn new(args: &[String]) -> Result<Config, &'static str> {  
        if args.len() < 3 {  
            return Err("Not enough arguments");  
        }  
        let query = args[1].clone();  
        let filename = args[2].clone();  
        Ok(Config { query, filename})  
    }  
}  

pub fn run(config: Config) -> Result<(), Box<dyn Error>> {  
    let contents = fs::read_to_string(config.filename)?;  
    println!("With text:\n{}", contents);  
    Ok(())  
}

main.rs:

use std::env;  
use std::process;  
use minigrep::Config;  

fn main() {  
    let args:Vec<String> = env::args().collect();  
    let config = Config::new(&args).unwrap_or_else(|err| {  
        println!("Problem parsing arguments: {}", err);  
        process::exit(1);  
    });  
    if let Err(e) = minigrep::run(config) {  
        println!("Application error: {}", e);  
        process::exit(1);  
    }  
}

In the previous sections, we moved the business logic into lib.rs. That helps a lot with writing tests, because the logic in lib.rs can be called directly with different parameters without running the program from the command line, and we can verify its return values. In other words, we can test the business logic directly.

12.6.2 What Is Test-Driven Development?

TDD stands for Test-Driven Development. It usually follows these steps:

Write a failing test, run it, and make sure it fails for the expected reason
Write or modify just enough code to make the new test pass
Refactor the code you just added or changed to make sure the tests still pass
Return to step 1 and continue

TDD is just one of many software development methods, but it can guide and help code design. Writing tests first and then writing code to pass those tests also helps maintain a high level of test coverage during development.

In this article, we will use TDD to implement the search logic: search for the specified string in the file contents and put the matching lines into a list. This function will be named search.

12.6.3 Modifying the Code

Follow the TDD steps:

1. Write a Failing Test

First, write a test module in lib.rs:

#[cfg(test)]  
mod tests {  
    use super::*;  

    #[test]  
    fn one_result() {  
        let query = "duct";  
        let contents = "\  
Rust: 
safe, fast, productive.  
Pick three.";  
        assert_eq!(vec!["safe, fast, productive."],search(query, contents));  
    }  
}

That is, because "duct" stored in query appears in the line "safe, fast, productive.", the return value should be a Vector whose element type is String, and it should contain only one element: "safe, fast, productive.".

The return value is a Vector because search is expected to handle multiple matching results. Of course, this particular test can only have one result, which is why the test is named one_result.

After writing the test module, write the search function:

pub fn search<'a>(query: &str, contents: &'a str) -> Vec<&'a str> {  
    vec![]  
}

To make the function callable from outside, it must be declared pub.
The function needs lifetime annotations because it has more than one non-self parameter, so Rust cannot tell which parameter’s lifetime matches the return value.
The elements in the returned Vector are string slices taken from contents, so the return value should have the same lifetime as contents. That is why both are annotated with the same lifetime 'a, while query does not need a lifetime annotation.
The function body only needs to compile, because the first step of TDD is to write a failing test. Failure is the desired outcome right now.

The test will fail, and that is exactly what we want in the first step of TDD.

2. Write Just Enough Code for the New Test to Pass

The code for search_case_insensitive is very similar to search; we only need a few changes. The logic is simple: convert both the query and the text to lowercase.

pub fn search_case_insensitive<'a>(query: &str, contents: &'a str) -> Vec<&'a str> {  
    let mut results = Vec::new();  
    let query = query.to_lowercase();  
    for line in contents.to_lowercase().lines() {  
        if line.contains(&query) {  
            results.push(line);  
        }  
    }  
    results  
}

The to_lowercase method converts a string to lowercase.
The result of to_lowercase is a String, which owns its data. That means the new query is a String, not a &str. In the if inside the loop, we use &query because contains does not accept String, so we must pass a reference.

Run the tests again:

$ cargo test
   Compiling minigrep v0.1.0 (file:///projects/minigrep)
    Finished `test` profile [unoptimized +debuginfo] target(s) in 1.33s
     Running unittests src/lib.rs (target/debug/deps/minigrep-9cd200e5fac0fc94)

running 2 tests
test tests::case_insensitive ... ok
test tests::case_sensitive ... ok

test result: ok. 2 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s

     Running unittests src/main.rs (target/debug/deps/minigrep-9cd200e5fac0fc94)

running 0 tests

test result: ok. 0 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s

   Doc-tests minigrep

running 0 tests

test result: ok. 0 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s

Both tests pass.

3. Use This Function in `run`

Now that the function works, we can call it from run.

But first, we need to add a field to the Config struct to decide whether to use the normal search or the case-insensitive search_case_insensitive:

pub struct Config {  
    pub query: String,  
    pub filename: String,  
    pub case_sensitive: bool,  
}

Update run so it checks the configuration:

pub fn run(config: Config) -> Result<(), Box<dyn Error>> {  
    let contents = fs::read_to_string(config.filename)?;  
    let results = if config.case_sensitive {  
        search(&config.query, &contents)  
    } else {  
        search_case_insensitive(&config.query, &contents)  
    };  
    for line in results {  
        println!("{}", line);  
    }  
    Ok(())  
}

The new constructor on Config also needs to change, and it should set case_sensitive based on an environment variable:

impl Config {  
    pub fn new(args: &[String]) -> Result<Config, &'static str> {  
        if args.len() < 3 {  
            return Err("Not enough arguments");  
        }  
        let query = args[1].clone();  
        let filename = args[2].clone();  
        let case_sensitive = std::env::var("CASE_INSENSITIVE").is_err();  
        Ok(Config { query, filename, case_sensitive})  
    }  
}

This uses std::env::var (you can also import std::env first and then use env::var). Its argument is the name of the environment variable, usually written in all caps. Here I use CASE_INSENSITIVE, which means “case-insensitive.” If this environment variable exists, we treat the search as case-insensitive; if it does not exist, we treat it as case-sensitive.

std::env::var returns a Result. If CASE_INSENSITIVE is set, it returns Ok(String) containing the variable’s value; otherwise it returns Err(std::env::VarError).

The is_err method is chained after std::env::var. If the result is Err, it returns true and assigns true to case_sensitive; otherwise it assigns false.

PS: honestly, writing this little program in such a rigid way is a teaching compromise. When I was halfway through, even I was amused by how much code there was. In real work, you do not need to make it this rigid.

12.6.3 The Full Code and a Trial Run

Here is all the code written so far.

lib.rs:

use std::error::Error;  
use std::fs;  

pub struct Config {  
    pub query: String,  
    pub filename: String,  
    pub case_sensitive: bool,  
}  

impl Config {

[Rust Guide] 12.5. Refactoring Pt.3 - Moving Business Logic

SomeB1oody — Sat, 23 May 2026 22:11:53 +0000

12.5.0 Before We Begin

This project has several steps:

Receive command-line arguments
Read files
Refactor: improve modules and error handling (this article)
Use TDD (test-driven development) to develop library functionality
Use environment variables
Write error messages to standard error instead of standard output

If you find this helpful, please like, bookmark, and follow. To keep learning along, follow this series.

12.5.1 Review

The previous two articles completed modularization optimization and error handling. In this article, we will do further optimization on that basis.

Here is all the code written up to the previous article:

use std::env;  
use std::fs;  
use std::process;  

struct Config {  
    query: String,  
    filename: String,  
}  

fn main() {  
    let args:Vec<String> = env::args().collect();  
    let config = Config::new(&args).unwrap_or_else(|err| {  
        println!("Problem parsing arguments: {}", err);  
        process::exit(1);  
    });  

    let contents = fs::read_to_string(config.filename)  
        .expect("Something went wrong while reading the file");  
    println!("With text:\n{}", contents);  
}  

impl Config {  
    fn new(args: &[String]) -> Result<Config, &'static str> {  
        if args.len() < 3 {  
            return Err("Not enough arguments");  
        }  
        let query = args[1].clone();  
        let filename = args[2].clone();  
        Ok(Config { query, filename})  
    }  
}

12.5.2 Extracting Logic from `main`

As discussed in 12.3. Refactoring Pt. 1, we follow the guiding principle for separating concerns in binary programs:

Split the program into main.rs and lib.rs, and put business logic in lib.rs
If the logic is small, keeping it in main.rs is fine
As the logic becomes more complex, extract it from main.rs into lib.rs

According to that principle, everything in main except configuration parsing and error handling should be extracted into a run function. That keeps main small enough that we can verify correctness just by reading it, while the rest of the logic can be verified through tests (see Chapter 11 for tests).

For the code we have so far, the run function should be:

fn run(config: Config) {  
    let contents = fs::read_to_string(config.filename)  
        .expect("Something went wrong while reading the file");  
    println!("With text:\n{}", contents);  
}

main should also call run:

fn main() {  
    let args:Vec<String> = env::args().collect();  
    let config = Config::new(&args).unwrap_or_else(|err| {  
        println!("Problem parsing arguments: {}", err);  
        process::exit(1);  
    });  
    run(config);  
}

12.5.3 Improving Error Handling in `run`

Right now, run uses expect for file-reading errors. That kind of error handling calls panic!. What we want instead is to propagate errors with Result, just like Config::new:

fn run(config: Config) -> Result<(), Box<dyn Error>> {  
    let contents = fs::read_to_string(config.filename)?;  
    println!("With text:\n{}", contents);  
    Ok(())  
}

The Ok variant of Result corresponds to (), the unit type. This type means “nothing is returned” or “there is nothing here,” which is fine because run does not need to return anything on success. The final line Ok(()) returns Ok with a unit value.
The Err variant of Result is Box<dyn Error>. You do not need to understand it in depth yet; just know that it represents any type that implements the std::error::Error trait (here I wrote just Error because I imported it with use std::error::Error;). This means different error types can be returned in different situations. dyn is short for dynamic.
The ? symbol was explained in detail in 9.3. Result Enum and Recoverable Errors Pt. 2. Briefly, read_to_string returns a Result. Adding ? means that if read_to_string returns Ok, the value inside Ok is returned and assigned to the variable; if it returns Err, the function terminates immediately and returns the Err and its attached error information. In other words, ? is equivalent to:

let contents = match fs::read_to_string(config.filename){
    Ok(contents) => contents,
    Err(e) => return Err(e),
};

With this change, the error is propagated to the caller, which is main, so main must handle the error:

fn main() {  
    let args:Vec<String> = env::args().collect();  
    let config = Config::new(&args).unwrap_or_else(|err| {  
        println!("Problem parsing arguments: {}", err);  
        process::exit(1);  
    });  
    if let Err(e) = run(config) {  
        println!("Application error: {}", e);  
        process::exit(1);  
    }  
}

The if let used here is syntactic sugar for match; think of it as a match that handles only one branch. See 6.4. Simple Control Flow - If Let for details. Note that if let and if are not the same thing, so do not confuse them.

12.5.4 Moving the Business Logic

Now that all the functions and error handling are separated, the next step is to move them into lib.rs.

The things to move are these functions, structs, and related imports.

The result after moving them (lib.rs) is:

use std::error::Error;  
use std::fs;  

pub struct Config {  
    pub query: String,  
    pub filename: String,  
}  

impl Config {  
    pub fn new(args: &[String]) -> Result<Config, &'static str> {  
        if args.len() < 3 {  
            return Err("Not enough arguments");  
        }  
        let query = args[1].clone();  
        let filename = args[2].clone();  
        Ok(Config { query, filename})  
    }  
}  

pub fn run(config: Config) -> Result<(), Box<dyn Error>> {  
    let contents = fs::read_to_string(config.filename)?;  
    println!("With text:\n{}", contents);  
    Ok(())  
}

Note: all structs, methods on structs, and functions used by main.rs must be marked pub so they can be called.

Now look at main.rs:

use std::env;  
use std::process;  
use minigrep::Config;  

fn main() {  
    let args:Vec<String> = env::args().collect();  
    let config = Config::new(&args).unwrap_or_else(|err| {  
        println!("Problem parsing arguments: {}", err);  
        process::exit(1);  
    });  
    if let Err(e) = minigrep::run(config) {  
        println!("Application error: {}", e);  
        process::exit(1);  
    }  
}

All refactoring tasks are complete. The next step is to write tests (the next article).

[Rust Guide] 12.4. Refactoring Pt.2 - Error Handling

SomeB1oody — Sat, 23 May 2026 22:10:03 +0000

12.4.0 Before We Begin

This project has several steps:

Receive command-line arguments
Read files
Refactor: improve modules and error handling (this article)
Use TDD (test-driven development) to develop library functionality
Use environment variables
Write error messages to standard error instead of standard output

If you find this helpful, please like, bookmark, and follow. To keep learning along, follow this series.

12.4.1 Review

In the previous section, to improve modularity, we created a struct for the variables and moved the argument-parsing function into a method on that struct. Here is all the code written up to the previous article:

use std::env;  
use std::fs;  

struct Config {  
    query: String,  
    filename: String,  
}  

fn main() {  
    let args:Vec<String> = env::args().collect();  
    let config = Config::new(&args);  

    let contents = fs::read_to_string(config.filename)  
        .expect("Something went wrong while reading the file");  
    println!("With text:\n{}", contents);  
}  

impl Config {  
    fn new(args: &[String]) -> Config {  
        let query = args[1].clone();  
        let filename = args[2].clone();  
        Config {  
            query,  
            filename,  
        }  
    }  
}

12.4.2 Unexpected Input

The program works correctly only when the user provides valid input. Let’s try running it without arguments:

$ cargo run
   Compiling minigrep v0.1.0 (file:///projects/minigrep)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.0s
     Running `target/debug/minigrep`
thread 'main' panicked at src/main.rs:27:21:
index out of bounds: the len is 1 but the index is 1
note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace

It reports Index out of bounds. As the programmer, we know this is because there were not enough arguments, so the program went out of bounds when using an index to fetch them. But a user cannot understand this error message, so they cannot correct the mistake.

What this article will do is make the program’s error messages easier to understand.

12.4.3 Specifying Error Messages

The way to help users understand the error is to provide our own error message. In the previous example, the panic happened when Config::new tried to access an out-of-bounds index, so let’s modify that part:

impl Config {  
    fn new(args: &[String]) -> Config {  
        if args.len() < 3 {  
            panic!("Not enough arguments");  
        }  
        let query = args[1].clone();  
        let filename = args[2].clone();  
        Config {  
            query,  
            filename,  
        }  
    }  
}

If args contains fewer than three elements, panic and print "Not enough arguments" to tell the user that too few arguments were provided.

Try running it without arguments again:

$ cargo run
   Compiling minigrep v0.1.0 (file:///projects/minigrep)
    Finished `dev` profile [unoptimized +debuginfo] target(s) in 0.0s
     Running `target/debug/minigrep`
thread 'main' panicked at src/main.rs:26:13:
not enough arguments
note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace

This error message is much better than the previous one.

However, some extra information is still shown, such as thread 'main' panicked at src/main.rs:26:13: and note: run with RUST_BACKTRACE=1 environment variable to display a backtrace. Those are for programmers, not for users, so they should be removed too.

12.4.4 Using the `Result` Type

panic! is appropriate when the program itself has a bug. But here, the problem is that the program was used incorrectly because there were too few arguments. For this kind of problem, using Result to propagate the error is the best choice (see 9.2. Result Enum and Recoverable Errors Pt. 1 and Pt. 2 for details):

impl Config {  
    fn new(args: &[String]) -> Result<Config, &'static str> {  
        if args.len() < 3 {  
            return Err("Not enough arguments");  
        }  
        let query = args[1].clone();  
        let filename = args[2].clone();  
        Ok(Config { query, filename})  
    }  
}

Error information must be wrapped in Err, and successful return values must be wrapped in Ok.
The Ok variant of Result returns a Config instance, while Err returns an &str string literal. However, the compiler does not know where that &str comes from or how long its lifetime is, so we need a lifetime annotation. We want it to remain valid for the entire program run, so we write it as &'static str, the static lifetime.

Since the return type of new has changed, the code in main that receives its value must also change:

let config = Config::new(&args).unwrap_or_else(|err| {  
    println!("Problem parsing arguments: {}", err);  
    process::exit(1);  
});

The unwrap_or_else method accepts a Result. If it is Ok, it returns the value inside Ok, similar to unwrap. If it is Err, the method calls a closure.

A closure is an anonymous function that we define and pass as an argument to unwrap_or_else. Its syntax uses two pipes ||, with a variable name in the middle as the parameter. Here it is err, which can be used inside the closure body, such as when printing the error.

Then we use process::exit from the standard library. Remember to import it first with use std::process;. Calling exit terminates the program immediately, and its argument, 1 in the example, becomes the program’s exit status code. This means that after println!("Problem parsing arguments: {}", err);, the program stops, so there is no thread 'main' panicked at src/main.rs:26:13: or backtrace note.

Try it:

$ cargo run
   Compiling minigrep v0.1.0 (file:///projects/minigrep)
    Finished `dev` profile [unoptimized +debuginfo] target(s) in 0.48s
     Running `target/debug/minigrep`
Problem parsing arguments: not enough arguments

The concept of closures will be covered in the next chapter, so it is fine if this does not make complete sense yet; a rough understanding is enough here.

12.4.5 The Full Code

Here is all the code written up to this article:

use std::env;  
use std::fs;  
use std::process;  

struct Config {  
    query: String,  
    filename: String,  
}  

fn main() {  
    let args:Vec<String> = env::args().collect();  
    let config = Config::new(&args).unwrap_or_else(|err| {  
        println!("Problem parsing arguments: {}", err);  
        process::exit(1);  
    });  

    let contents = fs::read_to_string(config.filename)  
        .expect("Something went wrong while reading the file");  
    println!("With text:\n{}", contents);  
}  

impl Config {  
    fn new(args: &[String]) -> Result<Config, &'static str> {  
        if args.len() < 3 {  
            return Err("Not enough arguments");  
        }  
        let query = args[1].clone();  
        let filename = args[2].clone();  
        Ok(Config { query, filename})  
    }  
}

[Rust Guide] 12.3. Refactoring Pt.1 - Improving Modularity

SomeB1oody — Sat, 23 May 2026 22:09:07 +0000

12.3.0 Before We Begin

This project has several steps:

Receive command-line arguments
Read files
Refactor: improve modules and error handling (this article)
Use TDD (test-driven development) to develop library functionality
Use environment variables
Write error messages to standard error instead of standard output

If you find this helpful, please like, bookmark, and follow. To keep learning along, follow this series.

12.3.1 Why Refactor

The purpose of refactoring is to improve modularity and error handling.

Here is all the code written up to the previous article:

use std::env;  
use std::fs;  

fn main() {  
    let args:Vec<String> = env::args().collect();  
    let query = &args[1];  
    let filename = &args[2];  

    println!("search for {}", query);  
    println!("In file {}", filename);  

    let contents = fs::read_to_string(filename)  
        .expect("Something went wrong while reading the file");
    println!("With text:\n{}", contents);  
}

This code has four problems:

The main function is doing too much. It handles command-line parsing and file reading. The guiding principle of program design is that each function should handle only one responsibility, so the function should be split up.
The variables query and filename store program configuration, while contents stores file contents. As code and variables accumulate, it becomes harder to track what each variable actually means. These values should be stored in a struct.
File-reading errors are handled with expect, which always prints an error message and panics no matter what went wrong. That is not ideal, because a file read failure might mean the file does not exist, or it might be a permissions problem. The panic message "Something went wrong while reading the file" does not help the user diagnose the issue.
If expect is used throughout the program, users will see error messages coming from Rust internals, such as "Index out of bounds", which makes it hard to understand what actually caused the problem. It is better to centralize error handling so future maintainers only need to consider one place when changing the logic, and so the error messages shown to users are understandable.

12.3.2 A Guiding Principle for Separating Concerns in Binary Programs

Many Rust binary projects run into the same organizational problem: they put too much functionality and too many responsibilities into main. The Rust community has a guiding principle for separating concerns in binary programs:

Split the program into main.rs and lib.rs, and put business logic in lib.rs
If the logic is small, keeping it in main.rs is fine
As the logic becomes more complex, extract it from main.rs into lib.rs

After this split, the responsibilities that should remain in main in this example are:

Call the command-line parsing logic using the argument values
Perform other configuration
Call the run function in lib.rs
Handle any problems that run may return

12.3.3 Separating Logic

Take another look at the code:

use std::env;  
use std::fs;  

fn main() {  
    let args:Vec<String> = env::args().collect();  
    let query = &args[1];  
    let filename = &args[2];  

    println!("search for {}", query);  
    println!("In file {}", filename);  

    let contents = fs::read_to_string(filename)  
        .expect("Something went wrong while reading the file");
    println!("With text:\n{}", contents);  
}

First, extract the command-line argument handling:

fn parse_config(args: &[String]) -> (&str, &str) {  
    let query = &args[1];  
    let filename = &args[2];  
    (query, filename)  
}

&[String] means a slice of a Vector whose elements are String
There is no need to print query and filename here, so that part is removed

Then change main to call parse_config:

fn main() {  
    let args:Vec<String> = env::args().collect();  
    let (query, filename) = parse_config(&args);  

    let contents = fs::read_to_string(filename)  
        .expect("Something went wrong while reading the file");  
    println!("With text:\n{}", contents);  
}

12.3.4 Using a Struct

parse_config returns query and filename together as a tuple, and then main splits those two tuple values back into two variables. This back-and-forth splitting and combining shows that the abstraction in the program is not ideal.

query and filename are both part of the configuration and are related to each other, so putting them in a tuple does not express that relationship well enough. A struct is a better fit:

struct Config {  
    query: String,  
    filename: String,  
}  

fn main() {  
    let args:Vec<String> = env::args().collect();  
    let config = parse_config(&args);  

    let contents = fs::read_to_string(config.filename)  
        .expect("Something went wrong while reading the file");  
    println!("With text:\n{}", contents);  
}  

fn parse_config(args: &[String]) -> Config {  
    let query = args[1].clone();  
    let filename = args[2].clone();  
    Config {  
        query,  
        filename,  
    }  
}

In parse_config, pay attention to the types of query and filename: the parameter args has type &[String], which is a reference and therefore does not own the data, so query and filename are also references. But Config expects String, not &String, so we need to clone to gain ownership and convert &String into String.

Cloning uses more time and memory than storing references directly, but it saves us from dealing with lifetimes and makes the code more direct and simpler. In some scenarios, giving up a bit of performance in exchange for simplicity is well worth considering.

Of course, using String::from to wrap the values also works:

fn parse_config(args: &[String]) -> Config {  
    let query = &args[1];  
    let filename = &args[2];  
    Config {  
        query: String::from(query),  
        filename: String::from(filename),  
    }  
}

There are other valid ways to write this code too, but here I will use the cloning approach.

12.3.5 Turning a Function Into a Struct Method

Since parse_config creates a Config instance, it is effectively a constructor. A constructor can be written like this:

impl Config {  
    fn new(args: &[String]) -> Config {  
        let query = args[1].clone();  
        let filename = args[2].clone();  
        Config {  
            query,  
            filename,  
        }  
    }  
}

Just place this function on the Config implementation block (for details on methods, see 5.3. Methods on Structs). I also renamed parse_config to new, because I am treating it as a constructor (constructors are usually named new).

After this change, main also needs to be updated:

let config = Config::new(&args);

12.3.5 The Full Code

Here is all the code written up to this article:

use std::env;  
use std::fs;  

struct Config {  
    query: String,  
    filename: String,  
}  

fn main() {  
    let args:Vec<String> = env::args().collect();  
    let config = Config::new(&args);  

    let contents = fs::read_to_string(config.filename)  
        .expect("Something went wrong while reading the file");  
    println!("With text:\n{}", contents);  
}  

impl Config {  
    fn new(args: &[String]) -> Config {  
        let query = args[1].clone();  
        let filename = args[2].clone();  
        Config {  
            query,  
            filename,  
        }  
    }  
}

[Rust Guide] 12.2. Reading Files

SomeB1oody — Sat, 23 May 2026 22:08:22 +0000

12.2.0 Before We Begin

This project has several steps:

Receive command-line arguments
Read files (this article)
Refactor: improve modules and error handling
Use TDD (test-driven development) to develop library functionality
Use environment variables
Write error messages to standard error instead of standard output

If you find this helpful, please like, bookmark, and follow. To keep learning along, follow this series.

12.2.2 Review

Here is all the code written up to the previous article:

use std::env;  

fn main() {  
    let args:Vec<String> = env::args().collect();  
    let query = &args[1];  
    let filename = &args[2];

    println!("search for {}", query);  
    println!("In file {}", filename);  
}

At this point, the code handles reading the user’s command-line input. Next we need to read the file based on that input.

12.2.3 Reading a File

To read a file, we need to import std::fs, which handles file-related operations:

use std::fs;

Next, read the file using filename:

let contents = fs::read_to_string(filename);

Reading can fail, so the return value is not the contents directly but a Result enum. For that enum, you can use expect to unwrap it. The argument to expect is the error message to print if something goes wrong (expect is covered in detail in 9.2. Result Enum and Recoverable Errors Pt. 1).

let contents = fs::read_to_string(filename)
.expect("Something went wrong while reading the file");// line break here is only to keep the line short

If the file is read successfully, print the contents:

println!("With text:\n{}", contents);

12.2.4 Testing the Code

At this point, we can test the code.

Here is all the code written so far:

use std::env;  
use std::fs;  

fn main() {  
    let args:Vec<String> = env::args().collect();  
    let query = &args[1];  
    let filename = &args[2];  

    println!("search for {}", query);  
    println!("In file {}", filename);  

    let contents = fs::read_to_string(filename)  
        .expect("Something went wrong while reading the file");// line break here is only to keep the line short  
    println!("With text:\n{}", contents);  
}

First, create a .txt file in the project directory. You can name it whatever you like; I used poem.txt. Put some text in it, for example:

I'm nobody! Who are you?
Are you nobody, too?
Then there's a pair of us - don't tell!
They'd banish us, you know.

How dreary to be somebody!
How public, like a frog
To tell your name the livelong day
To an admiring bog!

Then run the command:

cargo run -- the poem.txt

The -- separates Cargo command arguments from program arguments. It tells Cargo that what follows is not a Cargo option or argument, but an argument passed to the program. It is not read or stored.
the is the text to search for and is stored in query
poem.txt is the file name and is stored in filename

Output:

$ cargo run -- the poem.txt
   Compiling minigrep v0.1.0 (file:///projects/minigrep)
    Finished `dev` profile [unoptimized +debuginfo] target(s) in 0.0s
     Running `target/debug/minigrep the poem.txt`
Searching for the
In file poem.txt
With text:
I'm nobody! Who are you?
Are you nobody, too?
Then there's a pair of us - don't tell!
They'd banish us, you know.

How dreary to be somebody!
How public, like a frog
To tell your name the livelong day
To an admiring bog!

No problems.

[Rust Guide] 12.1. Receiving Command-Line Arguments

SomeB1oody — Sat, 23 May 2026 22:07:30 +0000

12.1.0 Before We Begin

This project has several steps:

Receive command-line arguments (this article)
Read files
Refactor: improve modules and error handling
Use TDD (test-driven development) to develop library functionality
Use environment variables
Write error messages to standard error instead of standard output

If you find this helpful, please like, bookmark, and follow. To keep learning along, follow this series.

12.1.1 Standardizing the Input Format

First we need to define a standard input format for passing arguments. I use the following convention:

cargo run text filename.txt

12.1.2 Reading Command-Line Arguments

After standardizing the input, the next problem is reading command-line arguments.

We need a function from Rust’s standard library: std::env::args(). This function returns an iterator (covered in Chapter 13) that yields a series of values. For an iterator, you can use the collect method to turn that series of values into a collection, such as a Vector.

As discussed in 7.4. Use Pt. 1, when a function is nested inside more than one module, we usually bring its parent module into scope.

Here is the code:

use std::env;

fn main() {
    let args:Vec<String> = env::args().collect();
}

Because collect produces a collection, but Rust cannot infer the element type of that collection, we must explicitly declare args as Vec<String>.

Let’s use println! to see what happens:

use std::env;

fn main() {
    let args:Vec<String> = env::args().collect();
    println!("{:#?}", args);
}

Output 1, with no arguments:

$ cargo run
   Compiling minigrep v0.1.0 (file:///projects/minigrep)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.61s
     Running `target/debug/minigrep`
[src/main.rs:5:5] args = [
    "target/debug/minigrep",
]

Output 2, with arguments:

$ cargo run -- needle haystack
   Compiling minigrep v0.1.0 (file:///projects/minigrep)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 1.57s
     Running `target/debug/minigrep needle haystack`
[src/main.rs:5:5] args = [
    "target/debug/minigrep",
    "needle",
    "haystack",
]

The -- in the second example is used to separate the arguments for the Cargo command from the arguments passed to the program. It tells Cargo that what follows is not a Cargo option or argument, but arguments that should be passed to the program when it runs. env::args does not read or store it.

You can see that even without arguments, this Vector still has one element: the currently executing binary itself, which in this example is "target/debug/minigrep". So the arguments we actually need begin at the second element of args, that is, at index 1.

Once we know where the needed arguments are stored, we can declare variables to hold them. Declare query to store the text to search for, and filename to store the file name:

let query = &args[1]; 
let filename = &args[2];

This works, but if the user enters too few arguments and the index is out of bounds, Rust will panic and stop the program. Of course, you can also combine match with get:

let query = match args.get(1) {  
    Some(arg) => arg,  
    None => panic!("No query provided"),  
};  
let filename = match args.get(2) {  
    Some(arg) => arg,  
    None => panic!("No file name provided"),  
};

We will use the first approach here.

Then print the two variables so the user can confirm the input:

println!("search for {}", query);  
println!("In file {}", filename);

12.1.3 The Full Code

Here is all the code written up to this article:

use std::env;  

fn main() {  
    let args:Vec<String> = env::args().collect();  
    let query = &args[1];  
    let filename = &args[2];

    println!("search for {}", query);  
    println!("In file {}", filename);  
}

11.10. Integration Tests

SomeB1oody — Sat, 23 May 2026 22:05:46 +0000

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:

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):

use RustStudy;

#[test]
fn it_adds_two() {
    let result = RustStudy::add_two(2);
    assert_eq!(result, 4);
}

Output:

$ 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:

$ 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.

[Rust Guide] 11.9. Unit Tests

SomeB1oody — Sat, 23 May 2026 22:01:33 +0000

If you find this helpful, please like, bookmark, and follow. To keep learning along, follow this series.

11.9.1 Test Categories

Rust divides tests into two categories: unit tests and integration tests.

Unit tests are smaller and more focused. Each one tests a single module in isolation, and they can also test private interfaces.
Integration tests live completely outside the codebase. They use your code the same way external code does. Integration tests can only access public interfaces, and each test may use multiple modules.

11.9.2 The `#[cfg(test)]` Annotation

The purpose of unit tests is to isolate a small piece of code so we can quickly determine whether it behaves as expected. We usually keep unit tests and the code under test in the same file under src.

By convention, each source file should also have a test module to hold these functions, and #[cfg(test)] is used to annotate the test module. Code marked with this annotation is compiled and run only when cargo test is executed; it is not compiled when you run cargo build.

Those are the rules for unit tests. Integration tests live in a different directory, so they do not need the #[cfg(test)] annotation.

cfg in #[cfg(test)] is short for configuration. Using it tells Rust that the annotated item is included only under the specified configuration option.

For example:

pub fn add(left: usize, right: usize) -> usize {
    left + right
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn it_works() {
        let result = add(2, 2);
        assert_eq!(result, 4);
    }
}

The configuration option in #[cfg(test)] is test. This configuration option is provided by Rust for compiling and running tests, and items under #[cfg(test)] are compiled and run only when you execute cargo test.

11.9.3 Testing Private Functions

Rust allows you to test private functions, which is not always the case in other languages.

For example:

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);
    }
}

Even though internal_adder is not declared public with pub, it can still be called inside the test module.

[Rust Guide] 11.8. Ignoring Tests

SomeB1oody — Sat, 23 May 2026 22:00:37 +0000

If you find this helpful, please like, bookmark, and follow. To keep learning along, follow this series.

11.8.1 Ignore Some Tests and Run the Rest

Some tests take a long time to run, so in most cases you may want to ignore them when running cargo test unless you explicitly run them.

For these tests, Rust provides the ignore attribute, which marks them as not run by default.

For example:

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn it_works() {
        let result = add(2, 2);
        assert_eq!(result, 4);
    }

    #[test]
    #[ignore]
    fn expensive_test() {
        assert_eq!(5, 1 + 1 + 1 + 1 + 1)
    }
}

Because expensive_test is marked with the ignore attribute, it will not run under cargo test unless you explicitly ask for it.

Here is the test output:

$ cargo test
   Compiling adder v0.1.0 (file:///projects/adder)
    Finished `test` profile [unoptimized +debuginfo] target(s) in 0.60s
     Running unittests src/lib.rs (target/debug/deps/adder-92948b65e88960b4)

running 2 tests
test tests::expensive_test ... ignored
test tests::it_works ... ok

test result: ok. 1 passed; 0 failed; 1 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

11.8.2 Run Only Ignored Tests

How do you run only the ignored tests? Add the argument cargo test -- --ignored:

$ cargo test -- --ignored
   Compiling adder v0.1.0 (file:///projects/adder)
    Finished `test` profile [unoptimized +debuginfo] target(s) in 0.61s
     Running unittests src/lib.rs (target/debug/deps/adder-92948b65e88960b4)

running 1 test
test expensive_test ... ok

test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 1 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

Controlling which tests the program runs ensures that cargo test returns quickly. If you have plenty of time and want to run all tests, including both ignored and non-ignored ones, use cargo test -- --include-ignored.

[Rust Guide] 11.7. Running Tests by Name

SomeB1oody — Sat, 23 May 2026 21:59:40 +0000

If you find this helpful, please like, bookmark, and follow. To keep learning along, follow this series.

11.7.1 Running a Subset of Tests by Name

If you want to choose which tests to run, pass the test name or names as arguments to cargo test.

For example:

pub fn add_two(a: usize) -> usize {
    a + 2
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn add_two_and_two() {
        let result = add_two(2);
        assert_eq!(result, 4);
    }

    #[test]
    fn add_three_and_two() {
        let result = add_two(3);
        assert_eq!(result, 5);
    }

    #[test]
    fn one_hundred() {
        let result = add_two(100);
        assert_eq!(result, 102);
    }
}

If you only want to run the one_hundred test, write cargo test one_hundred:

$ cargo test one_hundred
   Compiling adder v0.1.0 (file:///projects/adder)
    Finished `test` profile [unoptimized +debuginfo] target(s) in 0.69s
     Running unittests src/lib.rs (target/debug/deps/adder-92948b65e88960b4)

running 1 test
test tests::one_hundred ... ok

test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 2 filtered out; finished in 0.00s

To run a single test, just specify its exact name. To run multiple tests, specify part of the test name (module names work too) as the argument, and all tests that match that name will run.

For example, if I want to run add_two_and_two() and add_three_and_two, both of which contain add in their names, I can write cargo test add:

$ cargo test add
   Compiling adder v0.1.0 (file:///projects/adder)
    Finished `test` profile [unoptimized +debuginfo] target(s) in 0.61s
     Running unittests src/lib.rs (target/debug/deps/adder-92948b65e88960b4)

running 2 tests
test tests::add_three_and_two ... ok
test tests::add_two_and_two ... ok

test result: ok. 2 passed; 0 failed; 0 ignored; 0 measured; 1 filtered out; finished in 0.00s

DEV Community: SomeB1oody

[Rust Guide]12.8. Writing Error Messages to Standard Error

12.8.0 Before We Begin

12.8.1 Review

12.8.2 Standard Output vs. Standard Error

12.8.3 Modifying the Code

[Rust Guide] 12.7. Using Environment Variables

12.7.0 Before We Begin

12.7.1 Review

12.7.2 What Is TDD?

12.7.3 Write a Failing Test

12.7.4 Write or Modify Just Enough Code for the New Test to Pass

12.7.5 Use This Function in run

12.7.6 The Full Code and a Trial Run

[Rust Guide] 12.6. Developing Library Functionality with TDD

12.6.0 Before We Begin

12.6.1 Review

12.6.2 What Is Test-Driven Development?

12.6.3 Modifying the Code

1. Write a Failing Test

2. Write Just Enough Code for the New Test to Pass

3. Use This Function in run

12.6.3 The Full Code and a Trial Run

[Rust Guide] 12.5. Refactoring Pt.3 - Moving Business Logic

12.5.0 Before We Begin

12.5.1 Review

12.5.2 Extracting Logic from main

12.5.3 Improving Error Handling in run

12.5.4 Moving the Business Logic

[Rust Guide] 12.4. Refactoring Pt.2 - Error Handling

12.4.0 Before We Begin

12.4.1 Review

12.4.2 Unexpected Input

12.4.3 Specifying Error Messages

12.4.4 Using the Result Type

12.4.5 The Full Code

[Rust Guide] 12.3. Refactoring Pt.1 - Improving Modularity

12.3.0 Before We Begin

12.3.1 Why Refactor

12.3.2 A Guiding Principle for Separating Concerns in Binary Programs

12.3.3 Separating Logic

12.3.4 Using a Struct

12.3.5 Turning a Function Into a Struct Method

12.3.5 The Full Code

[Rust Guide] 12.2. Reading Files

12.2.0 Before We Begin

12.2.2 Review

12.2.3 Reading a File

12.2.4 Testing the Code

[Rust Guide] 12.1. Receiving Command-Line Arguments

12.1.0 Before We Begin

12.1.1 Standardizing the Input Format

12.1.2 Reading Command-Line Arguments

12.1.3 The Full Code

11.10. Integration Tests

11.10.1 What Are Integration Tests

11.10.2 The tests Directory

1. Create the tests Directory

2. Create a Test File

3. Move the Test Code Into the Test File

11.10.3 Running a Specific Integration Test

11.10.4 Submodules in Integration Tests

11.10.5 Integration Tests for Binary Crates

[Rust Guide] 11.9. Unit Tests

11.9.1 Test Categories

11.9.2 The #[cfg(test)] Annotation

11.9.3 Testing Private Functions

[Rust Guide] 11.8. Ignoring Tests

11.8.1 Ignore Some Tests and Run the Rest

11.8.2 Run Only Ignored Tests

[Rust Guide] 11.7. Running Tests by Name

11.7.1 Running a Subset of Tests by Name

12.7.5 Use This Function in `run`

3. Use This Function in `run`

12.5.2 Extracting Logic from `main`

12.5.3 Improving Error Handling in `run`

12.4.4 Using the `Result` Type

11.10.2 The `tests` Directory

1. Create the `tests` Directory

11.9.2 The `#[cfg(test)]` Annotation