From 94e764f1f82e554bb7eb563c84841340e8c442f2 Mon Sep 17 00:00:00 2001 From: Hayden Stainsby Date: Tue, 15 Nov 2022 23:18:13 +0100 Subject: [PATCH] mock: add README to tracing-mock (#2362) 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. Specifically **I** want to have access to `tracing-mock` within parts of `tokio` to write tests that ensure that the correct calling location is picked up for all `spawn*` functions when the `tracing` feature is enabled. 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. The README is included in the `lib.rs` docs using `#[doc = include_str!(...)]`, so that the same documentation is included in the crate, and the examples are tested when running doctests. 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. Co-authored-by: David Barsky Co-authored-by: Eliza Weisman --- tracing-mock/README.md | 176 ++++++++++++++++++++++++++++++++++++++++ tracing-mock/src/lib.rs | 1 + 2 files changed, 177 insertions(+) create mode 100644 tracing-mock/README.md diff --git a/tracing-mock/README.md b/tracing-mock/README.md new file mode 100644 index 0000000000..b508db00cb --- /dev/null +++ b/tracing-mock/README.md @@ -0,0 +1,176 @@ +![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]: https://github.com/tokio-rs/tracing/blob/master/tracing-mock/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-mock` provides +tools for making assertions about what `tracing` diagnostics are emitted +by code under test. + +*Compiler support: [requires `rustc` 1.49+][msrv]* + +[msrv]: #supported-rust-versions + +## Usage + +`tracing-mock` crate provides a mock +[`Collector`](https://tracing-rs.netlify.app/tracing/#collectors) +that allows asserting on the order and contents of +[spans](https://tracing-rs.netlify.app/tracing/#spans) and +[events](https://tracing-rs.netlify.app/tracing/#events). + +As `tracing-mock` isn't available on [crates.io](https://crates.io/) +yet, you must import it via git. When using `tracing-mock` with the +`tracing` `0.1` ecosystem, 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" } +tracing-core = { git = "https://github.com/tokio-rs/tracing", branch = "v0.1.x" } +``` + +## Examples + +The following examples are for the `master` branch. For examples that +will work with `tracing` from [crates.io], please check the +[v0.1.x](https://github.com/tokio-rs/tracing/tree/v0.1.x/tracing-mock) +branch. + +Below is an example that checks that an event contains a message: + +```rust +use tracing::collect::with_default; +use tracing_mock::{collector, expect, field}; + +fn yak_shaving() { + tracing::info!("preparing to shave yaks"); +} + +let (collector, handle) = collector::mock() + .event(expect::event().with_fields(field::msg("preparing to shave yaks"))) + .only() + .run_with_handle(); + +with_default(collector, || { + yak_shaving(); +}); + +handle.assert_finished(); + +``` + +Below is a slightly more complex example. `tracing-mock` asserts that, in order: +- a span is created with a single field/value pair +- the span is entered +- an event is created with the field `number_of_yaks`, a corresponding + value of 3, and the message "preparing to shave yaks", and nothing else +- an event is created with the field `all_yaks_shaved`, a corresponding value + of `true`, and the message "yak shaving completed" +- the span is exited +- no further traces are received + +```rust +use tracing::collect::with_default; +use tracing_mock::{collector, expect, field}; + +#[tracing::instrument] +fn yak_shaving(number_of_yaks: u32) { + tracing::info!(number_of_yaks, "preparing to shave yaks"); + + let number_shaved = number_of_yaks; // shave_all + tracing::info!( + all_yaks_shaved = number_shaved == number_of_yaks, + "yak shaving completed." + ); +} + +let yak_count: u32 = 3; +let span = expect::span().named("yak_shaving"); + +let (collector, handle) = collector::mock() + .new_span( + span.clone() + .with_field(expect::field("number_of_yaks").with_value(&yak_count).only()), + ) + .enter(span.clone()) + .event( + expect::event().with_fields( + expect::field("number_of_yaks") + .with_value(&yak_count) + .and(field::msg("preparing to shave yaks")) + .only(), + ), + ) + .event( + expect::event().with_fields( + expect::field("all_yaks_shaved") + .with_value(&true) + .and(field::msg("yak shaving completed.")) + .only(), + ), + ) + .exit(span.clone()) + .only() + .run_with_handle(); + +with_default(collector, || { + yak_shaving(yak_count); +}); + +handle.assert_finished(); +``` + +## 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][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. \ No newline at end of file diff --git a/tracing-mock/src/lib.rs b/tracing-mock/src/lib.rs index e7a6e8b0e2..90cd371e35 100644 --- a/tracing-mock/src/lib.rs +++ b/tracing-mock/src/lib.rs @@ -1,3 +1,4 @@ +#![doc = include_str!("../README.md")] use std::{ pin::Pin, task::{Context, Poll},