test: add tracing-test crate for non-publishable test utils (#2466)

## Motivation

There has been interest around publishing tracing-mock to crates.io
for some time. In order to make this possible, it needs to be cleaned up.

## Solution

There are some test utils in the `tracing-mock` crate which wouldn't
make sense to publish. They provide test futures that are needed in
multiple `tracing-*` crates, but would likely not be needed outside that
context.

This change moves that functionality into a separate `tracing-test`
crate, which should never be published to crates.io.

Refs: #539

Co-authored-by: David Barsky <[email protected]>

Author: hds

Cargo.toml

@@ -13,6 +13,7 @@ members = [
     "tracing-mock",
     "tracing-subscriber",
     "tracing-serde",
+    "tracing-test",
     "tracing-appender",
     "tracing-journald",
     "examples"

tracing-attributes/Cargo.toml

@@ -35,14 +35,25 @@ proc-macro = true
 
 [dependencies]
 proc-macro2 = "1.0.60"
-syn = { version = "2.0", default-features = false, features = ["full", "parsing", "printing", "visit-mut", "clone-impls", "extra-traits", "proc-macro"] }
+syn = { version = "2.0", default-features = false, features = [
+    "full",
+    "parsing",
+    "printing",
+    "visit-mut",
+    "clone-impls",
+    "extra-traits",
+    "proc-macro",
+] }
 quote = "1.0.20"
 
 [dev-dependencies]
 tracing = { path = "../tracing", version = "0.2" }
-tracing-mock = { path = "../tracing-mock", features = ["tokio-test"] }
+tracing-mock = { path = "../tracing-mock" }
 tokio-test = "0.4.2"
-tracing-subscriber = { path = "../tracing-subscriber", version = "0.3", features = ["env-filter"] }
+tracing-subscriber = { path = "../tracing-subscriber", version = "0.3", features = [
+    "env-filter",
+] }
+tracing-test = { path = "../tracing-test" }
 async-trait = "0.1.67"
 trybuild = "1.0.64"
 rustversion = "1.0.9"

tracing-attributes/tests/async_fn.rs

@@ -1,9 +1,10 @@
-use tracing_mock::*;
-
 use std::convert::Infallible;
 use std::{future::Future, pin::Pin, sync::Arc};
+
 use tracing::collect::with_default;
 use tracing_attributes::instrument;
+use tracing_mock::{collector, expect};
+use tracing_test::{block_on_future, PollN};
 
 #[instrument]
 async fn test_async_fn(polls: usize) -> Result<(), ()> {

tracing-attributes/tests/err.rs

@@ -4,6 +4,7 @@ use tracing_attributes::instrument;
 use tracing_mock::*;
 use tracing_subscriber::filter::EnvFilter;
 use tracing_subscriber::subscribe::CollectExt;
+use tracing_test::{block_on_future, PollN};
 
 use std::convert::TryFrom;
 use std::num::TryFromIntError;

tracing-attributes/tests/follows_from.rs

@@ -1,6 +1,7 @@
 use tracing::{collect::with_default, Id, Level, Span};
 use tracing_attributes::instrument;
-use tracing_mock::*;
+use tracing_mock::{collector, expect};
+use tracing_test::block_on_future;
 
 #[instrument(follows_from = causes, skip(causes))]
 fn with_follows_from_sync(causes: impl IntoIterator<Item = impl Into<Option<Id>>>) {}

tracing-attributes/tests/ret.rs

@@ -1,11 +1,12 @@
 use std::convert::TryFrom;
 use std::num::TryFromIntError;
-use tracing_mock::*;
 
 use tracing::{collect::with_default, Level};
 use tracing_attributes::instrument;
+use tracing_mock::{collector, expect};
 use tracing_subscriber::subscribe::CollectExt;
 use tracing_subscriber::EnvFilter;
+use tracing_test::block_on_future;
 
 #[instrument(ret)]
 fn ret() -> i32 {

tracing-futures/Cargo.toml

@@ -43,7 +43,8 @@ mio = "0.6.23"
 futures = "0.3.21"
 tokio-test = "0.4.2"
 tracing-core = { path = "../tracing-core", version = "0.2" }
-tracing-mock = { path = "../tracing-mock", features = ["tokio-test"] }
+tracing-mock = { path = "../tracing-mock" }
+tracing-test = { path = "../tracing-test" }
 
 [badges]
 maintenance = { status = "actively-developed" }

tracing-futures/tests/std_future.rs

@@ -3,7 +3,8 @@ use std::{future::Future, pin::Pin, task};
 use futures::FutureExt as _;
 use tracing::Instrument;
 use tracing::{collect::with_default, Level};
-use tracing_mock::*;
+use tracing_mock::{collector, expect};
+use tracing_test::{block_on_future, PollN};
 
 #[test]
 fn enter_exit_is_reasonable() {

tracing-mock/Cargo.toml

@@ -21,7 +21,6 @@ publish = false
 tracing = { path = "../tracing", version = "0.2" }
 tracing-core = { path = "../tracing-core", version = "0.2", default-features = false }
 tracing-subscriber = { path = "../tracing-subscriber", version = "0.3", default-features = false, features = ["registry"], optional = true }
-tokio-test = { version = "0.4.2", optional = true }
 
 # Fix minimal-versions; tokio-test fails with otherwise acceptable 0.1.0
 tokio-stream = "0.1.9"

tracing-mock/src/lib.rs

@@ -1,9 +1,4 @@
 #![doc = include_str!("../README.md")]
-use std::{
-    pin::Pin,
-    task::{Context, Poll},
-};
-
 pub mod collector;
 pub mod event;
 pub mod expect;
@@ -22,12 +17,6 @@ pub enum Parent {
     Explicit(String),
 }
 
-pub struct PollN<T, E> {
-    and_return: Option<Result<T, E>>,
-    finish_at: usize,
-    polls: usize,
-}
-
 impl Parent {
     pub fn check_parent_name(
         &self,
@@ -104,57 +93,3 @@ impl Parent {
         }
     }
 }
-
-impl<T, E> std::future::Future for PollN<T, E>
-where
-    T: Unpin,
-    E: Unpin,
-{
-    type Output = Result<T, E>;
-    fn poll(self: Pin<&mut Self>, cx: &mut Context) -> Poll<Self::Output> {
-        let this = self.get_mut();
-
-        this.polls += 1;
-        if this.polls == this.finish_at {
-            let value = this.and_return.take().expect("polled after ready");
-
-            Poll::Ready(value)
-        } else {
-            cx.waker().wake_by_ref();
-            Poll::Pending
-        }
-    }
-}
-
-impl PollN<(), ()> {
-    pub fn new_ok(finish_at: usize) -> Self {
-        Self {
-            and_return: Some(Ok(())),
-            finish_at,
-            polls: 0,
-        }
-    }
-
-    pub fn new_err(finish_at: usize) -> Self {
-        Self {
-            and_return: Some(Err(())),
-            finish_at,
-            polls: 0,
-        }
-    }
-}
-
-#[cfg(feature = "tokio-test")]
-pub fn block_on_future<F>(future: F) -> F::Output
-where
-    F: std::future::Future,
-{
-    use tokio_test::task;
-
-    let mut task = task::spawn(future);
-    loop {
-        if let Poll::Ready(v) = task.poll() {
-            break v;
-        }
-    }
-}

tracing-test/Cargo.toml

@@ -0,0 +1,26 @@
+## BIG SCARY NOTE
+# This crate is internal and to be used for testing only. It should not
+# be published to crates.io ever. If the functionality is needed outside
+# the tracing project, it should be moved back to tracing-mock.
+
+[package]
+name = "tracing-test"
+version = "0.1.0"
+authors = [
+    "Eliza Weisman <[email protected]>",
+    "Tokio Contributors <[email protected]>",
+]
+license = "MIT"
+readme = "README.md"
+repository = "https://github.com/tokio-rs/tracing"
+homepage = "https://tokio.rs"
+edition = "2018"
+rust-version = "1.49.0"
+publish = false
+
+[dependencies]
+tokio-test = "0.4.2"
+
+[package.metadata.docs.rs]
+all-features = true
+rustdoc-args = ["--cfg", "docsrs"]

tracing-test/LICENSE

@@ -0,0 +1,25 @@
+Copyright (c) 2019 Tokio Contributors
+
+Permission is hereby granted, free of charge, to any
+person obtaining a copy of this software and associated
+documentation files (the "Software"), to deal in the
+Software without restriction, including without
+limitation the rights to use, copy, modify, merge,
+publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software
+is furnished to do so, subject to the following
+conditions:
+
+The above copyright notice and this permission notice
+shall be included in all copies or substantial portions
+of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF
+ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED
+TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
+PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT
+SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR
+IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+DEALINGS IN THE SOFTWARE.

tracing-test/README.md

@@ -0,0 +1,58 @@
+![Tracing — Structured, application-level diagnostics][splash]
+
+[splash]: https://raw.githubusercontent.com/tokio-rs/tracing/master/assets/splash.svg
+
+# tracing-test
+
+Utilities for testing [`tracing`][tracing] and crates that uses it.
+
+[![Documentation (master)][docs-master-badge]][docs-master-url]
+[![MIT licensed][mit-badge]][mit-url]
+[![Build Status][actions-badge]][actions-url]
+[![Discord chat][discord-badge]][discord-url]
+
+[Documentation][docs-master-url] | [Chat][discord-url]
+
+[docs-master-badge]: https://img.shields.io/badge/docs-master-blue
+[docs-master-url]: https://tracing-rs.netlify.com/tracing_mock
+[mit-badge]: https://img.shields.io/badge/license-MIT-blue.svg
+[mit-url]: https://github.com/tokio-rs/tracing/blob/master/tracing-test/LICENSE
+[actions-badge]: https://github.com/tokio-rs/tracing/workflows/CI/badge.svg
+[actions-url]:https://github.com/tokio-rs/tracing/actions?query=workflow%3ACI
+[discord-badge]: https://img.shields.io/discord/500028886025895936?logo=discord&label=discord&logoColor=white
+[discord-url]: https://discord.gg/EeF3cQw
+
+## Overview
+
+[`tracing`] is a framework for instrumenting Rust programs to collect
+structured, event-based diagnostic information. `tracing-test` provides
+some reusable tools to aid in testing, but that are only intended for
+internal use. For mocks and expectations, see [`tracing-mock`].
+
+*Compiler support: [requires `rustc` 1.56+][msrv]*
+
+[msrv]: #supported-rust-versions
+
+## Supported Rust Versions
+
+Tracing is built against the latest stable release. The minimum supported
+version is 1.56. The current Tracing version is not guaranteed to build on Rust
+versions earlier than the minimum supported version.
+
+Tracing follows the same compiler support policies as the rest of the Tokio
+project. The current stable Rust compiler and the three most recent minor
+versions before it will always be supported. For example, if the current stable
+compiler version is 1.45, the minimum supported version will not be increased
+past 1.42, three minor versions prior. Increasing the minimum supported compiler
+version is not considered a semver breaking change as long as doing so complies
+with this policy.
+
+## License
+
+This project is licensed under the [MIT license][mit-url].
+
+### Contribution
+
+Unless you explicitly state otherwise, any contribution intentionally submitted
+for inclusion in Tracing by you, shall be licensed as MIT, without any additional
+terms or conditions.

tracing-test/src/lib.rs

@@ -0,0 +1,65 @@
+use std::{
+    pin::Pin,
+    task::{Context, Poll},
+};
+
+#[allow(missing_docs)]
+
+pub struct PollN<T, E> {
+    and_return: Option<Result<T, E>>,
+    finish_at: usize,
+    polls: usize,
+}
+
+impl<T, E> std::future::Future for PollN<T, E>
+where
+    T: Unpin,
+    E: Unpin,
+{
+    type Output = Result<T, E>;
+    fn poll(self: Pin<&mut Self>, cx: &mut Context) -> Poll<Self::Output> {
+        let this = self.get_mut();
+
+        this.polls += 1;
+        if this.polls == this.finish_at {
+            let value = this.and_return.take().expect("polled after ready");
+
+            Poll::Ready(value)
+        } else {
+            cx.waker().wake_by_ref();
+            Poll::Pending
+        }
+    }
+}
+
+impl PollN<(), ()> {
+    pub fn new_ok(finish_at: usize) -> Self {
+        Self {
+            and_return: Some(Ok(())),
+            finish_at,
+            polls: 0,
+        }
+    }
+
+    pub fn new_err(finish_at: usize) -> Self {
+        Self {
+            and_return: Some(Err(())),
+            finish_at,
+            polls: 0,
+        }
+    }
+}
+
+pub fn block_on_future<F>(future: F) -> F::Output
+where
+    F: std::future::Future,
+{
+    use tokio_test::task;
+
+    let mut task = task::spawn(future);
+    loop {
+        if let Poll::Ready(v) = task.poll() {
+            break v;
+        }
+    }
+}

tracing/test_static_max_level_features/Cargo.toml

@@ -19,4 +19,4 @@ features = ["max_level_debug", "release_max_level_info"]
 
 [dev-dependencies]
 tokio-test = "0.2.0"
-tracing-mock = { path = "../../tracing-mock", features = ["tokio-test"] }
+tracing-test = { path = "../../tracing-test" }

tracing/test_static_max_level_features/tests/test.rs

@@ -6,7 +6,7 @@ use tracing::{
     debug, error, info, instrument, span, trace, warn, Collect, Event, Id, Level, Metadata,
 };
 use tracing_core::span::Current;
-use tracing_mock::*;
+use tracing_test::block_on_future;
 
 struct State {
     last_level: Mutex<Option<Level>>,