mock: improve ergonomics when an ExpectedSpan is needed (#3097)

Many of the methods on `MockCollector` take an `ExpectedSpan`. This
often requires significant boilerplate. For example, to expect that a
span with a specific name enters and then exits, the following code is
needed:

```rust
let span = expect::span().named("span name");

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

In order to make using `tracing-mock` more ergonomic and also more
compact, the `MockCollector` and `MockSubscriber` methods that previous
took an `ExpectedSpan`, are now generic over `Into<ExpectedSpan>`.

There are currently 3 implementations of `From` for `ExpectedSpan` which
allow the following shorthand uses:

`T: Into<String>` - an `ExpectedSpan` will be created that expects to
have a name specified by `T`.

```rust
let (collector, handle) = collector::mock()
    .enter("span name")
    .exit("span name")
    .run_with_handle();
```

`&ExpectedId` - an `ExpectedSpan` will be created that expects to have
the expected Id. A reference is taken and cloned internally because the
caller always needs to use an `ExpectedId` in at least 2 calls to the
mock collector/subscriber.

```rust
let id = expect::id();

let (collector, handle) = collector::mock()
    .new_span(&id)
    .enter(&id)
    .run_with_handle();
```

`&ExpectedSpan` - The expected span is taken by reference and cloned.

```rust
let span = expect::span().named("span name");

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

In Rust, taking a reference to an object and immediately cloning it is
an anti-pattern. It is considered better to force the user to clone
outside the API to make the cloning explict.

However, in the case of a testing framework, it seems reasonable to
prefer a more concise API, rather than having it more explicit.

To reduce the size of this PR and to avoid unnecessary churn in other
crates, the tests within the tracing repo which use `tracing-mock` will
not be updated to use the new `Into<ExpectedSpan>` capabilities. The new
API is backwards compatible and those tests can remain as they are.

Author: hds

tracing-mock/src/layer.rs

@@ -1,13 +1,13 @@
 //! An implementation of the [`Layer`] trait which validates that
-//! the `tracing` data it recieves matches the expected output for a test.
+//! the `tracing` data it receives matches the expected output for a test.
 //!
 //!
 //! The [`MockLayer`] is the central component in these tools. The
 //! `MockLayer` has expectations set on it which are later
 //! validated as the code under test is run.
 //!
 //! ```
-//! use tracing_mock::{expect, field, layer};
+//! use tracing_mock::{expect, layer};
 //! use tracing_subscriber::{layer::SubscriberExt, util::SubscriberInitExt, Layer};
 //!
 //! let (layer, handle) = layer::mock()
@@ -40,11 +40,11 @@
 //!     .named("my_span");
 //! let (layer, handle) = layer::mock()
 //!     // Enter a matching span
-//!     .enter(span.clone())
+//!     .enter(&span)
 //!     // Record an event with message "collect parting message"
 //!     .event(expect::event().with_fields(expect::message("say hello")))
 //!     // Exit a matching span
-//!     .exit(span)
+//!     .exit(&span)
 //!     // Expect no further messages to be recorded
 //!     .only()
 //!     // Return the layer and handle
@@ -75,18 +75,18 @@
 //! span before recording an event, the test will fail:
 //!
 //! ```should_panic
-//! use tracing_mock::{expect, field, layer};
+//! use tracing_mock::{expect, layer};
 //! use tracing_subscriber::{layer::SubscriberExt, util::SubscriberInitExt, Layer};  
 //!
 //! let span = expect::span()
 //!     .named("my_span");
 //! let (layer, handle) = layer::mock()
 //!     // Enter a matching span
-//!     .enter(span.clone())
+//!     .enter(&span)
 //!     // Record an event with message "collect parting message"
 //!     .event(expect::event().with_fields(expect::message("say hello")))
 //!     // Exit a matching span
-//!     .exit(span)
+//!     .exit(&span)
 //!     // Expect no further messages to be recorded
 //!     .only()
 //!     // Return the subscriber and handle
@@ -146,18 +146,18 @@ use std::{
 /// # Examples
 ///
 /// ```
-/// use tracing_mock::{expect, field, layer};
+/// use tracing_mock::{expect, layer};
 /// use tracing_subscriber::{layer::SubscriberExt, util::SubscriberInitExt, Layer};
 ///
 /// let span = expect::span()
 ///     .named("my_span");
 /// let (layer, handle) = layer::mock()
 ///     // Enter a matching span
-///     .enter(span.clone())
+///     .enter(&span)
 ///     // Record an event with message "collect parting message"
 ///     .event(expect::event().with_fields(expect::message("say hello")))
 ///     // Exit a matching span
-///     .exit(span)
+///     .exit(&span)
 ///     // Expect no further messages to be recorded
 ///     .only()
 ///     // Return the subscriber and handle
@@ -414,7 +414,7 @@ impl MockLayerBuilder {
     ///
     /// This function accepts `Into<NewSpan>` instead of
     /// [`ExpectedSpan`] directly. [`NewSpan`] can be used to test
-    /// span fields and the span parent.
+    /// span fields and the span ancestry.
     ///
     /// The new span doesn't need to be entered for this expectation
     /// to succeed.
@@ -504,8 +504,8 @@ impl MockLayerBuilder {
     ///     .at_level(tracing::Level::INFO)
     ///     .named("the span we're testing");
     /// let (layer, handle) = layer::mock()
-    ///     .enter(span.clone())
-    ///     .exit(span)
+    ///     .enter(&span)
+    ///     .exit(&span)
     ///     .only()
     ///     .run_with_handle();
     ///
@@ -532,8 +532,8 @@ impl MockLayerBuilder {
     ///     .at_level(tracing::Level::INFO)
     ///     .named("the span we're testing");
     /// let (layer, handle) = layer::mock()
-    ///     .enter(span.clone())
-    ///     .exit(span)
+    ///     .enter(&span)
+    ///     .exit(&span)
     ///     .only()
     ///     .run_with_handle();
     ///
@@ -552,8 +552,11 @@ impl MockLayerBuilder {
     ///
     /// [`exit`]: fn@Self::exit
     /// [`only`]: fn@Self::only
-    pub fn enter(mut self, span: ExpectedSpan) -> Self {
-        self.expected.push_back(Expect::Enter(span));
+    pub fn enter<S>(mut self, span: S) -> Self
+    where
+        S: Into<ExpectedSpan>,
+    {
+        self.expected.push_back(Expect::Enter(span.into()));
         self
     }
 
@@ -581,8 +584,8 @@ impl MockLayerBuilder {
     ///     .at_level(tracing::Level::INFO)
     ///     .named("the span we're testing");
     /// let (layer, handle) = layer::mock()
-    ///     .enter(span.clone())
-    ///     .exit(span)
+    ///     .enter(&span)
+    ///     .exit(&span)
     ///     .only()
     ///     .run_with_handle();
     ///
@@ -608,8 +611,8 @@ impl MockLayerBuilder {
     ///     .at_level(tracing::Level::INFO)
     ///     .named("the span we're testing");
     /// let (layer, handle) = layer::mock()
-    ///     .enter(span.clone())
-    ///     .exit(span)
+    ///     .enter(&span)
+    ///     .exit(&span)
     ///     .only()
     ///     .run_with_handle();
     ///
@@ -629,8 +632,11 @@ impl MockLayerBuilder {
     /// [`enter`]: fn@Self::enter
     /// [`MockHandle::assert_finished`]: fn@crate::subscriber::MockHandle::assert_finished
     /// [`Span::enter`]: fn@tracing::Span::enter
-    pub fn exit(mut self, span: ExpectedSpan) -> Self {
-        self.expected.push_back(Expect::Exit(span));
+    pub fn exit<S>(mut self, span: S) -> Self
+    where
+        S: Into<ExpectedSpan>,
+    {
+        self.expected.push_back(Expect::Exit(span.into()));
         self
     }