Skip to content

Commit

Permalink
mock: document public APIs in span module
Browse files Browse the repository at this point in the history
This change adds documentation to the span module and all the public
APIs within it. This includes doctests on all the methods which serve as
examples.

Additionally, the validation on `ExpectedSpan` was improved so that it
validates the level and target during `enter` and `exit` as well as on
`new_span`.

The method `ExpectedSpan::with_field` was renamed to `with_fields`
(plural) to match the same method on `ExpectedEvent` (and because
multiple fields can be passed to it).

A copy-paste typo was also fixed in the documentation for
`ExpectedEvent::with_contextual_parent`.

Refs: #539
  • Loading branch information
hds committed Jan 12, 2023
1 parent dd67660 commit 6408d2d
Show file tree
Hide file tree
Showing 14 changed files with 602 additions and 77 deletions.
16 changes: 8 additions & 8 deletions tracing-attributes/tests/async_fn.rs
Original file line number Diff line number Diff line change
Expand Up @@ -191,16 +191,16 @@ fn async_fn_with_async_trait() {
let (collector, handle) = collector::mock()
.new_span(
span.clone()
.with_field(expect::field("self"))
.with_field(expect::field("v")),
.with_fields(expect::field("self"))
.with_fields(expect::field("v")),
)
.enter(span.clone())
.new_span(span3.clone())
.enter(span3.clone())
.event(expect::event().with_fields(expect::field("val").with_value(&2u64)))
.exit(span3.clone())
.drop_span(span3)
.new_span(span2.clone().with_field(expect::field("self")))
.new_span(span2.clone().with_fields(expect::field("self")))
.enter(span2.clone())
.event(expect::event().with_fields(expect::field("val").with_value(&5u64)))
.exit(span2.clone())
Expand Down Expand Up @@ -246,7 +246,7 @@ fn async_fn_with_async_trait_and_fields_expressions() {
let span = expect::span().named("call");
let (collector, handle) = collector::mock()
.new_span(
span.clone().with_field(
span.clone().with_fields(
expect::field("_v")
.with_value(&5usize)
.and(expect::field("test").with_value(&tracing::field::debug(10)))
Expand Down Expand Up @@ -314,21 +314,21 @@ fn async_fn_with_async_trait_and_fields_expressions_with_generic_parameter() {
let span4 = expect::span().named("sync_fun");
let (collector, handle) = collector::mock()
/*.new_span(span.clone()
.with_field(
.with_fields(
expect::field("Self").with_value(&"TestImpler")))
.enter(span.clone())
.exit(span.clone())
.drop_span(span)*/
.new_span(
span2
.clone()
.with_field(expect::field("Self").with_value(&std::any::type_name::<TestImpl>())),
.with_fields(expect::field("Self").with_value(&std::any::type_name::<TestImpl>())),
)
.enter(span2.clone())
.new_span(
span4
.clone()
.with_field(expect::field("Self").with_value(&std::any::type_name::<TestImpl>())),
.with_fields(expect::field("Self").with_value(&std::any::type_name::<TestImpl>())),
)
.enter(span4.clone())
.exit(span4)
Expand All @@ -337,7 +337,7 @@ fn async_fn_with_async_trait_and_fields_expressions_with_generic_parameter() {
.new_span(
span3
.clone()
.with_field(expect::field("Self").with_value(&std::any::type_name::<TestImpl>())),
.with_fields(expect::field("Self").with_value(&std::any::type_name::<TestImpl>())),
)
.enter(span3.clone())
.exit(span3.clone())
Expand Down
12 changes: 6 additions & 6 deletions tracing-attributes/tests/destructuring.rs
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ fn destructure_tuples() {

let (collector, handle) = collector::mock()
.new_span(
span.clone().with_field(
span.clone().with_fields(
expect::field("arg1")
.with_value(&format_args!("1"))
.and(expect::field("arg2").with_value(&format_args!("2")))
Expand Down Expand Up @@ -40,7 +40,7 @@ fn destructure_nested_tuples() {

let (collector, handle) = collector::mock()
.new_span(
span.clone().with_field(
span.clone().with_fields(
expect::field("arg1")
.with_value(&format_args!("1"))
.and(expect::field("arg2").with_value(&format_args!("2")))
Expand Down Expand Up @@ -72,7 +72,7 @@ fn destructure_refs() {
let (collector, handle) = collector::mock()
.new_span(
span.clone()
.with_field(expect::field("arg1").with_value(&1usize).only()),
.with_fields(expect::field("arg1").with_value(&1usize).only()),
)
.enter(span.clone())
.exit(span.clone())
Expand All @@ -98,7 +98,7 @@ fn destructure_tuple_structs() {

let (collector, handle) = collector::mock()
.new_span(
span.clone().with_field(
span.clone().with_fields(
expect::field("arg1")
.with_value(&format_args!("1"))
.and(expect::field("arg2").with_value(&format_args!("2")))
Expand Down Expand Up @@ -139,7 +139,7 @@ fn destructure_structs() {

let (collector, handle) = collector::mock()
.new_span(
span.clone().with_field(
span.clone().with_fields(
expect::field("arg1")
.with_value(&format_args!("1"))
.and(expect::field("arg2").with_value(&format_args!("2")))
Expand Down Expand Up @@ -184,7 +184,7 @@ fn destructure_everything() {

let (collector, handle) = collector::mock()
.new_span(
span.clone().with_field(
span.clone().with_fields(
expect::field("arg1")
.with_value(&format_args!("1"))
.and(expect::field("arg2").with_value(&format_args!("2")))
Expand Down
2 changes: 1 addition & 1 deletion tracing-attributes/tests/err.rs
Original file line number Diff line number Diff line change
Expand Up @@ -155,7 +155,7 @@ fn impl_trait_return_type() {
let (collector, handle) = collector::mock()
.new_span(
span.clone()
.with_field(expect::field("x").with_value(&10usize).only()),
.with_fields(expect::field("x").with_value(&10usize).only()),
)
.enter(span.clone())
.exit(span.clone())
Expand Down
18 changes: 9 additions & 9 deletions tracing-attributes/tests/fields.rs
Original file line number Diff line number Diff line change
Expand Up @@ -46,7 +46,7 @@ impl HasField {

#[test]
fn fields() {
let span = expect::span().with_field(
let span = expect::span().with_fields(
expect::field("foo")
.with_value(&"bar")
.and(expect::field("dsa").with_value(&true))
Expand All @@ -60,7 +60,7 @@ fn fields() {

#[test]
fn expr_field() {
let span = expect::span().with_field(
let span = expect::span().with_fields(
expect::field("s")
.with_value(&"hello world")
.and(expect::field("len").with_value(&"hello world".len()))
Expand All @@ -73,7 +73,7 @@ fn expr_field() {

#[test]
fn two_expr_fields() {
let span = expect::span().with_field(
let span = expect::span().with_fields(
expect::field("s")
.with_value(&"hello world")
.and(expect::field("s.len").with_value(&"hello world".len()))
Expand All @@ -87,7 +87,7 @@ fn two_expr_fields() {

#[test]
fn clashy_expr_field() {
let span = expect::span().with_field(
let span = expect::span().with_fields(
// Overriding the `s` field should record `s` as a `Display` value,
// rather than as a `Debug` value.
expect::field("s")
Expand All @@ -99,7 +99,7 @@ fn clashy_expr_field() {
fn_clashy_expr_field("hello world");
});

let span = expect::span().with_field(expect::field("s").with_value(&"s").only());
let span = expect::span().with_fields(expect::field("s").with_value(&"s").only());
run_test(span, || {
fn_clashy_expr_field2("hello world");
});
Expand All @@ -108,7 +108,7 @@ fn clashy_expr_field() {
#[test]
fn self_expr_field() {
let span =
expect::span().with_field(expect::field("my_field").with_value(&"hello world").only());
expect::span().with_fields(expect::field("my_field").with_value(&"hello world").only());
run_test(span, || {
let has_field = HasField {
my_field: "hello world",
Expand All @@ -119,7 +119,7 @@ fn self_expr_field() {

#[test]
fn parameters_with_fields() {
let span = expect::span().with_field(
let span = expect::span().with_fields(
expect::field("foo")
.with_value(&"bar")
.and(expect::field("param").with_value(&1u32))
Expand All @@ -132,15 +132,15 @@ fn parameters_with_fields() {

#[test]
fn empty_field() {
let span = expect::span().with_field(expect::field("foo").with_value(&"bar").only());
let span = expect::span().with_fields(expect::field("foo").with_value(&"bar").only());
run_test(span, || {
fn_empty_field();
});
}

#[test]
fn string_field() {
let span = expect::span().with_field(expect::field("s").with_value(&"hello world").only());
let span = expect::span().with_fields(expect::field("s").with_value(&"hello world").only());
run_test(span, || {
fn_string(String::from("hello world"));
});
Expand Down
14 changes: 7 additions & 7 deletions tracing-attributes/tests/instrument.rs
Original file line number Diff line number Diff line change
Expand Up @@ -64,7 +64,7 @@ fn fields() {
.with_target("my_target");
let (collector, handle) = collector::mock()
.new_span(
span.clone().with_field(
span.clone().with_fields(
expect::field("arg1")
.with_value(&2usize)
.and(expect::field("arg2").with_value(&false))
Expand All @@ -75,7 +75,7 @@ fn fields() {
.exit(span.clone())
.drop_span(span)
.new_span(
span2.clone().with_field(
span2.clone().with_fields(
expect::field("arg1")
.with_value(&3usize)
.and(expect::field("arg2").with_value(&true))
Expand Down Expand Up @@ -115,15 +115,15 @@ fn skip() {
let (collector, handle) = collector::mock()
.new_span(
span.clone()
.with_field(expect::field("arg1").with_value(&2usize).only()),
.with_fields(expect::field("arg1").with_value(&2usize).only()),
)
.enter(span.clone())
.exit(span.clone())
.drop_span(span)
.new_span(
span2
.clone()
.with_field(expect::field("arg1").with_value(&3usize).only()),
.with_fields(expect::field("arg1").with_value(&3usize).only()),
)
.enter(span2.clone())
.exit(span2.clone())
Expand Down Expand Up @@ -155,7 +155,7 @@ fn generics() {

let (collector, handle) = collector::mock()
.new_span(
span.clone().with_field(
span.clone().with_fields(
expect::field("arg1")
.with_value(&format_args!("Foo"))
.and(expect::field("arg2").with_value(&format_args!("false"))),
Expand Down Expand Up @@ -188,7 +188,7 @@ fn methods() {

let (collector, handle) = collector::mock()
.new_span(
span.clone().with_field(
span.clone().with_fields(
expect::field("self")
.with_value(&format_args!("Foo"))
.and(expect::field("arg1").with_value(&42usize)),
Expand Down Expand Up @@ -220,7 +220,7 @@ fn impl_trait_return_type() {
let (collector, handle) = collector::mock()
.new_span(
span.clone()
.with_field(expect::field("x").with_value(&10usize).only()),
.with_fields(expect::field("x").with_value(&10usize).only()),
)
.enter(span.clone())
.exit(span.clone())
Expand Down
2 changes: 1 addition & 1 deletion tracing-mock/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -121,7 +121,7 @@ let span = expect::span().named("yak_shaving");
let (collector, handle) = collector::mock()
.new_span(
span.clone()
.with_field(expect::field("number_of_yaks").with_value(&yak_count).only()),
.with_fields(expect::field("number_of_yaks").with_value(&yak_count).only()),
)
.enter(span.clone())
.event(
Expand Down
16 changes: 9 additions & 7 deletions tracing-mock/src/collector.rs
Original file line number Diff line number Diff line change
Expand Up @@ -21,12 +21,18 @@ use tracing::{
Collect, Event, Metadata,
};

struct SpanState {
pub(crate) struct SpanState {
name: &'static str,
refs: usize,
meta: &'static Metadata<'static>,
}

impl SpanState {
pub(crate) fn metadata(&self) -> &'static Metadata<'static> {
self.meta
}
}

struct Running<F: Fn(&Metadata<'_>) -> bool> {
spans: Mutex<HashMap<Id, SpanState>>,
expected: Arc<Mutex<VecDeque<Expect>>>,
Expand Down Expand Up @@ -329,9 +335,7 @@ where
match self.expected.lock().unwrap().pop_front() {
None => {}
Some(Expect::Enter(ref expected_span)) => {
if let Some(name) = expected_span.name() {
assert_eq!(name, span.name);
}
expected_span.check(span, &self.name);
}
Some(ex) => ex.bad(&self.name, format_args!("entered span {:?}", span.name)),
}
Expand All @@ -354,9 +358,7 @@ where
match self.expected.lock().unwrap().pop_front() {
None => {}
Some(Expect::Exit(ref expected_span)) => {
if let Some(name) = expected_span.name() {
assert_eq!(name, span.name);
}
expected_span.check(span, &self.name);
let curr = self.current.lock().unwrap().pop();
assert_eq!(
Some(id),
Expand Down
2 changes: 1 addition & 1 deletion tracing-mock/src/event.rs
Original file line number Diff line number Diff line change
Expand Up @@ -364,7 +364,7 @@ impl ExpectedEvent {
///
/// # Examples
///
/// The explicit parent is matched by name:
/// The contextual parent is matched by name:
///
/// ```
/// use tracing::collect::with_default;
Expand Down
Loading

0 comments on commit 6408d2d

Please sign in to comment.