Module span

Define expectations to match and validate spans.

The ExpectedSpan and NewSpan structs define expectations for spans to be matched by the mock collector API in the collector module.

Expected spans should be created with expect::span and a chain of method calls describing the assertions made about the span. Expectations about the lifecycle of the span can be set on the MockCollector.

Examples

use tracing_mock::{collector, expect};

let span = expect::span()
    .named("interesting_span")
    .at_level(tracing::Level::INFO);

let (collector, handle) = collector::mock()
    .enter(&span)
    .exit(&span)
    .run_with_handle();

tracing::collect::with_default(collector, || {
   let span = tracing::info_span!("interesting_span");
    let _guard = span.enter();
});

handle.assert_finished();

Instead of passing an ExpectedSpan, the collector methods will also accept anything that implements Into<String> which is shorthand for expect::span().named(name).

use tracing_mock::collector;

let (collector, handle) = collector::mock()
    .enter("interesting_span")
    .run_with_handle();

tracing::collect::with_default(collector, || {
   let span = tracing::info_span!("interesting_span");
    let _guard = span.enter();
});

handle.assert_finished();

The following example asserts the name, level, parent, and fields of the span:

use tracing_mock::{collector, expect};

let span = expect::span()
    .named("interesting_span")
    .at_level(tracing::Level::INFO);
let new_span = span
    .clone()
    .with_fields(expect::field("field.name").with_value(&"field_value"))
    .with_ancestry(expect::has_explicit_parent("parent_span"));

let (collector, handle) = collector::mock()
    .new_span("parent_span")
    .new_span(new_span)
    .enter(&span)
    .exit(&span)
    .run_with_handle();

tracing::collect::with_default(collector, || {
    let parent = tracing::info_span!("parent_span");

    let span = tracing::info_span!(
        parent: parent.id(),
        "interesting_span",
        field.name = "field_value",
    );
    let _guard = span.enter();
});

handle.assert_finished();

All expectations must be met for the test to pass. For example, the following test will fail due to a mismatch in the spans’ names:

use tracing_mock::{collector, expect};

let span = expect::span()
    .named("interesting_span")
    .at_level(tracing::Level::INFO);

let (collector, handle) = collector::mock()
    .enter(&span)
    .exit(&span)
    .run_with_handle();

tracing::collect::with_default(collector, || {
   let span = tracing::info_span!("another_span");
   let _guard = span.enter();
});

handle.assert_finished();

Structs

• ExpectedId
  A mock span ID.
• ExpectedSpan
  A mock span.
• NewSpan
  A mock new span.