publish tracing tests framework on crates.io #539

yaahc · 2020-01-14T18:39:48Z

Feature Request

Motivation

I'm writing a 3rd party library for instrumenting programs with tracing spans https://github.com/yaahc/spandoc that I would like to be able to test using the tracing test framework without having to vendor the test framework or write my own test subscriber.

Proposal

Publish the contents of tracing/tracing/tests/support and any other necessary machinery so that they can be added as a dev dependency to spandoc and tests can be created that verify span entry and exit ordering.

It is not necessary for the tracing crates themselves to depend on the published version via crates.io. Eliza has some worries about introducing a need to maintain API stability into the test framework, not depending on the published version should make this a less important concern, its okay if the published version drifts from the actively used version by the main tracing crates so long as the core functionality that is published to crates.io still works.

Alternatives

Alternatively I can just vendor support files into my crate and depend on them in the same way that tracing crates do.

The text was updated successfully, but these errors were encountered:

hawkw · 2020-01-14T22:51:53Z

Hmm, if we're going to do this, I think the test framework needs a lot of cleanup. At the very least, we should:

ensure that the panic output is readable and is actually formatted nicely
ensure there are no double panics/panics in drop
try to make the test dsl less verbose (e.g. turn span::mock().named("foo") into just span("foo") or something
make the naming make more sense
add API docs

hawkw · 2020-01-15T22:50:48Z

i notice that the actix-tracing integration crate that was recently published has basically reproduced its own version of the test support code as well: https://github.com/actix/actix-net/blob/aed5fecc8a0b994cc871483bcf15b3c5fbb350df/actix-tracing/src/lib.rs#L139-L225

so, perhaps that's more evidence in support of making it publicly available...

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

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

The `tracing-mock` crate provides a mock collector (and a subscriber for use by the tests in the `tracing-subscriber` crate) which is able to make assertions about what diagnostics are emitted. These assertions are defined by structs that match on events, span, and their fields and metadata. The structs that matched these objects have been called, up until now, mocks, however this terminology may be misleading, as the created objects don't mock anything. To reduce confusion, these structs have been split into two categories: mocks and expectations. The mocks replace some component in the tracing ecosystem when a library is under test. The expectations define the assertions we wish to make about traces received by the mocks. Mocks (per module): * collector - `MockCollector`, no change * subscriber - `MockSubscriber`, renamed from `ExpectSubscriber` Expectations (per module): * event - `ExpectedEvent`, renamed from `MockEvent` * span - `ExpectedSpan`, renamed from `MockSpan` * field - `ExpectedField` and `ExpectedFields`, renamed from `MockField` and `Expected`. Also `ExpectedValue` renamed from `MockValue`. * metadata - `ExpectedMetadata`, renamed from `Expected` Refs: #539

The `tracing-mock` crate provides a mock collector (and a subscriber for use by the tests in the `tracing-subscriber` crate) which is able to make assertions about what diagnostics are emitted. These assertions are defined by structs that match on events, span, and their fields and metadata. The structs that matched these objects have been called, up until now, mocks, however this terminology may be misleading, as the created objects don't mock anything. To reduce confusion, these structs have been split into two categories: mocks and expectations. Additionally, the `done()` function on the `Collector` and `Subscriber` mocks has been replaced with `only()`. This matches the similar function for `ExpectedField`, and may be more intuitive. The mocks replace some component in the tracing ecosystem when a library is under test. The expectations define the assertions we wish to make about traces received by the mocks. Mocks (per module): * collector - `MockCollector`, no change * subscriber - `MockSubscriber`, renamed from `ExpectSubscriber` Expectations (per module): * event - `ExpectedEvent`, renamed from `MockEvent` * span - `ExpectedSpan`, renamed from `MockSpan` * field - `ExpectedField` and `ExpectedFields`, renamed from `MockField` and `Expected`. Also `ExpectedValue` renamed from `MockValue`. * metadata - `ExpectedMetadata`, renamed from `Expected` Refs: #539

The `tracing-mock` crate provides a mock collector (and a subscriber for use by the tests in the `tracing-subscriber` crate) which is able to make assertions about what diagnostics are emitted. These assertions are defined by structs that match on events, span, and their fields and metadata. The structs that matched these objects have been called, up until now, mocks, however this terminology may be misleading, as the created objects don't mock anything. There were two different names for similar functionality with `only()` and `done()` on fields and collectors/subscribers respectively. Using a single name for these may make it easier to onboard onto `tracing-mock`. To reduce confusion, these structs have been split into two categories: mocks and expectations. Additionally, the `done()` function on the `Collector` and `Subscriber` mocks has been replaced with `only()`. This matches the similar function for `ExpectedField`, and may be more intuitive. The mocks replace some component in the tracing ecosystem when a library is under test. The expectations define the assertions we wish to make about traces received by the mocks. Mocks (per module): * collector - `MockCollector`, no change * subscriber - `MockSubscriber`, renamed from `ExpectSubscriber` Expectations (per module): * event - `ExpectedEvent`, renamed from `MockEvent` * span - `ExpectedSpan`, renamed from `MockSpan` * field - `ExpectedField` and `ExpectedFields`, renamed from `MockField` and `Expected`. Also `ExpectedValue` renamed from `MockValue`. * metadata - `ExpectedMetadata`, renamed from `Expected` Refs: #539

The current format of test expectations in `tracing-mock` isn't ideal. The format `span::expect` requires importing `tracing_mock::<thing>` which may conflict with imports from other tracing crates, especially `tracing-core`. So we change the order and move the functions into a module called `expect` so that: * `event::expect` becomes `expect::event` * `span::expect` becomes `expect::span` * `field::expect` becomes `expect::field` This format has two advantages. 1. It reads as natural English, e.g "expect span" 2. It is no longer common to import the modules directly. Regarding point (2), the following format was previously common: ```rust use tracing_mock::field; field::expect(); ``` This import of the `field` module may then conflict with importing the same from `tracing_core`, making it necessary to rename one of the imports. The same code would now be written: ```rust use tracing_mock::expect; expect::field(); ``` Which is less likely to conflict. This change also fixes an unused warning on `MockHandle::new` when the `tracing-subscriber` feature is not enabled. Refs: #539

* mock: change helper functions to `expect::<thing>` The current format of test expectations in `tracing-mock` isn't ideal. The format `span::expect` requires importing `tracing_mock::<thing>` which may conflict with imports from other tracing crates, especially `tracing-core`. So we change the order and move the functions into a module called `expect` so that: * `event::expect` becomes `expect::event` * `span::expect` becomes `expect::span` * `field::expect` becomes `expect::field` This format has two advantages. 1. It reads as natural English, e.g "expect span" 2. It is no longer common to import the modules directly. Regarding point (2), the following format was previously common: ```rust use tracing_mock::field; field::expect(); ``` This import of the `field` module may then conflict with importing the same from `tracing_core`, making it necessary to rename one of the imports. The same code would now be written: ```rust use tracing_mock::expect; expect::field(); ``` Which is less likely to conflict. This change also fixes an unused warning on `MockHandle::new` when the `tracing-subscriber` feature is not enabled. Refs: #539

hds · 2022-11-14T22:03:03Z

Hayden's list of things to do before publishing:

Add README - should be tested
Add documentation to all public APIs, including examples / doctests to most of them
Add #[must_use] to the public API where necessary
Add expectation for Collector::try_drop to MockCollector
Add negative tests for all assertions (as in, we should test that tracing-mock will correctly fail a test if the code under test is wrong) - this should also test that there are no double panics
Improve the logging output of the tests - it can be very verbose
Improve the panic output so that it's readable and nicely formatted

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 adds documentation to the collector module itself and to all the public APIs in the module. This includes doctests on all the methods that serve as examples. Additionally the implementation for the `Expect` struct has been moved into the module with the definition, this was missed in #2369. Refs: #539

This change adds documentation to the event module and all the public APIs within it. This includes doctests on all the methods which serve as examples. Some small API changes are also included The methods `with_explicit_parent` and `with_contextual_parent` have had the negative case moved into separate methods `without_explicit_parent` and `without_contextual_parent` respectively. This removes the need for an `Option` around the parameter in the original methods - which are likely to be the most used case (the 'without' case where `None` would have been passed before is not used anywhere in this workspace). The method `in_scope` has been placed behind the `tracing-subscriber` feature flag as it currently only works with the `MockSubscriber`, not with the `MockCollector`. If the feature flag is active and it is used to set a non-empty scope, the `MockCollector` will panic with `unimplemented` during validation. Refs: #539

## Motivation 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. The `event` module needs documentation and examples. ## Solution This change adds documentation to the event module and all the public APIs within it. This includes doctests on all the methods which serve as examples. The following pattern was applied to the description of most methods: - Short description of expectation - Additional clarification (where needed) - Description of cases that cause the expectation to fail - Examples - Successful validation - Unsuccesful validation Two changes were also made in the text provided to the user when an assertion fails for `with_explicit_parent` or `with_contextual_parent`. One small API changes is also included: The method `in_scope` has been placed behind the `tracing-subscriber` feature flag as it currently only works with the `MockSubscriber`, not with the `MockCollector`. If the feature flag is active and it is used to set a non-empty scope, the `MockCollector` will panic with `unimplemented` during validation. Refs: #539

This change adds documentation to the span module and all the public APIs within it. This includes doctests on all the methods which serve as examples. Additionally, the validation on `ExpectedSpan` was improved so that it validates the level and target during `enter` and `exit` as well as on `new_span`. The method `ExpectedSpan::with_field` was renamed to `with_fields` (plural) to match the same method on `ExpectedEvent` (and because multiple fields can be passed to it). A copy-paste typo was also fixed in the documentation for `ExpectedEvent::with_contextual_parent`. Refs: #539

Tokio is instrumented with traces which can be used to analyze the behavior of the runtime during execution or post-mortem. The instrumentation is optional. This is where tokio-console collections information. There are currently no tests for the instrumentation. In order to provide more stability to the instrumentation and prepare for future changes, tests are added to verify the current behavior. The tests are written using the `tracing-mock` crate. As this crate is still unreleased, a separate test create has been added under `tokio/tests` which is outside the workspace. This allows us to pull in both `tracing` and `tracing-mock` from the tracing repository on GitHub without affecting the rest of the tokio repository. This change adds initial tests for the task instrumentation. Further tests will be added in subsequent commits. Once `tracing-mock` is published on crates.io (tokio-rs/tracing#539), these tests can be moved in with the "normal" tokio integration tests. The decision to add these tests now is due to the release of `tracing-mock` taking a while, so it would be better to have tests while we wait.

## 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 <me@davidbarsky.com>

This change adds documentation to the tracing-mock span module and all the public APIs within it. This includes doctests on all the methods which serve as examples. Additionally, the validation on `ExpectedSpan` was improved so that it validates the level and target during `enter` and `exit` as well as on `new_span`. The method `ExpectedSpan::with_field` was renamed to `with_fields` (plural) to match the same method on `ExpectedEvent` (and because multiple fields can be passed to it). A copy-paste typo was also fixed in the documentation for `ExpectedEvent::with_contextual_parent`. Refs: #539 Co-authored-by: David Barsky <me@davidbarsky.com>

This change adds documentation to the tracing-mock `field` module and all the public APIs within it. This includes doctests on all the methods which serve as examples. Additionally, the `field::msg` function (which constructs a field with name "message" and the provided value) was moved to `expect::message`. This is part of a unification of all expectation constructors inside the `expect` module. Refs: #539 Co-authored-by: David Barsky <me@davidbarsky.com>

mladedav · 2024-04-20T19:29:55Z

Hi, @hds, I can see you're made quite a progress on this, is there anything to help out with regarding this?

I've tried using this recently (through git dependency) and from the lists I've seen here, the double panics happened to me a few times and the output might be improved but other than that, do you think there is more work to be done?

hds · 2024-04-20T21:37:47Z

@mladedav I've got a couple of necessary refactorings pending and then one or two more PRs to complete the documentation. Some of the changes that have made it into master also need to be backported I think (although I'm not 100% sure of the state of that).

I must admit, that I haven't looked into the double panics yet, so if you have specific reproductions then that would be really useful. If you could open an Issue with the repo and let me know, I can have a look.

The `tracing-mock` crate provides a mock collector (and a subscriber for use by the tests in the `tracing-subscriber` crate) which is able to make assertions about what diagnostics are emitted. These assertions are defined by structs that match on events, span, and their fields and metadata. The structs that matched these objects have been called, up until now, mocks, however this terminology may be misleading, as the created objects don't mock anything. There were two different names for similar functionality with `only()` and `done()` on fields and collectors/subscribers respectively. Using a single name for these may make it easier to onboard onto `tracing-mock`. To reduce confusion, these structs have been split into two categories: mocks and expectations. Additionally, the `done()` function on the `Collector` and `Subscriber` mocks has been replaced with `only()`. This matches the similar function for `ExpectedField`, and may be more intuitive. The mocks replace some component in the tracing ecosystem when a library is under test. The expectations define the assertions we wish to make about traces received by the mocks. Mocks (per module): * collector - `MockCollector`, no change * subscriber - `MockSubscriber`, renamed from `ExpectSubscriber` Expectations (per module): * event - `ExpectedEvent`, renamed from `MockEvent` * span - `ExpectedSpan`, renamed from `MockSpan` * field - `ExpectedField` and `ExpectedFields`, renamed from `MockField` and `Expected`. Also `ExpectedValue` renamed from `MockValue`. * metadata - `ExpectedMetadata`, renamed from `Expected` Refs: tokio-rs#539

* mock: change helper functions to `expect::<thing>` The current format of test expectations in `tracing-mock` isn't ideal. The format `span::expect` requires importing `tracing_mock::<thing>` which may conflict with imports from other tracing crates, especially `tracing-core`. So we change the order and move the functions into a module called `expect` so that: * `event::expect` becomes `expect::event` * `span::expect` becomes `expect::span` * `field::expect` becomes `expect::field` This format has two advantages. 1. It reads as natural English, e.g "expect span" 2. It is no longer common to import the modules directly. Regarding point (2), the following format was previously common: ```rust use tracing_mock::field; field::expect(); ``` This import of the `field` module may then conflict with importing the same from `tracing_core`, making it necessary to rename one of the imports. The same code would now be written: ```rust use tracing_mock::expect; expect::field(); ``` Which is less likely to conflict. This change also fixes an unused warning on `MockHandle::new` when the `tracing-subscriber` feature is not enabled. Refs: tokio-rs#539

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. The `event` module needs documentation and examples. This change adds documentation to the event module and all the public APIs within it. This includes doctests on all the methods which serve as examples. The following pattern was applied to the description of most methods: - Short description of expectation - Additional clarification (where needed) - Description of cases that cause the expectation to fail - Examples - Successful validation - Unsuccesful validation Two changes were also made in the text provided to the user when an assertion fails for `with_explicit_parent` or `with_contextual_parent`. One small API changes is also included: The method `in_scope` has been placed behind the `tracing-subscriber` feature flag as it currently only works with the `MockSubscriber`, not with the `MockCollector`. If the feature flag is active and it is used to set a non-empty scope, the `MockCollector` will panic with `unimplemented` during validation. Refs: tokio-rs#539

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. The `subscriber` module needs documentation and examples. This change adds documentation to the `subscriber` module and all the public APIs within it. This includes doctests on all the methods which serve as examples. The `MockSubscriberBuilder::record` method was removed as its functionality is not implemented. Previously, the `MockSubscriber` would verify the scope of an `ExpectedEvent`, even if `in_scope` hadn't been called. In this case, that would check that an event was not in a span if `in_scope` had not been called. `tracing-subscriber` all adhere to this pattern. However it is different to the behavior of all other expectation methods, where an explicit call is needed to expect something, otherwise nothing is checked. As such, the behavior has been modified to align with the rest of the crate. The previous behavior can be achieved by calling `in_scope(None)` to verify that an event has no scope. The documentation for `in_scope` has been updated with an example for this case. The tests in `tracing-subscriber` which previously verified *implicitly* that an event had no scope (by not calling `in_scope` at all) have *not* been modified. It is my opinion that this implicit behavior was never required. Refs: tokio-rs#539

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 adds documentation to the collector module itself and to all the public APIs in the module. This includes doctests on all the methods that serve as examples. Additionally the implementation for the `Expect` struct has been moved into the module with the definition, this was missed in tokio-rs#2369. Refs: tokio-rs#539

## Motivation 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. The `expect` module, which contains constructor functions for many of the other `tracing-mock` modules needs documentation and examples. This change adds documentation to the `expect` module and all the public APIs within it. This includes doctests on all the methods which serve as examples. ## Solution The lint for `missing_docs` has been enabled for the entire `tracing-mock` crate! This has been done together with all the other lints that are enabled on the other crates in this project. The `event::msg("message")` constructor was removed, in favor of requiring an explicit construction via `expect::event().with_fields(expect::msg("message"))`. This is appropriate to reduce the API surface that would need to be supported in the future and also because the `event::msg` constructor could be overridden by a subsequent usage of `with_fields`. The shorthand `expect::message()` was renamed to `expect::msg` to make this change less burdensome. The `span::named("name")` constructor was removed, in favor of requiring an explicit construction via `expect::span.with_name("name")`. The latter isn't much longer and since #3097, a string with the name can be passed directly everywhere that an `ExpectedSpan` is required. This change also sets the `missing_docs` lint to warn for the entire `tracing-mock` crate, making it ready to publish (once backported). Refs: #539

This change adds documentation to the tracing-mock span module and all the public APIs within it. This includes doctests on all the methods which serve as examples. Additionally, the validation on `ExpectedSpan` was improved so that it validates the level and target during `enter` and `exit` as well as on `new_span`. The method `ExpectedSpan::with_field` was renamed to `with_fields` (plural) to match the same method on `ExpectedEvent` (and because multiple fields can be passed to it). A copy-paste typo was also fixed in the documentation for `ExpectedEvent::with_contextual_parent`. Refs: #539 Co-authored-by: David Barsky <me@davidbarsky.com>

This change adds documentation to the tracing-mock `field` module and all the public APIs within it. This includes doctests on all the methods which serve as examples. Additionally, the `field::msg` function (which constructs a field with name "message" and the provided value) was moved to `expect::message`. This is part of a unification of all expectation constructors inside the `expect` module. Refs: #539 Co-authored-by: David Barsky <me@davidbarsky.com>

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. 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 <me@davidbarsky.com>

This change adds documentation to the tracing-mock span module and all the public APIs within it. This includes doctests on all the methods which serve as examples. Additionally, the validation on `ExpectedSpan` was improved so that it validates the level and target during `enter` and `exit` as well as on `new_span`. The method `ExpectedSpan::with_field` was renamed to `with_fields` (plural) to match the same method on `ExpectedEvent` (and because multiple fields can be passed to it). A copy-paste typo was also fixed in the documentation for `ExpectedEvent::with_contextual_parent`. Refs: #539 Co-authored-by: David Barsky <me@davidbarsky.com>

This change adds documentation to the tracing-mock `field` module and all the public APIs within it. This includes doctests on all the methods which serve as examples. Additionally, the `field::msg` function (which constructs a field with name "message" and the provided value) was moved to `expect::message`. This is part of a unification of all expectation constructors inside the `expect` module. Refs: #539 Co-authored-by: David Barsky <me@davidbarsky.com>

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. 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 <me@davidbarsky.com>

This change adds documentation to the tracing-mock span module and all the public APIs within it. This includes doctests on all the methods which serve as examples. Additionally, the validation on `ExpectedSpan` was improved so that it validates the level and target during `enter` and `exit` as well as on `new_span`. The method `ExpectedSpan::with_field` was renamed to `with_fields` (plural) to match the same method on `ExpectedEvent` (and because multiple fields can be passed to it). A copy-paste typo was also fixed in the documentation for `ExpectedEvent::with_contextual_parent`. Refs: #539 Co-authored-by: David Barsky <me@davidbarsky.com>

This change adds documentation to the tracing-mock `field` module and all the public APIs within it. This includes doctests on all the methods which serve as examples. Additionally, the `field::msg` function (which constructs a field with name "message" and the provided value) was moved to `expect::message`. This is part of a unification of all expectation constructors inside the `expect` module. Refs: #539 Co-authored-by: David Barsky <me@davidbarsky.com>

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. The `expect` module, which contains constructor functions for many of the other `tracing-mock` modules needs documentation and examples. This change adds documentation to the `expect` module and all the public APIs within it. This includes doctests on all the methods which serve as examples. The lint for `missing_docs` has been enabled for the entire `tracing-mock` crate! This has been done together with all the other lints that are enabled on the other crates in this project. The `event::msg("message")` constructor was removed, in favor of requiring an explicit construction via `expect::event().with_fields(expect::msg("message"))`. This is appropriate to reduce the API surface that would need to be supported in the future and also because the `event::msg` constructor could be overridden by a subsequent usage of `with_fields`. The shorthand `expect::message()` was renamed to `expect::msg` to make this change less burdensome. The `span::named("name")` constructor was removed, in favor of requiring an explicit construction via `expect::span.with_name("name")`. The latter isn't much longer and since #3097, a string with the name can be passed directly everywhere that an `ExpectedSpan` is required. This change also sets the `missing_docs` lint to warn for the entire `tracing-mock` crate, making it ready to publish (once backported). Refs: #539

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. 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 <me@davidbarsky.com>

This change adds documentation to the tracing-mock span module and all the public APIs within it. This includes doctests on all the methods which serve as examples. Additionally, the validation on `ExpectedSpan` was improved so that it validates the level and target during `enter` and `exit` as well as on `new_span`. The method `ExpectedSpan::with_field` was renamed to `with_fields` (plural) to match the same method on `ExpectedEvent` (and because multiple fields can be passed to it). A copy-paste typo was also fixed in the documentation for `ExpectedEvent::with_contextual_parent`. Refs: #539 Co-authored-by: David Barsky <me@davidbarsky.com>

This change adds documentation to the tracing-mock `field` module and all the public APIs within it. This includes doctests on all the methods which serve as examples. Additionally, the `field::msg` function (which constructs a field with name "message" and the provided value) was moved to `expect::message`. This is part of a unification of all expectation constructors inside the `expect` module. Refs: #539 Co-authored-by: David Barsky <me@davidbarsky.com>

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. The `expect` module, which contains constructor functions for many of the other `tracing-mock` modules needs documentation and examples. This change adds documentation to the `expect` module and all the public APIs within it. This includes doctests on all the methods which serve as examples. The lint for `missing_docs` has been enabled for the entire `tracing-mock` crate! This has been done together with all the other lints that are enabled on the other crates in this project. The `event::msg("message")` constructor was removed, in favor of requiring an explicit construction via `expect::event().with_fields(expect::msg("message"))`. This is appropriate to reduce the API surface that would need to be supported in the future and also because the `event::msg` constructor could be overridden by a subsequent usage of `with_fields`. The shorthand `expect::message()` was renamed to `expect::msg` to make this change less burdensome. The `span::named("name")` constructor was removed, in favor of requiring an explicit construction via `expect::span.with_name("name")`. The latter isn't much longer and since #3097, a string with the name can be passed directly everywhere that an `ExpectedSpan` is required. This change also sets the `missing_docs` lint to warn for the entire `tracing-mock` crate, making it ready to publish (once backported). Refs: #539

hawkw mentioned this issue Mar 12, 2020

Multiple test failures in tracing-futures 0.2.3 #632

Open

hawkw mentioned this issue May 14, 2020

cross-project bug: async_trait and tracing::instrument are incompatible dtolnay/async-trait#45

Closed

GeorgeHahn mentioned this issue Jul 10, 2020

Extract test framework #793

Closed

This was referenced Oct 25, 2022

mock: add README to tracing-mock #2357

Closed

Move tracing-subscriber test/support module into tracing-mock #2359

Closed

hds mentioned this issue Nov 9, 2022

mock: differentiate between mocks and expectations #2373

Merged

hds mentioned this issue Nov 11, 2022

mock: change helper functions to expect::<thing> #2377

Merged

hds mentioned this issue Nov 15, 2022

mock: add README to tracing-mock #2362

Merged

hds mentioned this issue Nov 16, 2022

mock: document public API in collector module #2389

Merged

hds mentioned this issue Dec 27, 2022

mock: document public APIs in event module #2426

Merged

hds mentioned this issue Jan 12, 2023

mock: document public APIs in span module #2442

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

publish tracing tests framework on crates.io #539

publish tracing tests framework on crates.io #539

yaahc commented Jan 14, 2020

hawkw commented Jan 14, 2020

hawkw commented Jan 15, 2020

hds commented Nov 14, 2022 •

edited

Loading

mladedav commented Apr 20, 2024

hds commented Apr 20, 2024

publish tracing tests framework on crates.io #539

publish tracing tests framework on crates.io #539

Comments

yaahc commented Jan 14, 2020

Feature Request

Motivation

Proposal

Alternatives

hawkw commented Jan 14, 2020

hawkw commented Jan 15, 2020

hds commented Nov 14, 2022 • edited Loading

mladedav commented Apr 20, 2024

hds commented Apr 20, 2024

hds commented Nov 14, 2022 •

edited

Loading