From 67df9b9ac62ec1ec2e50289842a8842cf1a263f8 Mon Sep 17 00:00:00 2001 From: Steve Smith Date: Mon, 14 Nov 2016 13:52:43 +0000 Subject: [PATCH 1/3] Add sections about concurrency and stdout/err capture to the Testing chapter of the book. --- src/doc/book/testing.md | 43 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 43 insertions(+) diff --git a/src/doc/book/testing.md b/src/doc/book/testing.md index ed916fd798bb6..3b6d77032f132 100644 --- a/src/doc/book/testing.md +++ b/src/doc/book/testing.md @@ -586,3 +586,46 @@ you add more examples. We haven’t covered all of the details with writing documentation tests. For more, please see the [Documentation chapter](documentation.html). + +# Testing and concurrency + +One thing that is important to note when writing tests are run concurrently +using threads (by default the number of threads is equal to the number of CPUs +on the machine). For this reason you should take care that your tests are +written in such a way as to not depend on each-other, or on any shared +state. "Share state" can also include the environment, such as the current +working directory, or environment variables. + +If this is an issue it is possible to control this concurrency, either by +setting the environment variable `RUST_TEST_THREADS`, or by passing the argument +`--test-threads` to the tests: + +```bash +$ RUST_TEST_THREADS=1 cargo test # Run tests with no concurrency +... +$ cargo test -- --test-threads=1 # Same as above +... +``` + +# Test output + +By default Rust's test library captures and discards output to standard +out/error, e.g. output from `println!()`. This too can be controlled using the +environment or a switch: + + +```bash +$ RUST_TEST_NOCAPTURE=1 cargo test # Preserve stdout/stderr +... +$ cargo test -- --nocapture # Same as above +... +``` + +However a better method avoiding capture is to use logging rather than raw +output. Rust has a [standard logging API][log], which provides a frontend to +multiple loggin implementations. This can be used in conjunction with the +default [env_logger] to output any debugging information in a manner that can be +controlled at runtime. + +[log]: https://crates.io/crates/log +[env_logger]: https://crates.io/crates/env_logger From b9e17fa58ad9413355903d1a1a8cde5b11a9d436 Mon Sep 17 00:00:00 2001 From: Steve Smith Date: Mon, 14 Nov 2016 14:21:35 +0000 Subject: [PATCH 2/3] Typo in new section --- src/doc/book/testing.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/doc/book/testing.md b/src/doc/book/testing.md index 3b6d77032f132..8ec482fa58513 100644 --- a/src/doc/book/testing.md +++ b/src/doc/book/testing.md @@ -593,7 +593,7 @@ One thing that is important to note when writing tests are run concurrently using threads (by default the number of threads is equal to the number of CPUs on the machine). For this reason you should take care that your tests are written in such a way as to not depend on each-other, or on any shared -state. "Share state" can also include the environment, such as the current +state. "Shared state" can also include the environment, such as the current working directory, or environment variables. If this is an issue it is possible to control this concurrency, either by From 5a76fe4225f735a3a6e8574954b327157461423c Mon Sep 17 00:00:00 2001 From: Steve Smith Date: Mon, 14 Nov 2016 16:43:25 +0000 Subject: [PATCH 3/3] Remove thread-per-CPU bit as it may not be accurate. --- src/doc/book/testing.md | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/src/doc/book/testing.md b/src/doc/book/testing.md index 8ec482fa58513..3faa4b09c1fc8 100644 --- a/src/doc/book/testing.md +++ b/src/doc/book/testing.md @@ -590,11 +590,10 @@ please see the [Documentation chapter](documentation.html). # Testing and concurrency One thing that is important to note when writing tests are run concurrently -using threads (by default the number of threads is equal to the number of CPUs -on the machine). For this reason you should take care that your tests are -written in such a way as to not depend on each-other, or on any shared -state. "Shared state" can also include the environment, such as the current -working directory, or environment variables. +using threads. For this reason you should take care that your tests are written +in such a way as to not depend on each-other, or on any shared state. "Shared +state" can also include the environment, such as the current working directory, +or environment variables. If this is an issue it is possible to control this concurrency, either by setting the environment variable `RUST_TEST_THREADS`, or by passing the argument @@ -623,7 +622,7 @@ $ cargo test -- --nocapture # Same as above However a better method avoiding capture is to use logging rather than raw output. Rust has a [standard logging API][log], which provides a frontend to -multiple loggin implementations. This can be used in conjunction with the +multiple logging implementations. This can be used in conjunction with the default [env_logger] to output any debugging information in a manner that can be controlled at runtime.