Testing Environment-Dependent Code in Rust

2026-06-24T00:00:00+00:00

When we have a function that interacts with external resources, testing that code might be difficult because side-effects could impact on other tests. Environment variables are key-value pairs that are part of the process environment. One change in an env variable changes the process state, so this mutation persists throughout the process lifetime.

In Rust, unit tests are compiled into one binary, which means that all tests run in the same process. That is why we need to be careful when testing code that modifies env vars, because those changes may affect other tests and could produce an undesirable behaviour.

On top of that, Rust tests run in parallel by default, so we need to ensure that any thread modifying environment variables has exclusive access to the process environment.

Ensuring exclusive access to the Process Environment #</a> </h2>

One way to guarantee that there is only one thread with exclusive access to the process environment is to simply use one thread! We can achieve that by running cargo test -- --test-threads=1</code>. This is the simplest solution to the problem, however, if the number of unit tests in our project grows a lot, the execution time of the tests could be annoying because all tests, including the ones that do not need to be single-threaded, run on a single thread anyway.

Another solution more appropriate to this case is to use the macro #[serial]</code> from the serial_test</a> crate. This macro allows us to select the tests that we want to run in serial, while leaving the others unchanged.

#[cfg(test)]</span></span>
mod</span> tests</span> {</span></span>
    use</span> super</span>::*</span>;</span></span>
    use</span> serial_test</span>::</span>serial;</span></span>
    </span></span>
    #[test]</span></span>
    fn</span> normal_test1</span>() {</span></span>
        ...</span></span>
    }</span></span>
    </span></span>
    #[test]</span></span>
    fn</span> normal_test2</span>() {</span></span>
        ...</span></span>
    }</span></span>
</span>
    #[test]</span></span>
    #[serial]</span></span>
    fn</span> serial_test1</span>() {</span></span>
        ...</span></span>
    }</span></span>
    </span></span>
    #[test]</span></span>
    #[serial]</span></span>
    fn</span> serial_test2</span>() {</span></span>
        ...</span></span>
    }</span></span>
}</span></span></code></pre>
In this example, we guarantee that serial_test1</code> and serial_test2</code> run in serial, while (maybe) at the same time normal_test1</code> and normal_test2</code> run in parallel, so we get the best of both worlds.</p>
Why serial_test</code> alone isn't enough#</span></a>
</h2>
With serial_test</code> we solve the problem of concurrent access to the process environment, but we still have the problem that changes to env vars persist across the tests. We need to find a way to restore the previous state of the env vars that were modified, so that other tests are not contaminated.</p>
We may be tempted to do it with something like this:</p>
#[test]</span></span>
#[serial]</span></span>
fn</span> test</span>() {</span></span>
    let</span> var</span> =</span> "PATH"</span>;</span></span>
    let</span> previous_state</span> =</span> std</span>::</span>env</span>::</span>var_os</span>(var)</span>.</span>unwrap</span>();</span></span>
</span>
    ...</span> // test the function that modifies <var> env variable</span></span>
</span>
    // SAFETY: There are no other threads accessing the process environment because all tests that do it have #[serial] macro.</span></span>
    unsafe</span> {</span></span>
        std</span>::</span>env</span>::</span>set_var</span>(var, previous_state);</span></span>
    }</span></span>
}</span></span></code></pre>
However, this has a problem. The last statement may NEVER</em> run if the test panics, so this is not a solution at all.</p>
The RAII guard#</span></a>
</h2>
Rust implements RAII (Resource Acquisition Is Initialization), which means that once the owner of some data goes out of scope, the drop()</code> method of that data is called and the data is freed.</p>
We can take advantage of this by implementing a common design pattern in Rust: the RAII guard. We create an object that holds the original values of the environment variables that we are going to change, and implement the Drop trait so that it restores the process environment state when the object goes out of scope (even if the test panics).</p>
use</span> std</span>::</span>{</span>ffi</span>::</span>OsString</span>, env};</span></span>
</span>
struct</span> EnvGuard</span> {</span></span>
    key</span>:</span> OsString</span>,</span></span>
    value</span>:</span> Option</span><</span>OsString</span>></span></span>
}</span></span>
</span>
impl</span> EnvGuard</span> {</span></span>
    // SAFETY:</span></span>
    // The caller must guarantee exclusive access to the process environment</span></span>
    // for the lifetime of this guard.</span></span>
    unsafe fn</span> capture</span>(key</span>:</span> OsString</span>)</span> -></span> Self</span> {</span></span>
        Self</span> {</span></span>
            value</span>:</span> env</span>::</span>var_os</span>(</span>&</span>key),</span></span>
            key,</span></span>
        }</span></span>
    }</span></span>
}</span></span>
</span>
impl</span> Drop</span> for</span> EnvGuard</span> {</span></span>
    fn</span> drop</span>(</span>&mut</span> self</span>) {</span></span>
        // SAFETY:</span></span>
        // The caller of `capture` guaranteed exclusive access to the process</span></span>
        // environment for the lifetime of this guard.</span></span>
        unsafe</span> {</span></span>
            match &</span>self</span>.</span>value {</span></span>
                Some</span>(val)</span> =></span> env</span>::</span>set_var</span>(</span>&</span>self</span>.</span>key, val),</span></span>
                None</span> =></span> env</span>::</span>remove_var</span>(</span>&</span>self</span>.</span>key)</span></span>
            }</span></span>
        }</span></span>
    }</span></span>
}</span></span></code></pre>
Note that capture</code> itself performs no unsafe operation — it only calls env::var_os</code>, which is safe. It's marked unsafe</code> to push the safety contract to the call site, since that contract ("exclusive access to the environment") covers the guard's entire lifetime, not just this one function.</p>
Now we can use it in our tests</p>
#[test]</span></span>
#[serial]</span></span>
fn</span> test</span>() {</span></span>
    let</span> var</span> =</span> "PATH"</span>;</span></span>
    </span></span>
    // SAFETY: There are no other threads accessing the process environment because all tests that do it have #[serial] macro.</span></span>
    let</span> _guard</span> = unsafe</span> {</span> EnvGuard</span>::</span>capture</span>(var</span>.</span>into</span>()) };</span></span>
</span>
    ...</span> // test the function that modifies <var> env variable</span></span>
</span>
    // When `_guard` goes out of scope, even if the test panics, the env var is restored to the original value.</span></span>
}</span></span></code></pre>Result#</span></a>
</h2>
We end up with a simple and idiomatic solution to a common problem of testing environment variables. It is worth mentioning that this solution is easy to extend to multiple variables, and also it is easy to adapt to other external state besides the environment variables.</p>

If you spot something incorrect in this post, let me know — I'm still learning this too :)</em></p>

Federico Barberón

Testing Environment-Dependent Code in Rust