mock: add README to tracing-mock

There has been interest around publishing `tracing-mock` to crates.io
for some time. In order to make this possible, documentation and some
code clean up is needed.

This change starts that process by adding a README for `tracing-mock`.
The README follows the standard format for all `tracing` crates and
includes 2 examples. Additionally an integration test has been added for
each example.

The README describes steps when using the `tracing` 1.0 from crates.io
and `tracing-mock` from the `v0.1.x` branch. The tests target the
current branch.

Refs: #539

tracing-mock/Cargo.toml

@@ -18,7 +18,7 @@ rust-version = "1.49.0"
 publish = false
 
 [dependencies]
-tracing = { path = "../tracing", version = "0.2", default-features = false }
+tracing = { path = "../tracing", version = "0.2" }
 tracing-core = { path = "../tracing-core", version = "0.2", default-features = false }
 tokio-test = { version = "0.4.2", optional = true }
 

tracing-mock/README.md

@@ -0,0 +1,170 @@
+![Tracing — Structured, application-level diagnostics][splash]
+
+[splash]: https://raw.githubusercontent.com/tokio-rs/tracing/master/assets/splash.svg
+
+# tracing-mock
+
+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]: 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. This crate provides
+constructors for mock `tracing` objects to allow testing of `tracing`
+itself as well as crates that use it.
+
+*Compiler support: [requires `rustc` 1.49+][msrv]*
+
+[msrv]: #supported-rust-versions
+
+## Usage
+
+The `tracing-mock` crate provides a mock `subscriber` which can
+verify the spans and events sent. It is inteded for use in tests
+to ensure that your crate is tracing at the corrrect time with the
+correct data.
+
+As `tracing-mock` isn't available on [crates.io](https://crates.io/)
+yet, you must import it via git. It is important that you also override
+the source of any `tracing` crates that are transient dependencies. For
+example, the `Cargo.toml` for your test crate could contain:
+
+```toml
+[dependencies]
+lib-under-test = 1.0 # depends on `tracing`
+
+[dev-dependencies]
+tracing-mock = { git = "https://github.com/tokio-rs/tracing", branch = "v0.1.x", version = "0.1" }
+tracing = { git = "https://github.com/tokio-rs/tracing", branch = "v0.1.x", version = "0.1" }
+
+[patch.crates-io]
+tracing = { git = "https://github.com/tokio-rs/tracing", branch = "v0.1.x" }
+```
+
+Below is a simple example of checking for an event with only a
+message.
+
+```rust
+use tracing::subscriber::with_default;
+use tracing_mock::{event, field, subscriber};
+
+fn yak_shaving() {
+    tracing::info!("preparing to shave yaks");
+}
+
+#[test]
+fn traced_event() {
+    let (subscriber, handle) = subscriber::mock()
+        .event(event::mock().with_fields(field::msg("preparing to shave yaks")))
+        .done()
+        .run_with_handle();
+
+    with_default(subscriber, || {
+        yak_shaving();
+    });
+
+    handle.assert_finished();
+}
+```
+
+The following is a more complex example taking the full yak shaving example
+from the `tracing` README and additionally instrumenting the called function
+with a span.
+
+```rust
+use tracing::subscriber::with_default;
+use tracing_mock::{event, field, span, subscriber};
+
+#[tracing::instrument]
+fn yak_shaving(number_of_yaks: u32) {
+    tracing::info!(number_of_yaks, "preparing to shave yaks");
+
+    let number_shaved = yak_shave::shave_all(number_of_yaks);
+    tracing::info!(
+        all_yaks_shaved = number_shaved == number_of_yaks,
+        "yak shaving completed."
+    );
+}
+
+// If this test gets updated, the `tracing-mock` README.md must be updated too.
+#[test]
+fn yak_shaving_traced() {
+    let yak_count: u32 = 3;
+    let span = span::mock().named("yak_shaving");
+
+    let (subscriber, handle) = subscriber::mock()
+        .new_span(
+            span.clone()
+                .with_field(field::mock("number_of_yaks").with_value(&yak_count).only()),
+        )
+        .enter(span.clone())
+        .event(
+            event::mock().with_fields(
+                field::mock("number_of_yaks")
+                    .with_value(&yak_count)
+                    .and(field::msg("preparing to shave yaks"))
+                    .only(),
+            ),
+        )
+        .event(
+            event::mock().with_fields(
+                field::mock("all_yaks_shaved")
+                    .with_value(&true)
+                    .and(field::msg("yak shaving completed."))
+                    .only(),
+            ),
+        )
+        .exit(span.clone())
+        .done()
+        .run_with_handle();
+
+    with_default(subscriber, || {
+        yak_shaving(yak_count);
+    });
+
+    handle.assert_finished();
+}
+```
+
+The full code for both examples can be found in the [readme.rs](tests/readme.rs)
+tests.
+
+## Supported Rust Versions
+
+Tracing is built against the latest stable release. The minimum supported
+version is 1.49. 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](LICENSE).
+
+### 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-mock/tests/readme.rs

@@ -0,0 +1,77 @@
+use tracing::collect::with_default;
+use tracing_mock::{event, field, span, collector};
+
+fn prepare_yak_shaving() {
+    tracing::info!("preparing to shave yaks");
+}
+
+// If this test gets updated, the `tracing-mock` README.md must be updated too.
+#[test]
+fn prepare_yak_shaving_traced() {
+    let (subscriber, handle) = collector::mock()
+        .event(event::mock().with_fields(field::msg("preparing to shave yaks")))
+        .done()
+        .run_with_handle();
+
+    with_default(subscriber, || {
+        prepare_yak_shaving();
+    });
+
+    handle.assert_finished();
+}
+
+mod yak_shave {
+    pub fn shave_all(number_of_yaks: u32) -> u32 {
+        number_of_yaks
+    }
+}
+
+#[tracing::instrument]
+fn yak_shaving(number_of_yaks: u32) {
+    tracing::info!(number_of_yaks, "preparing to shave yaks");
+
+    let number_shaved = yak_shave::shave_all(number_of_yaks);
+    tracing::info!(
+        all_yaks_shaved = number_shaved == number_of_yaks,
+        "yak shaving completed."
+    );
+}
+
+// If this test gets updated, the `tracing-mock` README.md must be updated too.
+#[test]
+fn yak_shaving_traced() {
+    let yak_count: u32 = 3;
+    let span = span::mock().named("yak_shaving");
+
+    let (subscriber, handle) = collector::mock()
+        .new_span(
+            span.clone()
+                .with_field(field::mock("number_of_yaks").with_value(&yak_count).only()),
+        )
+        .enter(span.clone())
+        .event(
+            event::mock().with_fields(
+                field::mock("number_of_yaks")
+                    .with_value(&yak_count)
+                    .and(field::msg("preparing to shave yaks"))
+                    .only(),
+            ),
+        )
+        .event(
+            event::mock().with_fields(
+                field::mock("all_yaks_shaved")
+                    .with_value(&true)
+                    .and(field::msg("yak shaving completed."))
+                    .only(),
+            ),
+        )
+        .exit(span)
+        .done()
+        .run_with_handle();
+
+    with_default(subscriber, || {
+        yak_shaving(yak_count);
+    });
+
+    handle.assert_finished();
+}