Expand description

serial_test

serial_test allows for the creation of serialised Rust tests using the serial attribute e.g.

#[test]
#[serial]
fn test_serial_one() {
  // Do things
}

#[test]
#[serial]
fn test_serial_another() {
  // Do things
}

#[test]
#[parallel]
fn test_parallel_another() {
  // Do parallel things
}

Multiple tests with the serial attribute are guaranteed to be executed in serial. Ordering of the tests is not guaranteed however. Other tests with the parallel attribute may run at the same time as each other, but not at the same time as a test with serial. Tests with neither attribute may run at any time and no guarantees are made about their timing!

Note that if you’re using an async test reactor attribute (e.g. tokio::test or actix_rt::test) then they should be listed before serial/parallel, otherwise we don’t get an async function and things break. There’s now an error for this case to improve debugging.

For cases like doctests and integration tests where the tests are run as separate processes, we also support file_serial/file_parallel, with similar properties but based off file locking. Note that there are no guarantees about one test with serial/parallel and another with file_serial/file_parallel as they lock using different methods.

#[test]
#[file_serial]
fn test_serial_three() {
  // Do things
}

For each test, a timeout can be specified with the timeout_ms parameter to the serial attribute. Note that the timeout is counted from the first invocation of the test, not from the time the previous test was completed. This can lead to some unpredictable behavior based on the number of parallel tests run on the system.

#[test]
#[serial(timeout_ms = 1000)]
fn test_serial_one() {
  // Do things
}

Feature flags

  • logging (enabled by default) — Switches on debug logging (and requires the log package)

  • async (enabled by default) — Enables async features (and requires the futures package)

  • file_locks — The file_locks feature unlocks the file_serial/file_parallel macros (and requires the fslock package)

Attribute Macros

file_parallelfile_locks

Allows for the creation of file-serialised parallel Rust tests that won’t clash with file-serialised serial tests

file_serialfile_locks

Allows for the creation of file-serialised Rust tests

Allows for the creation of parallel Rust tests that won’t clash with serial tests

Allows for the creation of serialised Rust tests