test-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 terminal.
This crate takes care of this per-test initialization in an intuitive way.
The crate provides a custom #[test]
attribute that, when used for
running a particular test, takes care of initializing log
and/or
tracing
beforehand.
As such, usage is as simple as importing and using said attribute:
use test_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_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_log::test;
#[test(tokio::test)]
async fn it_still_works() {
// ...
}
The crate comes with two features pertaining "backend" initialization:
log
, enabled by default, controls initialization for thelog
crate.trace
, disabled by default, controls initialization for thetracing
crate.
Depending on what backend the crate-under-test (and its dependencies) use, the respective feature(s) should be enabled to make messages that are emitted by the test manifest on the terminal.
On top of that, the color
feature (enabled by default) controls
whether to color output by default.
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 and
tracing-subscriber
documentation for supported
syntax and 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.
This crate adheres to Cargo's semantic versioning rules.
At a minimum, it builds with the most recent Rust stable release minus
five minor versions ("N - 5"). E.g., assuming the most recent Rust
stable is 1.68
, the crate is guaranteed to build with 1.63
and
higher.