Document using a Mutex to sequentalise tests

[nrc]

cc #42684

One can use a static Mutex to sequentialise tests, but this is not documented, afaik.

[durka]

I guess the trick is this:

use std::sync::Mutex;
#[macro_use] extern crate lazy_static;

lazy_static! {
    static ref TEST_MUTEX: Mutex<()> = Mutex::new(());
}

macro_rules! test {
    (fn $name:ident() $body:block) => {
        #[test]
        fn $name() {
            let _guard = $crate::TEST_MUTEX.lock().unwrap();
            $body
        }
    }
}

test! { fn one() { println!("one"); } }
test! { fn two() { println!("two"); } }

Where the preamble could certainly be put in a support crate.

[kriomant]

This approach has a problem: when one test fails with panic, remaining ones fail with PoisonError.

[durka]

Hmm, good point. I suppose an implementation like this can fix that:

macro_rules! test {
    (fn $name:ident() $body:block) => {
        #[test]
        fn $name() {
            let guard = $crate::TEST_MUTEX.lock().unwrap();
            if let Err(e) = panic::catch_unwind(|| { $body }) {
                drop(guard);
                panic::resume_unwind(e);
            }
        }
    }
}

Another reason to put this in a support crate (or the standard test harness) to avoid this and likely other traps.

[sfackler]

You don't need to do anything with catch_unwind - just don't unwrap the result.

[durka]

@sfackler Does a poisoned mutex still... mutex?

[sfackler]

Yes - the guard object is still inside of the error - https://doc.rust-lang.org/std/sync/struct.PoisonError.html#method.into_inner

[kriomant]

Yes, problem can be worked around using PoisonError::into_inner. However, trick becomes verbose and convoluted, we really need something built-in to avoid it.

[sfackler]

I agree in general (that's why I made https://docs.rs/antidote), but here, we're not accessing anything in the mutex so you can just save off the Result<MutexGuard> in the guard variable and not worry about it at all.

[marmistrz]

I couldn't agree more that we need something built-in. I tried adding the Mutex to my own tests, and this did not seem to work anyway. https://github.com/marmistrz/randmockery/blob/mutex/tests/test.rs

Setting RUST_TEST_THREADS=1 does the trick. Maybe it would simply be enough to allow setting this in Cargo.toml?

[sfackler]

@marmistrz let _ = mutex.lock() immediately discards the guard and unlocks the mutex. let _guard = mutex.lock() will do the right thing.

[frewsxcv]

I think I'm failing to understand why someone couldn't just use --test-threads=1 when running tests if they want them to be run in serial. I'm having trouble understanding why this is something we need to document