Rollup merge of #34060 - JDemler:master, r=steveklabnik

Improved documentation for tests/ directory

This ambigouity problem was already discussed in the [forums](https://users.rust-lang.org/t/problem-using-external-modules-inside-integration-test-submodule/5312/6).

1 files changed, 10 insertions, 4 deletions

diff --git a/src/doc/book/testing.md b/src/doc/book/testing.md
index d8afd7c4cf3..7954085472e 100644
--- a/src/doc/book/testing.md
+++ b/src/doc/book/testing.md
@@ -380,8 +380,9 @@ the `tests` directory.
 
 # The `tests` directory
 
-To write an integration test, let's make a `tests` directory, and
-put a `tests/lib.rs` file inside, with this as its contents:
+Each file in `tests/*.rs` directory is treated as individual crate.
+So, to write an integration test, let's make a `tests` directory, and
+put a `tests/integration_test.rs` file inside, with this as its contents:
 
 ```rust,ignore
 extern crate adder;
@@ -394,8 +395,8 @@ fn it_works() {
 ```
 
 This looks similar to our previous tests, but slightly different. We now have
-an `extern crate adder` at the top. This is because the tests in the `tests`
-directory are an entirely separate crate, and so we need to import our library.
+an `extern crate adder` at the top. This is because each test in the `tests`
+directory is an entirely separate crate, and so we need to import our library.
 This is also why `tests` is a suitable place to write integration-style tests:
 they use the library like any other consumer of it would.
 
@@ -428,6 +429,11 @@ test result: ok. 0 passed; 0 failed; 0 ignored; 0 measured
 Now we have three sections: our previous test is also run, as well as our new
 one.
 
+Cargo will ignore files in subdirectories of the `tests/` directory.
+Therefore shared modules in integrations tests are possible.
+For example `tests/common/mod.rs` is not seperatly compiled by cargo but can 
+be imported in every test with `mod common;`
+
 That's all there is to the `tests` directory. The `tests` module isn't needed
 here, since the whole thing is focused on tests.