🛈 Note: This is pre-release documentation for the upcoming tracing 0.2.0 ecosystem.

For the release documentation, please see docs.rs, instead.

pub struct ExpectedEvent { /* private fields */ }
Expand description

An expected event.

For a detailed description and examples, see the documentation for the methods and the event module.

Implementations§

source§

impl ExpectedEvent

source

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

Sets a name to expect when matching an event.

By default, an event’s name takes takes the form: event <file>:<line> where <file> and <line> refer to the location in the source code where the event was generated.

To override the name of an event, it has to be constructed directly, rather than by using the tracing crate’s macros.

In general, there are not many use cases for expecting an event with a particular name, as the value includes the file name and line number. Assertions about event names are therefore quite fragile, since they will change as the source code is modified.

source

pub fn with_fields<I>(self, fields: I) -> Self
where I: Into<ExpectedFields>,

Adds fields to expect when matching an event.

If an event 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 event, or if the value for that field is different, then the expectation will fail.

More information on the available validations is available in the ExpectedFields documentation.

§Examples
use tracing::collect::with_default;
use tracing_mock::{collector, expect};

let event = expect::event()
    .with_fields(expect::field("field.name").with_value(&"field_value"));

let (collector, handle) = collector::mock()
    .event(event)
    .run_with_handle();

with_default(collector, || {
    tracing::info!(field.name = "field_value");
});

handle.assert_finished();

A different field value will cause the expectation to fail:

use tracing::collect::with_default;
use tracing_mock::{collector, expect};

let event = expect::event()
    .with_fields(expect::field("field.name").with_value(&"field_value"));

let (collector, handle) = collector::mock()
    .event(event)
    .run_with_handle();

with_default(collector, || {
    tracing::info!(field.name = "different_field_value");
});

handle.assert_finished();
source

pub fn at_level(self, level: Level) -> Self

Sets the Level to expect when matching an event.

If an event is recorded at a different level, this expectation will fail.

§Examples
use tracing::collect::with_default;
use tracing_mock::{collector, expect};

let event = expect::event()
    .at_level(tracing::Level::WARN);

let (collector, handle) = collector::mock()
    .event(event)
    .run_with_handle();

with_default(collector, || {
    tracing::warn!("this message is bad news");
});

handle.assert_finished();

Expecting an event at INFO level will fail if the event is recorded at any other level:

use tracing::collect::with_default;
use tracing_mock::{collector, expect};

let event = expect::event()
    .at_level(tracing::Level::INFO);

let (collector, handle) = collector::mock()
    .event(event)
    .run_with_handle();

with_default(collector, || {
    tracing::warn!("this message is bad news");
});

handle.assert_finished();
source

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

Sets the target to expect when matching events.

If an event is recorded with a different target, this expectation will fail.

§Examples
use tracing::collect::with_default;
use tracing_mock::{collector, expect};

let event = expect::event()
    .with_target("some_target");

let (collector, handle) = collector::mock()
    .event(event)
    .run_with_handle();

with_default(collector, || {
    tracing::info!(target: "some_target", field = &"value");
});

handle.assert_finished();

The test will fail if the target is different:

use tracing::collect::with_default;
use tracing_mock::{collector, expect};

let event = expect::event()
    .with_target("some_target");

let (collector, handle) = collector::mock()
    .event(event)
    .run_with_handle();

with_default(collector, || {
    tracing::info!(target: "a_different_target", field = &"value");
});

handle.assert_finished();
source

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

Configures this ExpectedEvent to expect an explicit parent span when matching events or to be an explicit root.

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 an event is recorded with parent: None, None can be passed to with_explicit_parent instead.

If an event 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::collect::with_default;
use tracing_mock::{collector, expect};

let event = expect::event()
    .with_explicit_parent(Some("parent_span"));

let (collector, handle) = collector::mock()
    .event(event)
    .run_with_handle();

with_default(collector, || {
    let parent = tracing::info_span!("parent_span");
    tracing::info!(parent: parent.id(), field = &"value");
});

handle.assert_finished();

In the following example, we expect that the matched event is an explicit root:

use tracing::collect::with_default;
use tracing_mock::{collector, expect};

let event = expect::event()
    .with_explicit_parent(None);

let (collector, handle) = collector::mock()
    .event(event)
    .run_with_handle();

with_default(collector, || {
    tracing::info!(parent: None, field = &"value");
});

handle.assert_finished();

In the example below, the expectation fails because the event is contextually (rather than explicitly) within the span parent_span:

use tracing::collect::with_default;
use tracing_mock::{collector, expect};

let event = expect::event()
    .with_explicit_parent(Some("parent_span"));

let (collector, handle) = collector::mock()
    .enter(expect::span())
    .event(event)
    .run_with_handle();

with_default(collector, || {
    let parent = tracing::info_span!("parent_span");
    let _guard = parent.enter();
    tracing::info!(field = &"value");
});

handle.assert_finished();
source

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

Configures this ExpectedEvent to match an event with a contextually-determined parent span.

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 an event with an explicit parent span, use ExpectedEvent::with_explicit_parent.

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

§Examples

The contextual parent is matched by name:

use tracing::collect::with_default;
use tracing_mock::{collector, expect};

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

let (collector, handle) = collector::mock()
    .enter(expect::span())
    .event(event)
    .run_with_handle();

with_default(collector, || {
    let parent = tracing::info_span!("parent_span");
    let _guard = parent.enter();
    tracing::info!(field = &"value");
});

handle.assert_finished();

Matching an event recorded outside of a span:

use tracing::collect::with_default;
use tracing_mock::{collector, expect};

let event = expect::event()
    .with_contextual_parent(None);

let (collector, handle) = collector::mock()
    .event(event)
    .run_with_handle();

with_default(collector, || {
    tracing::info!(field = &"value");
});

handle.assert_finished();

In the example below, the expectation fails because the event is recorded with an explicit parent:

use tracing::collect::with_default;
use tracing_mock::{collector, expect};

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

let (collector, handle) = collector::mock()
    .enter(expect::span())
    .event(event)
    .run_with_handle();

with_default(collector, || {
    let parent = tracing::info_span!("parent_span");
    tracing::info!(parent: parent.id(), field = &"value");
});

handle.assert_finished();
source

pub fn in_scope(self, spans: impl IntoIterator<Item = ExpectedSpan>) -> Self

Validates that the event is emitted within the scope of the provided spans.

The spans must be provided reverse hierarchy order, so the closest span to the event would be first, followed by its parent, and so on.

If the spans provided do not match the hierarchy of the recorded event, the expectation will fail.

Note: This validation currently only works with a MockSubscriber. If used with a MockCollector, the expectation will fail directly as it is unimplemented.

§Examples
use tracing_mock::{expect, subscriber};
use tracing_subscriber::{subscribe::CollectExt, util::SubscriberInitExt, Subscribe};

let event = expect::event().in_scope([
    expect::span().named("parent_span"),
    expect::span().named("grandparent_span")
]);

let (subscriber, handle) = subscriber::mock()
    .enter(expect::span())
    .enter(expect::span())
    .event(event)
    .run_with_handle();

let _collect = tracing_subscriber::registry()
    .with(subscriber.with_filter(tracing_subscriber::filter::filter_fn(move |_meta| true)))
    .set_default();

let grandparent = tracing::info_span!("grandparent_span");
let _gp_guard = grandparent.enter();
let parent = tracing::info_span!("parent_span");
let _p_guard = parent.enter();
tracing::info!(field = &"value");    

handle.assert_finished();

The scope must match exactly, otherwise the expectation will fail:

use tracing_mock::{expect, subscriber};
use tracing_subscriber::{subscribe::CollectExt, util::SubscriberInitExt, Subscribe};

let event = expect::event().in_scope([
    expect::span().named("parent_span"),
    expect::span().named("grandparent_span")
]);

let (subscriber, handle) = subscriber::mock()
    .enter(expect::span())
    .event(event)
    .run_with_handle();

let _collect = tracing_subscriber::registry()
    .with(subscriber.with_filter(tracing_subscriber::filter::filter_fn(move |_meta| true)))
    .set_default();

let parent = tracing::info_span!("parent_span");
let _p_guard = parent.enter();
tracing::info!(field = &"value");

handle.assert_finished();

It is also possible to test that an event has no parent spans by passing None to in_scope. If the event is within a span, the test will fail:

use tracing_mock::{expect, subscriber};
use tracing_subscriber::{subscribe::CollectExt, util::SubscriberInitExt, Subscribe};

let event = expect::event().in_scope(None);

let (subscriber, handle) = subscriber::mock()
    .enter(expect::span())
    .event(event)
    .run_with_handle();

let _collect = tracing_subscriber::registry()
    .with(subscriber.with_filter(tracing_subscriber::filter::filter_fn(move |_meta| true)))
    .set_default();

let parent = tracing::info_span!("parent_span");
let _guard = parent.enter();
tracing::info!(field = &"value");    

handle.assert_finished();

Trait Implementations§

source§

impl Debug for ExpectedEvent

source§

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

Formats the value using the given formatter. Read more
source§

impl Default for ExpectedEvent

source§

fn default() -> ExpectedEvent

Returns the “default value” for a type. Read more
source§

impl Display for ExpectedEvent

source§

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

Formats the value using the given formatter. Read more
source§

impl PartialEq for ExpectedEvent

source§

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

This method tests for self and other values to be equal, and is used by ==.
1.0.0 · source§

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

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.
source§

impl Eq for ExpectedEvent

source§

impl StructuralPartialEq for ExpectedEvent

Auto Trait Implementations§

Blanket Implementations§

source§

impl<T> Any for T
where T: 'static + ?Sized,

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
source§

impl<T> Borrow<T> for T
where T: ?Sized,

source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
source§

impl<T> From<T> for T

source§

fn from(t: T) -> T

Returns the argument unchanged.

source§

impl<T> Instrument for T

source§

fn instrument(self, span: Span) -> Instrumented<Self>

Instruments this type with the provided Span, returning an Instrumented wrapper. Read more
source§

fn in_current_span(self) -> Instrumented<Self>

Instruments this type with the current Span, returning an Instrumented wrapper. Read more
source§

impl<T, U> Into<U> for T
where U: From<T>,

source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

source§

impl<T> ToString for T
where T: Display + ?Sized,

source§

default fn to_string(&self) -> String

Converts the given value to a String. Read more
source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

§

type Error = Infallible

The type returned in the event of a conversion error.
source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
source§

impl<T> WithCollector for T

source§

fn with_collector<C>(self, collector: C) -> WithDispatch<Self>
where C: Into<Dispatch>,

Attaches the provided collector to this type, returning a WithDispatch wrapper. Read more
source§

fn with_current_collector(self) -> WithDispatch<Self>

Attaches the current default collector to this type, returning a WithDispatch wrapper. Read more