mock: differentiate between mocks and expectations (#2373)

The `tracing-mock` crate provides a mock collector (and a subscriber for
use by the tests in the `tracing-subscriber` crate) which is able to
make assertions about what diagnostics are emitted.

These assertions are defined by structs that match on events, span, and
their fields and metadata. The structs that matched these objects have
been called, up until now, mocks, however this terminology may be
misleading, as the created objects don't mock anything.

There were two different names for similar functionality with `only()`
and `done()` on fields and collectors/subscribers respectively. Using a
single name for these may make it easier to onboard onto `tracing-mock`.

To reduce confusion, these structs have been split into two categories:
mocks and expectations.

Additionally, the `done()` function on the `Collector` and `Subscriber`
mocks has been replaced with `only()`. This matches the similar function
for `ExpectedField`, and may be more intuitive.

The mocks replace some component in the tracing ecosystem when a library
is under test. The expectations define the assertions we wish to make
about traces received by the mocks.

Mocks (per module):
* collector - `MockCollector`, no change
* subscriber - `MockSubscriber`, renamed from `ExpectSubscriber`

Expectations (per module):
* event - `ExpectedEvent`, renamed from `MockEvent`
* span - `ExpectedSpan`, renamed from `MockSpan`
* field - `ExpectedField` and `ExpectedFields`, renamed from `MockField`
  and `Expected`. Also `ExpectedValue` renamed from `MockValue`.
* metadata - `ExpectedMetadata`, renamed from `Expected`

Refs: #539

Author: hds

tracing-attributes/tests/async_fn.rs

@@ -84,16 +84,16 @@ fn repro_1831_2() -> impl Future<Output = Result<(), Infallible>> {
 #[test]
 fn async_fn_only_enters_for_polls() {
     let (subscriber, handle) = subscriber::mock()
-        .new_span(span::mock().named("test_async_fn"))
-        .enter(span::mock().named("test_async_fn"))
-        .event(event::mock().with_fields(field::mock("awaiting").with_value(&true)))
-        .exit(span::mock().named("test_async_fn"))
-        .enter(span::mock().named("test_async_fn"))
-        .exit(span::mock().named("test_async_fn"))
-        .enter(span::mock().named("test_async_fn"))
-        .exit(span::mock().named("test_async_fn"))
-        .drop_span(span::mock().named("test_async_fn"))
-        .done()
+        .new_span(span::expect().named("test_async_fn"))
+        .enter(span::expect().named("test_async_fn"))
+        .event(event::expect().with_fields(field::expect("awaiting").with_value(&true)))
+        .exit(span::expect().named("test_async_fn"))
+        .enter(span::expect().named("test_async_fn"))
+        .exit(span::expect().named("test_async_fn"))
+        .enter(span::expect().named("test_async_fn"))
+        .exit(span::expect().named("test_async_fn"))
+        .drop_span(span::expect().named("test_async_fn"))
+        .only()
         .run_with_handle();
     with_default(subscriber, || {
         block_on_future(async { test_async_fn(2).await }).unwrap();
@@ -113,14 +113,14 @@ fn async_fn_nested() {
         tracing::trace!(nested = true);
     }
 
-    let span = span::mock().named("test_async_fns_nested");
-    let span2 = span::mock().named("test_async_fns_nested_other");
+    let span = span::expect().named("test_async_fns_nested");
+    let span2 = span::expect().named("test_async_fns_nested_other");
     let (subscriber, handle) = subscriber::mock()
         .new_span(span.clone())
         .enter(span.clone())
         .new_span(span2.clone())
         .enter(span2.clone())
-        .event(event::mock().with_fields(field::mock("nested").with_value(&true)))
+        .event(event::expect().with_fields(field::expect("nested").with_value(&true)))
         .exit(span2.clone())
         .enter(span2.clone())
         .exit(span2.clone())
@@ -129,7 +129,7 @@ fn async_fn_nested() {
         .enter(span.clone())
         .exit(span.clone())
         .drop_span(span)
-        .done()
+        .only()
         .run_with_handle();
 
     with_default(subscriber, || {
@@ -191,26 +191,26 @@ fn async_fn_with_async_trait() {
         }
     }
 
-    let span = span::mock().named("foo");
-    let span2 = span::mock().named("bar");
-    let span3 = span::mock().named("baz");
+    let span = span::expect().named("foo");
+    let span2 = span::expect().named("bar");
+    let span3 = span::expect().named("baz");
     let (subscriber, handle) = subscriber::mock()
         .new_span(
             span.clone()
-                .with_field(field::mock("self"))
-                .with_field(field::mock("v")),
+                .with_field(field::expect("self"))
+                .with_field(field::expect("v")),
         )
         .enter(span.clone())
         .new_span(span3.clone())
         .enter(span3.clone())
-        .event(event::mock().with_fields(field::mock("val").with_value(&2u64)))
+        .event(event::expect().with_fields(field::expect("val").with_value(&2u64)))
         .exit(span3.clone())
         .enter(span3.clone())
         .exit(span3.clone())
         .drop_span(span3)
-        .new_span(span2.clone().with_field(field::mock("self")))
+        .new_span(span2.clone().with_field(field::expect("self")))
         .enter(span2.clone())
-        .event(event::mock().with_fields(field::mock("val").with_value(&5u64)))
+        .event(event::expect().with_fields(field::expect("val").with_value(&5u64)))
         .exit(span2.clone())
         .enter(span2.clone())
         .exit(span2.clone())
@@ -219,7 +219,7 @@ fn async_fn_with_async_trait() {
         .enter(span.clone())
         .exit(span.clone())
         .drop_span(span)
-        .done()
+        .only()
         .run_with_handle();
 
     with_default(subscriber, || {
@@ -255,23 +255,23 @@ fn async_fn_with_async_trait_and_fields_expressions() {
         async fn call(&mut self, _v: usize) {}
     }
 
-    let span = span::mock().named("call");
+    let span = span::expect().named("call");
     let (subscriber, handle) = subscriber::mock()
         .new_span(
             span.clone().with_field(
-                field::mock("_v")
+                field::expect("_v")
                     .with_value(&5usize)
-                    .and(field::mock("test").with_value(&tracing::field::debug(10)))
-                    .and(field::mock("val").with_value(&42u64))
-                    .and(field::mock("val2").with_value(&42u64)),
+                    .and(field::expect("test").with_value(&tracing::field::debug(10)))
+                    .and(field::expect("val").with_value(&42u64))
+                    .and(field::expect("val2").with_value(&42u64)),
             ),
         )
         .enter(span.clone())
         .exit(span.clone())
         .enter(span.clone())
         .exit(span.clone())
         .drop_span(span)
-        .done()
+        .only()
         .run_with_handle();
 
     with_default(subscriber, || {
@@ -322,27 +322,27 @@ fn async_fn_with_async_trait_and_fields_expressions_with_generic_parameter() {
         async fn call_with_mut_self(&mut self) {}
     }
 
-    //let span = span::mock().named("call");
-    let span2 = span::mock().named("call_with_self");
-    let span3 = span::mock().named("call_with_mut_self");
-    let span4 = span::mock().named("sync_fun");
+    //let span = span::expect().named("call");
+    let span2 = span::expect().named("call_with_self");
+    let span3 = span::expect().named("call_with_mut_self");
+    let span4 = span::expect().named("sync_fun");
     let (subscriber, handle) = subscriber::mock()
         /*.new_span(span.clone()
             .with_field(
-                field::mock("Self").with_value(&"TestImpler")))
+                field::expect("Self").with_value(&"TestImpler")))
         .enter(span.clone())
         .exit(span.clone())
         .drop_span(span)*/
         .new_span(
             span2
                 .clone()
-                .with_field(field::mock("Self").with_value(&std::any::type_name::<TestImpl>())),
+                .with_field(field::expect("Self").with_value(&std::any::type_name::<TestImpl>())),
         )
         .enter(span2.clone())
         .new_span(
             span4
                 .clone()
-                .with_field(field::mock("Self").with_value(&std::any::type_name::<TestImpl>())),
+                .with_field(field::expect("Self").with_value(&std::any::type_name::<TestImpl>())),
         )
         .enter(span4.clone())
         .exit(span4.clone())
@@ -355,14 +355,14 @@ fn async_fn_with_async_trait_and_fields_expressions_with_generic_parameter() {
         .new_span(
             span3
                 .clone()
-                .with_field(field::mock("Self").with_value(&std::any::type_name::<TestImpl>())),
+                .with_field(field::expect("Self").with_value(&std::any::type_name::<TestImpl>())),
         )
         .enter(span3.clone())
         .exit(span3.clone())
         .enter(span3.clone())
         .exit(span3.clone())
         .drop_span(span3)
-        .done()
+        .only()
         .run_with_handle();
 
     with_default(subscriber, || {
@@ -397,15 +397,15 @@ fn out_of_scope_fields() {
         }
     }
 
-    let span = span::mock().named("call");
+    let span = span::expect().named("call");
     let (subscriber, handle) = subscriber::mock()
         .new_span(span.clone())
         .enter(span.clone())
         .exit(span.clone())
         .enter(span.clone())
         .exit(span.clone())
         .drop_span(span)
-        .done()
+        .only()
         .run_with_handle();
 
     with_default(subscriber, || {
@@ -430,8 +430,8 @@ fn manual_impl_future() {
         }
     }
 
-    let span = span::mock().named("manual_impl_future");
-    let poll_event = || event::mock().with_fields(field::mock("poll").with_value(&true));
+    let span = span::expect().named("manual_impl_future");
+    let poll_event = || event::expect().with_fields(field::expect("poll").with_value(&true));
 
     let (subscriber, handle) = subscriber::mock()
         // await manual_impl_future
@@ -442,7 +442,7 @@ fn manual_impl_future() {
         .enter(span.clone())
         .exit(span.clone())
         .drop_span(span)
-        .done()
+        .only()
         .run_with_handle();
 
     with_default(subscriber, || {
@@ -463,8 +463,8 @@ fn manual_box_pin() {
         })
     }
 
-    let span = span::mock().named("manual_box_pin");
-    let poll_event = || event::mock().with_fields(field::mock("poll").with_value(&true));
+    let span = span::expect().named("manual_box_pin");
+    let poll_event = || event::expect().with_fields(field::expect("poll").with_value(&true));
 
     let (subscriber, handle) = subscriber::mock()
         // await manual_box_pin
@@ -475,7 +475,7 @@ fn manual_box_pin() {
         .enter(span.clone())
         .exit(span.clone())
         .drop_span(span)
-        .done()
+        .only()
         .run_with_handle();
 
     with_default(subscriber, || {

tracing-attributes/tests/destructuring.rs

@@ -7,21 +7,21 @@ fn destructure_tuples() {
     #[instrument]
     fn my_fn((arg1, arg2): (usize, usize)) {}
 
-    let span = span::mock().named("my_fn");
+    let span = span::expect().named("my_fn");
 
     let (subscriber, handle) = subscriber::mock()
         .new_span(
             span.clone().with_field(
-                field::mock("arg1")
+                field::expect("arg1")
                     .with_value(&format_args!("1"))
-                    .and(field::mock("arg2").with_value(&format_args!("2")))
+                    .and(field::expect("arg2").with_value(&format_args!("2")))
                     .only(),
             ),
         )
         .enter(span.clone())
         .exit(span.clone())
         .drop_span(span)
-        .done()
+        .only()
         .run_with_handle();
 
     with_default(subscriber, || {
@@ -36,23 +36,23 @@ fn destructure_nested_tuples() {
     #[instrument]
     fn my_fn(((arg1, arg2), (arg3, arg4)): ((usize, usize), (usize, usize))) {}
 
-    let span = span::mock().named("my_fn");
+    let span = span::expect().named("my_fn");
 
     let (subscriber, handle) = subscriber::mock()
         .new_span(
             span.clone().with_field(
-                field::mock("arg1")
+                field::expect("arg1")
                     .with_value(&format_args!("1"))
-                    .and(field::mock("arg2").with_value(&format_args!("2")))
-                    .and(field::mock("arg3").with_value(&format_args!("3")))
-                    .and(field::mock("arg4").with_value(&format_args!("4")))
+                    .and(field::expect("arg2").with_value(&format_args!("2")))
+                    .and(field::expect("arg3").with_value(&format_args!("3")))
+                    .and(field::expect("arg4").with_value(&format_args!("4")))
                     .only(),
             ),
         )
         .enter(span.clone())
         .exit(span.clone())
         .drop_span(span)
-        .done()
+        .only()
         .run_with_handle();
 
     with_default(subscriber, || {
@@ -67,17 +67,17 @@ fn destructure_refs() {
     #[instrument]
     fn my_fn(&arg1: &usize) {}
 
-    let span = span::mock().named("my_fn");
+    let span = span::expect().named("my_fn");
 
     let (subscriber, handle) = subscriber::mock()
         .new_span(
             span.clone()
-                .with_field(field::mock("arg1").with_value(&1usize).only()),
+                .with_field(field::expect("arg1").with_value(&1usize).only()),
         )
         .enter(span.clone())
         .exit(span.clone())
         .drop_span(span)
-        .done()
+        .only()
         .run_with_handle();
 
     with_default(subscriber, || {
@@ -94,21 +94,21 @@ fn destructure_tuple_structs() {
     #[instrument]
     fn my_fn(Foo(arg1, arg2): Foo) {}
 
-    let span = span::mock().named("my_fn");
+    let span = span::expect().named("my_fn");
 
     let (subscriber, handle) = subscriber::mock()
         .new_span(
             span.clone().with_field(
-                field::mock("arg1")
+                field::expect("arg1")
                     .with_value(&format_args!("1"))
-                    .and(field::mock("arg2").with_value(&format_args!("2")))
+                    .and(field::expect("arg2").with_value(&format_args!("2")))
                     .only(),
             ),
         )
         .enter(span.clone())
         .exit(span.clone())
         .drop_span(span)
-        .done()
+        .only()
         .run_with_handle();
 
     with_default(subscriber, || {
@@ -135,21 +135,21 @@ fn destructure_structs() {
         let _ = (arg1, arg2);
     }
 
-    let span = span::mock().named("my_fn");
+    let span = span::expect().named("my_fn");
 
     let (subscriber, handle) = subscriber::mock()
         .new_span(
             span.clone().with_field(
-                field::mock("arg1")
+                field::expect("arg1")
                     .with_value(&format_args!("1"))
-                    .and(field::mock("arg2").with_value(&format_args!("2")))
+                    .and(field::expect("arg2").with_value(&format_args!("2")))
                     .only(),
             ),
         )
         .enter(span.clone())
         .exit(span.clone())
         .drop_span(span)
-        .done()
+        .only()
         .run_with_handle();
 
     with_default(subscriber, || {
@@ -180,23 +180,23 @@ fn destructure_everything() {
         let _ = (arg1, arg2, arg3, arg4);
     }
 
-    let span = span::mock().named("my_fn");
+    let span = span::expect().named("my_fn");
 
     let (subscriber, handle) = subscriber::mock()
         .new_span(
             span.clone().with_field(
-                field::mock("arg1")
+                field::expect("arg1")
                     .with_value(&format_args!("1"))
-                    .and(field::mock("arg2").with_value(&format_args!("2")))
-                    .and(field::mock("arg3").with_value(&format_args!("3")))
-                    .and(field::mock("arg4").with_value(&format_args!("4")))
+                    .and(field::expect("arg2").with_value(&format_args!("2")))
+                    .and(field::expect("arg3").with_value(&format_args!("3")))
+                    .and(field::expect("arg4").with_value(&format_args!("4")))
                     .only(),
             ),
         )
         .enter(span.clone())
         .exit(span.clone())
         .drop_span(span)
-        .done()
+        .only()
         .run_with_handle();
 
     with_default(subscriber, || {