jstarks / test-env-log

A replacement of the #[test] attribute that initializes logging and/or tracing infrastructure before running tests.

test-env-log

• Documentation
• Changelog

test-env-log is a crate that takes care of automatically initializing logging and/or tracing for Rust tests.

When running Rust tests it can often be helpful to have easy access to the verbose log messages emitted by the code under test. Commonly, these log messages may be coming from the log crate or being emitted through the tracing infrastructure.

The problem with either -- in the context of testing -- is that some form of initialization is required in order to make these crate's messages appear on a standard output stream.

The commonly used env_logger (which provides an easy way to configure log based logging), for example, needs to be initialized like this:

let _ = env_logger::builder().is_test(true).try_init();

in each and every test.

Similarly, tracing based solutions require a subscriber to be registered that writes events/spans to the console.

This crate takes care of this per-test initialization in an intuitive way.

Usage

The crate provides a custom #[test] attribute that, when used for running a particular test, takes care of initializing log and/or tracing beforehand.

Example

As such, usage is as simple as importing and using said attribute:

use test_env_log::test;

#[test]
fn it_works() {
  info!("Checking whether it still works...");
  assert_eq!(2 + 2, 4);
  info!("Looks good!");
}

It is of course also possible to initialize logging for a chosen set of tests, by only annotating these with the custom attribute:

#[test_env_log::test]
fn it_still_works() {
  // ...
}

You can also wrap another attribute. For example, suppose you use #[tokio::test] to run async tests:

use test_env_log::test;

#[test(tokio::test)]
async fn it_still_works() {
  // ...
}

Logging Configuration

As usual when running cargo test, the output is captured by the framework by default and only shown on test failure. The --nocapture argument can be supplied in order to overwrite this setting. E.g.,

$ cargo test -- --nocapture

Furthermore, the RUST_LOG environment variable is honored and can be used to influence the log level to work with (among other things). Please refer to the env_logger docs for more information.

If the trace feature is enabled, the RUST_LOG_SPAN_EVENTS environment variable can be used to configure the tracing subscriber to log synthesized events at points in the span lifecycle. Set the variable to a comma-separated list of events you want to see. For example, RUST_LOG_SPAN_EVENTS=full or RUST_LOG_SPAN_EVENTS=new,close.

Valid events are new, enter, exit, close, active, and full. See the tracing_subscriber docs for details on what the events mean.

Features

The crate comes with two features:

• log, enabled by default, controls initialization for the log crate.
• trace, disabled by default, controls initialization for the tracing crate.

Depending on what backend the crate-under-test (and its dependencies) use, the respective feature should be enabled to make messages that are emitted by the test manifest on the console.

Note that as a user you are required to explicitly add env_logger or tracing-subscriber as a dependency to your project-under-test (when enabling the log or trace feature, respectively). E.g.,

[dev-dependencies]
env_logger = "*"
tracing = {version = "0.1", default-features = false}
tracing-subscriber = {version = "0.2.17", default-features = false, features = ["env-filter", "fmt"]}