Module collector

An implementation of the Collect trait to receive and validate tracing data.

The MockCollector is the central component of this crate. The MockCollector has expectations set on it which are later validated as the code under test is run.

Examples

use tracing_mock::{collector, expect, field};

let (collector, handle) = collector::mock()
    // Expect a single event with a specified message
    .event(expect::event().with_fields(expect::msg("droids")))
    .only()
    .run_with_handle();

// Use `with_default` to apply the `MockCollector` for the duration
// of the closure - this is what we are testing.
tracing::collect::with_default(collector, || {
    // These *are* the droids we are looking for
    tracing::info!("droids");
});

// Use the handle to check the assertions. This line will panic if an
// assertion is not met.
handle.assert_finished();

A more complex example may consider multiple spans and events with their respective fields:

use tracing_mock::{collector, expect, field};

let span = expect::span()
    .named("my_span");
let (collector, handle) = collector::mock()
    // Enter a matching span
    .enter(&span)
    // Record an event with message "collect parting message"
    .event(expect::event().with_fields(expect::msg("collect parting message")))
    // Record a value for the field `parting` on a matching span
    .record(&span, expect::field("parting").with_value(&"goodbye world!"))
    // Exit a matching span
    .exit(span)
    // Expect no further messages to be recorded
    .only()
    // Return the collector and handle
    .run_with_handle();

// Use `with_default` to apply the `MockCollector` for the duration
// of the closure - this is what we are testing.
tracing::collect::with_default(collector, || {
    let span = tracing::trace_span!(
        "my_span",
        greeting = "hello world",
        parting = tracing::field::Empty
    );

    let _guard = span.enter();
    tracing::info!("collect parting message");
    let parting = "goodbye world!";

    span.record("parting", &parting);
});

// Use the handle to check the assertions. This line will panic if an
// assertion is not met.
handle.assert_finished();

If we modify the previous example so that we don’t enter the span before recording an event, the test will fail:

use tracing_mock::{collector, expect, field};

let span = expect::span()
    .named("my_span");
let (collector, handle) = collector::mock()
    .enter(&span)
    .event(expect::event().with_fields(expect::msg("collect parting message")))
    .record(&span, expect::field("parting").with_value(&"goodbye world!"))
    .exit(span)
    .only()
    .run_with_handle();

// Use `with_default` to apply the `MockCollector` for the duration
// of the closure - this is what we are testing.
tracing::collect::with_default(collector, || {
    let span = tracing::trace_span!(
        "my_span",
        greeting = "hello world",
        parting = tracing::field::Empty
    );

    // Don't enter the span.
    // let _guard = span.enter();
    tracing::info!("collect parting message");
    let parting = "goodbye world!";

    span.record("parting", &parting);
});

// Use the handle to check the assertions. This line will panic if an
// assertion is not met.
handle.assert_finished();

This will result in an error message such as the following:

thread 'main' panicked at '
[main] expected to enter a span named `my_span`
[main] but instead observed event Event {
    fields: ValueSet {
        message: collect parting message,
        callsite: Identifier(0x10eda3278),
    },
    metadata: Metadata {
        name: "event src/collector.rs:27",
        target: "rust_out",
        level: Level(
            Info,
        ),
        module_path: "rust_out",
        location: src/collector.rs:27,
        fields: {message},
        callsite: Identifier(0x10eda3278),
        kind: Kind(EVENT),
    },
    parent: Current,
}', tracing/tracing-mock/src/expect.rs:59:33

Structs

• MockCollector
  A collector which can validate received traces.
• MockHandle
  A handle which is used to invoke validation of expectations.

Functions

• mock
  Create a new MockCollector.