test_log/lib.rs
1// Copyright (C) 2019-2023 Daniel Mueller <deso@posteo.net>
2// SPDX-License-Identifier: (Apache-2.0 OR MIT)
3
4#![deny(missing_docs)]
5
6//! A crate providing a replacement #[[macro@test]] attribute that
7//! initializes logging and/or tracing infrastructure before running
8//! tests.
9
10/// A procedural macro for the `test` attribute.
11///
12/// The attribute can be used to define a test that has the `env_logger`
13/// and/or `tracing` crates initialized (depending on the features used).
14///
15/// # Example
16///
17/// Specify the attribute on a per-test basis:
18/// ```rust
19/// # // doctests seemingly run in a slightly different environment where
20/// # // `super`, which is what our macro makes use of, is not available.
21/// # // By having a fake module here we work around that problem.
22/// # #[cfg(feature = "log")]
23/// # mod fordoctest {
24/// # use logging::info;
25/// # // Note that no test would actually run, regardless of `no_run`,
26/// # // because we do not invoke the function.
27/// #[test_log::test]
28/// fn it_works() {
29/// info!("Checking whether it still works...");
30/// assert_eq!(2 + 2, 4);
31/// info!("Looks good!");
32/// }
33/// # }
34/// ```
35///
36/// It can be very convenient to convert over all tests by overriding
37/// the `#[test]` attribute on a per-module basis:
38/// ```rust,no_run
39/// # mod fordoctest {
40/// use test_log::test;
41///
42/// #[test]
43/// fn it_still_works() {
44/// // ...
45/// }
46/// # }
47/// ```
48///
49/// You can also wrap another attribute. For example, suppose you use
50/// [`#[tokio::test]`](https://docs.rs/tokio/1.4.0/tokio/attr.test.html)
51/// to run async tests:
52/// ```
53/// # mod fordoctest {
54/// use test_log::test;
55///
56/// #[test(tokio::test)]
57/// async fn it_still_works() {
58/// // ...
59/// }
60/// # }
61/// ```
62pub use test_log_macros::test;
63
64#[cfg(feature = "trace")]
65#[doc(hidden)]
66pub use tracing_subscriber;
67
68#[cfg(feature = "log")]
69#[doc(hidden)]
70pub use env_logger;