From bfc43795f994c5f019e084ff88ab6d0960e2a171 Mon Sep 17 00:00:00 2001 From: Matilda Smeds Date: Sun, 12 Mar 2023 21:01:58 +0100 Subject: [PATCH] doc: explain testing in contributing guide (#5537) * Add links to fundamental testing concepts in Rust * Add information about conditional compilation attributes and how to use them to run tests with cargo --- CONTRIBUTING.md | 22 ++++++++++++++++++++-- 1 file changed, 20 insertions(+), 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 7681ef9da23..8e9716c11c1 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -197,8 +197,22 @@ If the change being proposed alters code (as opposed to only documentation for example), it is either adding new functionality to Tokio or it is fixing existing, broken functionality. In both of these cases, the pull request should include one or more tests to ensure that Tokio does not regress in the future. -There are two ways to write tests: integration tests and documentation tests -(Tokio avoids unit tests as much as possible). +There are two ways to write tests: [integration tests][integration-tests] +and [documentation tests][documentation-tests]. +(Tokio avoids [unit tests][unit-tests] as much as possible). + +Tokio uses [conditional compilation attributes][conditional-compilation] +throughout the codebase, to modify rustc's behavior. Code marked with such +attributes can be enabled using RUSTFLAGS and RUSTDOCFLAGS environment +variables. One of the most prevalent flags passed in these variables is +the `--cfg` option. To run tests in a particular file, check first what +options #![cfg] declaration defines for that file. + +For instance, to run a test marked with the 'tokio_unstable' cfg option, +you must pass this flag to the compiler when running the test. +``` +$ RUSTFLAGS="--cfg tokio_unstable" cargo test -p tokio --all-features --test rt_metrics +``` #### Integration tests @@ -658,3 +672,7 @@ When releasing a new version of a crate, follow these steps: entry for that release version into your editor and close the window. [keep-a-changelog]: https://github.com/olivierlacan/keep-a-changelog/blob/master/CHANGELOG.md +[unit-tests]: https://doc.rust-lang.org/rust-by-example/testing/unit_testing.html +[integration-tests]: https://doc.rust-lang.org/rust-by-example/testing/integration_testing.html +[documentation-tests]: https://doc.rust-lang.org/rust-by-example/testing/doc_testing.html +[conditional-compilation]: https://doc.rust-lang.org/reference/conditional-compilation.html \ No newline at end of file