7b2cbc631e
Many of the methods on `MockCollector` take an `ExpectedSpan`. This
often requires significant boilerplate. For example, to expect that a
span with a specific name enters and then exits, the following code is
needed:
```rust
let span = expect::span().named("span name");
let (collector, handle) = collector::mock()
.enter(span.clone())
.exit(span)
.run_with_handle();
```
In order to make using `tracing-mock` more ergonomic and also more
compact, the `MockCollector` and `MockSubscriber` methods that previous
took an `ExpectedSpan`, are now generic over `Into<ExpectedSpan>`.
There are currently 3 implementations of `From` for `ExpectedSpan` which
allow the following shorthand uses:
`T: Into<String>` - an `ExpectedSpan` will be created that expects to
have a name specified by `T`.
```rust
let (collector, handle) = collector::mock()
.enter("span name")
.exit("span name")
.run_with_handle();
```
`&ExpectedId` - an `ExpectedSpan` will be created that expects to have
the expected Id. A reference is taken and cloned internally because the
caller always needs to use an `ExpectedId` in at least 2 calls to the
mock collector/subscriber.
```rust
let id = expect::id();
let (collector, handle) = collector::mock()
.new_span(&id)
.enter(&id)
.run_with_handle();
```
`&ExpectedSpan` - The expected span is taken by reference and cloned.
```rust
let span = expect::span().named("span name");
let (collector, handle) = collector::mock()
.enter(&span)
.exit(&span)
.run_with_handle();
```
In Rust, taking a reference to an object and immediately cloning it is
an anti-pattern. It is considered better to force the user to clone
outside the API to make the cloning explict.
However, in the case of a testing framework, it seems reasonable to
prefer a more concise API, rather than having it more explicit.
To reduce the size of this PR and to avoid unnecessary churn in other
crates, the tests within the tracing repo which use `tracing-mock` will
not be updated to use the new `Into<ExpectedSpan>` capabilities. The new
API is backwards compatible and those tests can remain as they are.
tracing-mock
Utilities for testing [tracing][tracing] and crates that uses it.
Overview
[tracing] is a framework for instrumenting Rust programs to collect
structured, event-based diagnostic information. tracing-mock provides
tools for making assertions about what tracing diagnostics are emitted
by code under test.
Compiler support: requires rustc 1.63+
Usage
tracing-mock crate provides a mock
Collector
that allows asserting on the order and contents of
spans and
events.
As tracing-mock isn't available on crates.io
yet, you must import it via git. When using tracing-mock with the
tracing 0.1 ecosystem, it is important that you also override the
source of any tracing crates that are transient dependencies. For
example, the Cargo.toml for your test crate could contain:
[dependencies]
lib-under-test = "1.0" # depends on `tracing`
[dev-dependencies]
tracing-mock = { git = "https://github.com/tokio-rs/tracing", branch = "v0.1.x", version = "0.1" }
tracing = { git = "https://github.com/tokio-rs/tracing", branch = "v0.1.x", version = "0.1" }
[patch.crates-io]
tracing = { git = "https://github.com/tokio-rs/tracing", branch = "v0.1.x" }
tracing-core = { git = "https://github.com/tokio-rs/tracing", branch = "v0.1.x" }
Examples
The following examples are for the master branch. For examples that
will work with tracing from [crates.io], please check the
v0.1.x
branch.
Below is an example that checks that an event contains a message:
use tracing::subscriber::with_default;
use tracing_mock::{subscriber, expect, field};
fn yak_shaving() {
tracing::info!("preparing to shave yaks");
}
let (subscriber, handle) = subscriber::mock()
.event(expect::event().with_fields(expect::message("preparing to shave yaks")))
.only()
.run_with_handle();
with_default(subscriber, || {
yak_shaving();
});
handle.assert_finished();
Below is a slightly more complex example. tracing-mock asserts that, in order:
- a span is created with a single field/value pair
- the span is entered
- an event is created with the field
number_of_yaks, a corresponding value of 3, and the message "preparing to shave yaks", and nothing else - an event is created with the field
all_yaks_shaved, a corresponding value oftrue, and the message "yak shaving completed" - the span is exited
- no further traces are received
use tracing::subscriber::with_default;
use tracing_mock::{subscriber, expect};
#[tracing::instrument]
fn yak_shaving(number_of_yaks: u32) {
tracing::info!(number_of_yaks, "preparing to shave yaks");
let number_shaved = number_of_yaks; // shave_all
tracing::info!(
all_yaks_shaved = number_shaved == number_of_yaks,
"yak shaving completed."
);
}
let yak_count: u32 = 3;
let span = expect::span().named("yak_shaving");
let (subscriber, handle) = subscriber::mock()
.new_span(
span.clone()
.with_fields(expect::field("number_of_yaks").with_value(&yak_count).only()),
)
.enter(span.clone())
.event(
expect::event().with_fields(
expect::field("number_of_yaks")
.with_value(&yak_count)
.and(expect::message("preparing to shave yaks"))
.only(),
),
)
.event(
expect::event().with_fields(
expect::field("all_yaks_shaved")
.with_value(&true)
.and(expect::message("yak shaving completed."))
.only(),
),
)
.exit(span.clone())
.only()
.run_with_handle();
with_default(subscriber, || {
yak_shaving(yak_count);
});
handle.assert_finished();
Supported Rust Versions
Tracing is built against the latest stable release. The minimum supported version is 1.63. The current Tracing version is not guaranteed to build on Rust versions earlier than the minimum supported version.
Tracing follows the same compiler support policies as the rest of the Tokio project. The current stable Rust compiler and the three most recent minor versions before it will always be supported. For example, if the current stable compiler version is 1.69, the minimum supported version will not be increased past 1.66, three minor versions prior. Increasing the minimum supported compiler version is not considered a semver breaking change as long as doing so complies with this policy.
License
This project is licensed under the MIT license.
Contribution
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in Tracing by you, shall be licensed as MIT, without any additional terms or conditions.