From 09d6462d6fac29731bf92c24489ad8f9d784ab5e Mon Sep 17 00:00:00 2001 From: Hayden Stainsby Date: Tue, 25 Oct 2022 13:15:12 +0200 Subject: [PATCH 1/2] 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. Refs: #539 --- tracing-mock/Cargo.toml | 2 +- tracing-mock/README.md | 154 +++++++++++++++++++++++++++++++++++ tracing-mock/tests/readme.rs | 77 ++++++++++++++++++ 3 files changed, 232 insertions(+), 1 deletion(-) create mode 100644 tracing-mock/README.md create mode 100644 tracing-mock/tests/readme.rs diff --git a/tracing-mock/Cargo.toml b/tracing-mock/Cargo.toml index 02aabbfeaa..217705936f 100644 --- a/tracing-mock/Cargo.toml +++ b/tracing-mock/Cargo.toml @@ -18,7 +18,7 @@ rust-version = "1.49.0" publish = false [dependencies] -tracing = { path = "../tracing", version = "0.1.35", default-features = false } +tracing = { path = "../tracing", version = "0.1.35" } tracing-core = { path = "../tracing-core", version = "0.1.28", default-features = false } tokio-test = { version = "0.4.2", optional = true } diff --git a/tracing-mock/README.md b/tracing-mock/README.md new file mode 100644 index 0000000000..86c39e1f6c --- /dev/null +++ b/tracing-mock/README.md @@ -0,0 +1,154 @@ +![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. + +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. \ No newline at end of file diff --git a/tracing-mock/tests/readme.rs b/tracing-mock/tests/readme.rs new file mode 100644 index 0000000000..43da26b5d5 --- /dev/null +++ b/tracing-mock/tests/readme.rs @@ -0,0 +1,77 @@ +use tracing::subscriber::with_default; +use tracing_mock::{event, field, span, subscriber}; + +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) = subscriber::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) = 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(); +} From 2bd85a80a96173052448b1603e40d435e4ad52e9 Mon Sep 17 00:00:00 2001 From: Hayden Stainsby Date: Tue, 25 Oct 2022 17:54:32 +0200 Subject: [PATCH 2/2] fix clippy warning --- tracing-mock/tests/readme.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tracing-mock/tests/readme.rs b/tracing-mock/tests/readme.rs index 43da26b5d5..bdef69525a 100644 --- a/tracing-mock/tests/readme.rs +++ b/tracing-mock/tests/readme.rs @@ -65,7 +65,7 @@ fn yak_shaving_traced() { .only(), ), ) - .exit(span.clone()) + .exit(span) .done() .run_with_handle();