Struct ExpectedSpan

pub struct ExpectedSpan { /* private fields */ }

A mock span.

This is intended for use with the mock collector API in the collector module.

Implementations

impl ExpectedSpan

pub fn named<I>(self, name: I) -> Self

where I: Into<String>,

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();

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();

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();

pub fn with_target<I>(self, target: I) -> Self

where I: Into<String>,

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();

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();

pub fn with_fields<I>(self, fields: I) -> NewSpan

where 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

impl Clone for ExpectedSpan

fn clone(&self) -> ExpectedSpan

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for ExpectedSpan

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for ExpectedSpan

fn default() -> ExpectedSpan

Returns the “default value” for a type.

impl Display for ExpectedSpan

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl From<&ExpectedId> for ExpectedSpan

fn from(id: &ExpectedId) -> Self

Converts to this type from the input type.

impl From<&ExpectedSpan> for ExpectedSpan

fn from(span: &ExpectedSpan) -> Self

Converts to this type from the input type.

impl<I> From<I> for ExpectedSpan

where I: Into<String>,

fn from(name: I) -> Self

Converts to this type from the input type.

impl PartialEq for ExpectedSpan

fn eq(&self, other: &ExpectedSpan) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Eq for ExpectedSpan

impl StructuralPartialEq for ExpectedSpan