Struct tracing_mock::span::ExpectedSpan

source ·

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

source

pub fn named(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();

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

source

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

source

pub fn with_target(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();

source

pub fn with_explicit_parent(self, parent: Option<&str>) -> NewSpan

Configures this ExpectedSpan to expect an explicit parent span or to be an explicit root.

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 Some("parent_name") is passed to with_explicit_parent then, the provided string is the name of the parent span to expect.

To expect that a span is recorded with no parent, None can be passed to with_explicit_parent instead.

If a span is recorded without an explicit parent, or if the explicit parent has a different name, this expectation will fail.

§Examples

The explicit parent is matched by name:

use tracing_mock::{collector, expect};

let span = expect::span()
    .with_explicit_parent(Some("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_explicit_parent(None);

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

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_explicit_parent(Some("parent_span"));

let (collector, handle) = collector::mock()
    .new_span(parent_span.clone())
    .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();

source

pub fn with_contextual_parent(self, parent: Option<&str>) -> NewSpan

Configures this ExpectedSpan to expect a contextually-determined parent span, or be a contextual root.

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.

The provided string is the name of the parent span to expect. To expect that the event is a contextually-determined root, pass None instead.

To expect a span with an explicit parent span, use ExpectedSpan::with_explicit_parent.

If a span is recorded which is not inside a span, has an explicitly overridden parent span, or has a differently-named span as its parent, this expectation will fail.

§Examples

The contextual parent is matched by name:

use tracing_mock::{collector, expect};

let parent_span = expect::span().named("parent_span");
let span = expect::span()
    .with_contextual_parent(Some("parent_span"));

let (collector, handle) = collector::mock()
    .new_span(parent_span.clone())
    .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_contextual_parent(None);

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 recorded with an explicit parent:

use tracing_mock::{collector, expect};

let span = expect::span()
    .with_contextual_parent(Some("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();

source

pub fn with_fields(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();