pub struct ExpectedSpan { /* private fields */ }
Expand description
A mock span.
This is intended for use with the mock collector API in the
collector
module.
Implementations§
Source§impl ExpectedSpan
impl ExpectedSpan
Sourcepub fn named<I>(self, name: I) -> Self
pub fn named<I>(self, name: I) -> Self
Sets a name to expect when matching a span.
If an event is recorded with a name that differs from the one provided to this method, the expectation will fail.
§Examples
use tracing_mock::{collector, expect};
let span = expect::span().named("span name");
let (collector, handle) = collector::mock()
.enter(span)
.run_with_handle();
tracing::collect::with_default(collector, || {
let span = tracing::info_span!("span name");
let _guard = span.enter();
});
handle.assert_finished();
If only the name of the span needs to be validated, then
instead of using the named
method, a string can be passed
to the MockCollector
functions directly.
use tracing_mock::collector;
let (collector, handle) = collector::mock()
.enter("span name")
.run_with_handle();
tracing::collect::with_default(collector, || {
let span = tracing::info_span!("span name");
let _guard = span.enter();
});
handle.assert_finished();
When the span name is different, the assertion will fail:
use tracing_mock::{collector, expect};
let span = expect::span().named("span name");
let (collector, handle) = collector::mock()
.enter(span)
.run_with_handle();
tracing::collect::with_default(collector, || {
let span = tracing::info_span!("a different span name");
let _guard = span.enter();
});
handle.assert_finished();
Sourcepub fn with_id(self, id: ExpectedId) -> Self
pub fn with_id(self, id: ExpectedId) -> Self
Sets the ID
to expect when matching a span.
The ExpectedId
can be used to differentiate spans that are
otherwise identical. An ExpectedId
needs to be attached to
an ExpectedSpan
or NewSpan
which is passed to
MockCollector::new_span
. The same ExpectedId
can then
be used to match the exact same span when passed to
MockCollector::enter
, MockCollector::exit
, and
MockCollector::drop_span
.
This is especially useful when tracing-mock
is being used to
test the traces being generated within your own crate, in which
case you may need to distinguish between spans which have
identical metadata but different field values, which can
otherwise only be checked in MockCollector::new_span
.
§Examples
Here we expect that the span that is created first is entered second:
use tracing_mock::{collector, expect};
let id1 = expect::id();
let span1 = expect::span().named("span").with_id(id1.clone());
let id2 = expect::id();
let span2 = expect::span().named("span").with_id(id2.clone());
let (collector, handle) = collector::mock()
.new_span(&span1)
.new_span(&span2)
.enter(&span2)
.enter(&span1)
.run_with_handle();
tracing::collect::with_default(collector, || {
fn create_span() -> tracing::Span {
tracing::info_span!("span")
}
let span1 = create_span();
let span2 = create_span();
let _guard2 = span2.enter();
let _guard1 = span1.enter();
});
handle.assert_finished();
Since ExpectedId
implements Into<ExpectedSpan>
, in cases where
only checking on Id is desired, a shorthand version of the previous
example can be used.
use tracing_mock::{collector, expect};
let id1 = expect::id();
let id2 = expect::id();
let (collector, handle) = collector::mock()
.new_span(&id1)
.new_span(&id2)
.enter(&id2)
.enter(&id1)
.run_with_handle();
tracing::collect::with_default(collector, || {
fn create_span() -> tracing::Span {
tracing::info_span!("span")
}
let span1 = create_span();
let span2 = create_span();
let _guard2 = span2.enter();
let _guard1 = span1.enter();
});
handle.assert_finished();
If the order that the spans are entered changes, the test will fail:
use tracing_mock::{collector, expect};
let id1 = expect::id();
let span1 = expect::span().named("span").with_id(id1.clone());
let id2 = expect::id();
let span2 = expect::span().named("span").with_id(id2.clone());
let (collector, handle) = collector::mock()
.new_span(&span1)
.new_span(&span2)
.enter(&span2)
.enter(&span1)
.run_with_handle();
tracing::collect::with_default(collector, || {
fn create_span() -> tracing::Span {
tracing::info_span!("span")
}
let span1 = create_span();
let span2 = create_span();
let _guard1 = span1.enter();
let _guard2 = span2.enter();
});
handle.assert_finished();
Sourcepub fn at_level(self, level: Level) -> Self
pub fn at_level(self, level: Level) -> Self
Sets the Level
to expect when matching a span.
If an span is record with a level that differs from the one provided to this method, the expectation will fail.
§Examples
use tracing_mock::{collector, expect};
let span = expect::span()
.at_level(tracing::Level::INFO);
let (collector, handle) = collector::mock()
.enter(span)
.run_with_handle();
tracing::collect::with_default(collector, || {
let span = tracing::info_span!("span");
let _guard = span.enter();
});
handle.assert_finished();
Expecting a span at INFO
level will fail if the event is
recorded at any other level:
use tracing_mock::{collector, expect};
let span = expect::span()
.at_level(tracing::Level::INFO);
let (collector, handle) = collector::mock()
.enter(span)
.run_with_handle();
tracing::collect::with_default(collector, || {
let span = tracing::warn_span!("a serious span");
let _guard = span.enter();
});
handle.assert_finished();
Sourcepub fn with_target<I>(self, target: I) -> Self
pub fn with_target<I>(self, target: I) -> Self
Sets the target to expect when matching a span.
If an event is recorded with a target that doesn’t match the provided target, this expectation will fail.
§Examples
use tracing_mock::{collector, expect};
let span = expect::span()
.with_target("some_target");
let (collector, handle) = collector::mock()
.enter(span)
.run_with_handle();
tracing::collect::with_default(collector, || {
let span = tracing::info_span!(target: "some_target", "span");
let _guard = span.enter();
});
handle.assert_finished();
The test will fail if the target is different:
use tracing_mock::{collector, expect};
let span = expect::span()
.with_target("some_target");
let (collector, handle) = collector::mock()
.enter(span)
.run_with_handle();
tracing::collect::with_default(collector, || {
let span = tracing::info_span!(target: "a_different_target", "span");
let _guard = span.enter();
});
handle.assert_finished();
Sourcepub fn with_ancestry(self, ancestry: ExpectedAncestry) -> NewSpan
pub fn with_ancestry(self, ancestry: ExpectedAncestry) -> NewSpan
Configures this ExpectedSpan
to expect the specified
ExpectedAncestry
. A span’s ancestry indicates whether it has a
parent or is a root span and whether the parent is explitly or
contextually assigned.
Note: This method returns a NewSpan
and as such, this
expectation can only be validated when expecting a new span via
MockCollector::new_span
. It cannot be validated on
MockCollector::enter
, MockCollector::exit
, or any other
method on MockCollector
that takes an ExpectedSpan
.
An explicit parent span is one passed to the span!
macro in the
parent:
field. If no parent:
field is specified, then the span
will have a contextually determined parent or be a contextual root if
there is no parent.
If the ancestry is different from the provided one, this expectation will fail.
§Examples
An explicit or contextual parent can be matched on an ExpectedSpan
.
use tracing_mock::{collector, expect};
let parent = expect::span()
.named("parent_span")
.with_target("custom-target")
.at_level(tracing::Level::INFO);
let span = expect::span()
.with_ancestry(expect::has_explicit_parent(&parent));
let (collector, handle) = collector::mock()
.new_span(&parent)
.new_span(span)
.run_with_handle();
tracing::collect::with_default(collector, || {
let parent = tracing::info_span!(target: "custom-target", "parent_span");
tracing::info_span!(parent: parent.id(), "span");
});
handle.assert_finished();
The functions expect::has_explicit_parent
and
expect::has_contextual_parent
take Into<ExpectedSpan>
, so a string
passed directly will match on a span with that name, or an
ExpectedId
can be passed to match a span with that Id.
use tracing_mock::{collector, expect};
let span = expect::span()
.with_ancestry(expect::has_explicit_parent("parent_span"));
let (collector, handle) = collector::mock()
.new_span(expect::span().named("parent_span"))
.new_span(span)
.run_with_handle();
tracing::collect::with_default(collector, || {
let parent = tracing::info_span!("parent_span");
tracing::info_span!(parent: parent.id(), "span");
});
handle.assert_finished();
In the following example, the expected span is an explicit root:
use tracing_mock::{collector, expect};
let span = expect::span()
.with_ancestry(expect::is_explicit_root());
let (collector, handle) = collector::mock()
.new_span(span)
.run_with_handle();
tracing::collect::with_default(collector, || {
tracing::info_span!(parent: None, "span");
});
handle.assert_finished();
When expect::has_contextual_parent("parent_name")
is passed to
with_ancestry
then the provided string is the name of the contextual
parent span to expect.
use tracing_mock::{collector, expect};
let parent_span = expect::span().named("parent_span");
let span = expect::span()
.with_ancestry(expect::has_contextual_parent("parent_span"));
let (collector, handle) = collector::mock()
.new_span(&parent_span)
.enter(&parent_span)
.new_span(span)
.run_with_handle();
tracing::collect::with_default(collector, || {
let parent = tracing::info_span!("parent_span");
let _guard = parent.enter();
tracing::info_span!("span");
});
handle.assert_finished();
In the following example, we expect that the matched span is a contextually-determined root:
use tracing_mock::{collector, expect};
let span = expect::span()
.with_ancestry(expect::is_contextual_root());
let (collector, handle) = collector::mock()
.new_span(span)
.run_with_handle();
tracing::collect::with_default(collector, || {
tracing::info_span!("span");
});
handle.assert_finished();
In the example below, the expectation fails because the
span is contextually—as opposed to explicitly—within the span
parent_span
:
use tracing_mock::{collector, expect};
let parent_span = expect::span().named("parent_span");
let span = expect::span()
.with_ancestry(expect::has_explicit_parent("parent_span"));
let (collector, handle) = collector::mock()
.new_span(&parent_span)
.enter(&parent_span)
.new_span(span)
.run_with_handle();
tracing::collect::with_default(collector, || {
let parent = tracing::info_span!("parent_span");
let _guard = parent.enter();
tracing::info_span!("span");
});
handle.assert_finished();
Sourcepub fn with_fields<I>(self, fields: I) -> NewSpanwhere
I: Into<ExpectedFields>,
pub fn with_fields<I>(self, fields: I) -> NewSpanwhere
I: Into<ExpectedFields>,
Adds fields to expect when matching a span.
Note: This method returns a NewSpan
and as such, this
expectation can only be validated when expecting a new span via
MockCollector::new_span
. It cannot be validated on
MockCollector::enter
, MockCollector::exit
, or any other
method on MockCollector
that takes an ExpectedSpan
.
If a span is recorded with fields that do not match the provided
ExpectedFields
, this expectation will fail.
If the provided field is not present on the recorded span or if the value for that field diffs, then the expectation will fail.
More information on the available validations is available in
the ExpectedFields
documentation.
§Examples
use tracing_mock::{collector, expect};
let span = expect::span()
.with_fields(expect::field("field.name").with_value(&"field_value"));
let (collector, handle) = collector::mock()
.new_span(span)
.run_with_handle();
tracing::collect::with_default(collector, || {
tracing::info_span!("span", field.name = "field_value");
});
handle.assert_finished();
A different field value will cause the expectation to fail:
use tracing_mock::{collector, expect};
let span = expect::span()
.with_fields(expect::field("field.name").with_value(&"field_value"));
let (collector, handle) = collector::mock()
.new_span(span)
.run_with_handle();
tracing::collect::with_default(collector, || {
tracing::info_span!("span", field.name = "different_field_value");
});
handle.assert_finished();
Trait Implementations§
Source§impl Clone for ExpectedSpan
impl Clone for ExpectedSpan
Source§fn clone(&self) -> ExpectedSpan
fn clone(&self) -> ExpectedSpan
1.0.0 · Source§fn clone_from(&mut self, source: &Self)
fn clone_from(&mut self, source: &Self)
source
. Read more