Auto merge of #24783 - jooert:unittestguidelines, r=alexcrichton

Changes the style guidelines regarding unit tests to recommend using a sub-module named "tests" instead of "test" for unit tests as "test" might clash with imports of libtest (see #23870, #24030 and http://users.rust-lang.org/t/guidelines-naming-of-unit-test-module/1078 for previous discussions).

r? @alexcrichton

src/doc/style/testing/unit.md

@@ -1,10 +1,10 @@
 % Unit testing
 
-Unit tests should live in a `test` submodule at the bottom of the module they
-test. Mark the `test` submodule with `#[cfg(test)]` so it is only compiled when
+Unit tests should live in a `tests` submodule at the bottom of the module they
+test. Mark the `tests` submodule with `#[cfg(test)]` so it is only compiled when
 testing.
 
-The `test` module should contain:
+The `tests` module should contain:
 
 * Imports needed only for testing.
 * Functions marked with `#[test]` striving for full coverage of the parent module's
@@ -17,7 +17,7 @@ For example:
 // Excerpt from std::str
 
 #[cfg(test)]
-mod test {
+mod tests {
     #[test]
     fn test_eq() {
         assert!((eq(&"".to_owned(), &"".to_owned())));

src/doc/trpl/testing.md

@@ -219,10 +219,10 @@ fn it_works() {
 This is a very common use of `assert_eq!`: call some function with
 some known arguments and compare it to the expected output.
 
-# The `test` module
+# The `tests` module
 
 There is one way in which our existing example is not idiomatic: it's
-missing the test module. The idiomatic way of writing our example
+missing the `tests` module. The idiomatic way of writing our example
 looks like this:
 
 ```{rust,ignore}
@@ -231,7 +231,7 @@ pub fn add_two(a: i32) -> i32 {
 }
 
 #[cfg(test)]
-mod test {
+mod tests {
     use super::add_two;
 
     #[test]
@@ -241,7 +241,7 @@ mod test {
 }
 ```
 
-There's a few changes here. The first is the introduction of a `mod test` with
+There's a few changes here. The first is the introduction of a `mod tests` with
 a `cfg` attribute. The module allows us to group all of our tests together, and
 to also define helper functions if needed, that don't become a part of the rest
 of our crate. The `cfg` attribute only compiles our test code if we're
@@ -260,7 +260,7 @@ pub fn add_two(a: i32) -> i32 {
 }
 
 #[cfg(test)]
-mod test {
+mod tests {
     use super::*;
 
     #[test]
@@ -279,7 +279,7 @@ $ cargo test
      Running target/adder-91b3e234d4ed382a
 
 running 1 test
-test test::it_works ... ok
+test tests::it_works ... ok
 
 test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured
 
@@ -292,7 +292,7 @@ test result: ok. 0 passed; 0 failed; 0 ignored; 0 measured
 
 It works!
 
-The current convention is to use the `test` module to hold your "unit-style"
+The current convention is to use the `tests` module to hold your "unit-style"
 tests. Anything that just tests one small bit of functionality makes sense to
 go here. But what about "integration-style" tests instead? For that, we have
 the `tests` directory
@@ -325,7 +325,7 @@ $ cargo test
      Running target/adder-91b3e234d4ed382a
 
 running 1 test
-test test::it_works ... ok
+test tests::it_works ... ok
 
 test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured
 
@@ -346,7 +346,7 @@ 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.
 
-That's all there is to the `tests` directory. The `test` module isn't needed
+That's all there is to the `tests` directory. The `tests` module isn't needed
 here, since the whole thing is focused on tests.
 
 Let's finally check out that third section: documentation tests.
@@ -382,7 +382,7 @@ pub fn add_two(a: i32) -> i32 {
 }
 
 #[cfg(test)]
-mod test {
+mod tests {
     use super::*;
 
     #[test]
@@ -405,7 +405,7 @@ $ cargo test
      Running target/adder-91b3e234d4ed382a
 
 running 1 test
-test test::it_works ... ok
+test tests::it_works ... ok
 
 test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured
 

src/liballoc/heap.rs

@@ -384,7 +384,7 @@ mod imp {
 }
 
 #[cfg(test)]
-mod test {
+mod tests {
     extern crate test;
     use self::test::Bencher;
     use boxed::Box;

src/libcollections/linked_list.rs

@@ -933,7 +933,7 @@ impl<A: Hash> Hash for LinkedList<A> {
 }
 
 #[cfg(test)]
-mod test {
+mod tests {
     use std::clone::Clone;
     use std::iter::{Iterator, IntoIterator};
     use std::option::Option::{Some, None, self};

src/libcollections/vec_deque.rs

@@ -1772,7 +1772,7 @@ impl<T: fmt::Debug> fmt::Debug for VecDeque<T> {
 }
 
 #[cfg(test)]
-mod test {
+mod tests {
     use core::iter::{Iterator, self};
     use core::option::Option::Some;
 

src/libcoretest/num/mod.rs

@@ -45,7 +45,7 @@ pub fn test_num<T>(ten: T, two: T) where
 }
 
 #[cfg(test)]
-mod test {
+mod tests {
     use core::option::Option;
     use core::option::Option::{Some, None};
     use core::num::Float;

src/librand/chacha.rs

@@ -202,7 +202,7 @@ impl Rand for ChaChaRng {
 
 
 #[cfg(test)]
-mod test {
+mod tests {
     use std::prelude::v1::*;
 
     use core::iter::order;

src/librand/distributions/exponential.rs

@@ -82,7 +82,7 @@ impl IndependentSample<f64> for Exp {
 }
 
 #[cfg(test)]
-mod test {
+mod tests {
     use std::prelude::v1::*;
 
     use distributions::{Sample, IndependentSample};

src/librand/distributions/gamma.rs

@@ -276,7 +276,7 @@ impl IndependentSample<f64> for StudentT {
 }
 
 #[cfg(test)]
-mod test {
+mod tests {
     use std::prelude::v1::*;
 
     use distributions::{Sample, IndependentSample};

src/librand/isaac.rs

@@ -510,7 +510,7 @@ impl Rand for Isaac64Rng {
 
 
 #[cfg(test)]
-mod test {
+mod tests {
     use std::prelude::v1::*;
 
     use core::iter::order;

src/librand/reseeding.rs

@@ -120,7 +120,7 @@ impl Default for ReseedWithDefault {
 }
 
 #[cfg(test)]
-mod test {
+mod tests {
     use std::prelude::v1::*;
 
     use core::iter::{order, repeat};

src/librustc/session/config.rs

@@ -1111,7 +1111,7 @@ impl fmt::Display for CrateType {
 }
 
 #[cfg(test)]
-mod test {
+mod tests {
 
     use session::config::{build_configuration, optgroups, build_session_options};
     use session::build_session;

src/librustc_back/fs.rs

@@ -41,7 +41,7 @@ pub fn realpath(original: &Path) -> io::Result<PathBuf> {
 }
 
 #[cfg(all(not(windows), test))]
-mod test {
+mod tests {
     use tempdir::TempDir;
     use std::fs::{self, File};
     use super::realpath;

src/librustc_back/rpath.rs

@@ -171,7 +171,7 @@ fn minimize_rpaths(rpaths: &[String]) -> Vec<String> {
 }
 
 #[cfg(all(unix, test))]
-mod test {
+mod tests {
     use super::{RPathConfig};
     use super::{minimize_rpaths, rpaths_to_flags, get_rpath_relative_to_output};
     use std::path::{Path, PathBuf};

src/librustc_data_structures/graph/mod.rs

@@ -36,7 +36,7 @@ use std::usize;
 use snapshot_vec::{SnapshotVec, SnapshotVecDelegate};
 
 #[cfg(test)]
-mod test;
+mod tests;
 
 pub struct Graph<N,E> {
     nodes: SnapshotVec<Node<N>> ,

src/librustc_data_structures/unify/mod.rs

@@ -14,7 +14,7 @@ use std::marker::PhantomData;
 use snapshot_vec as sv;
 
 #[cfg(test)]
-mod test;
+mod tests;
 
 /// This trait is implemented by any type that can serve as a type
 /// variable. We call such variables *unification keys*. For example,

src/librustdoc/html/toc.rs

@@ -198,7 +198,7 @@ impl fmt::Display for Toc {
 }
 
 #[cfg(test)]
-mod test {
+mod tests {
     use super::{TocBuilder, Toc, TocEntry};
 
     #[test]

src/libstd/dynamic_lib.rs

@@ -117,7 +117,7 @@ impl DynamicLibrary {
 }
 
 #[cfg(all(test, not(target_os = "ios")))]
-mod test {
+mod tests {
     use super::*;
     use prelude::v1::*;
     use libc;

src/libstd/io/stdio.rs

@@ -418,7 +418,7 @@ pub fn _print(args: fmt::Arguments) {
 }
 
 #[cfg(test)]
-mod test {
+mod tests {
     use thread;
     use super::*;
 

src/libstd/io/util.rs

@@ -102,7 +102,7 @@ impl Write for Sink {
 }
 
 #[cfg(test)]
-mod test {
+mod tests {
     use prelude::v1::*;
 
     use io::prelude::*;

src/libstd/rand/os.rs

@@ -346,7 +346,7 @@ mod imp {
 }
 
 #[cfg(test)]
-mod test {
+mod tests {
     use prelude::v1::*;
 
     use sync::mpsc::channel;

src/libstd/rand/reader.rs

@@ -63,7 +63,7 @@ impl<R: Read> Rng for ReaderRng<R> {
 }
 
 #[cfg(test)]
-mod test {
+mod tests {
     use prelude::v1::*;
 
     use super::ReaderRng;

src/libstd/rt/backtrace.rs

@@ -38,7 +38,7 @@ pub fn log_enabled() -> bool {
 }
 
 #[cfg(test)]
-mod test {
+mod tests {
     use prelude::v1::*;
     use sys_common;
     macro_rules! t { ($a:expr, $b:expr) => ({

src/libstd/sync/future.rs

@@ -155,7 +155,7 @@ impl<A:Send+'static> Future<A> {
 }
 
 #[cfg(test)]
-mod test {
+mod tests {
     use prelude::v1::*;
     use sync::mpsc::channel;
     use sync::Future;

src/libstd/sync/mpsc/mod.rs

@@ -1065,7 +1065,7 @@ impl error::Error for TryRecvError {
 }
 
 #[cfg(test)]
-mod test {
+mod tests {
     use prelude::v1::*;
 
     use std::env;

src/libstd/sync/mpsc/select.rs

@@ -346,7 +346,7 @@ impl Iterator for Packets {
 
 #[cfg(test)]
 #[allow(unused_imports)]
-mod test {
+mod tests {
     use prelude::v1::*;
 
     use thread;

src/libstd/sync/mpsc/spsc_queue.rs

@@ -241,7 +241,7 @@ impl<T> Drop for Queue<T> {
 }
 
 #[cfg(test)]
-mod test {
+mod tests {
     use prelude::v1::*;
 
     use sync::Arc;

src/libstd/sync/mutex.rs

@@ -361,7 +361,7 @@ pub fn guard_poison<'a, T>(guard: &MutexGuard<'a, T>) -> &'a poison::Flag {
 }
 
 #[cfg(test)]
-mod test {
+mod tests {
     use prelude::v1::*;
 
     use sync::mpsc::channel;

src/libstd/sync/once.rs

@@ -121,7 +121,7 @@ impl Once {
 }
 
 #[cfg(test)]
-mod test {
+mod tests {
     use prelude::v1::*;
 
     use thread;

src/libstd/sys/common/remutex.rs

@@ -151,7 +151,7 @@ impl<'a, T> Drop for ReentrantMutexGuard<'a, T> {
 
 
 #[cfg(test)]
-mod test {
+mod tests {
     use prelude::v1::*;
     use sys_common::remutex::{ReentrantMutex, ReentrantMutexGuard};
     use cell::RefCell;

src/libstd/thread/mod.rs

@@ -722,7 +722,7 @@ fn _assert_sync_and_send() {
 ////////////////////////////////////////////////////////////////////////////////
 
 #[cfg(test)]
-mod test {
+mod tests {
     use prelude::v1::*;
 
     use any::Any;

src/libsyntax/ast.rs

@@ -1869,7 +1869,7 @@ pub struct MacroDef {
 }
 
 #[cfg(test)]
-mod test {
+mod tests {
     use serialize;
     use super::*;
 

src/libsyntax/ast_util.rs

@@ -632,7 +632,7 @@ pub fn lit_is_str(lit: &Lit) -> bool {
 }
 
 #[cfg(test)]
-mod test {
+mod tests {
     use ast::*;
     use super::*;
 

src/libsyntax/codemap.rs

@@ -949,7 +949,7 @@ pub struct MalformedCodemapPositions {
 //
 
 #[cfg(test)]
-mod test {
+mod tests {
     use super::*;
     use std::rc::Rc;
 

src/libsyntax/ext/expand.rs

@@ -1553,7 +1553,7 @@ impl<'a, 'v> Visitor<'v> for MacroExterminator<'a> {
 
 
 #[cfg(test)]
-mod test {
+mod tests {
     use super::{pattern_bindings, expand_crate};
     use super::{PatIdentFinder, IdentRenamer, PatIdentRenamer, ExpansionConfig};
     use ast;

src/libsyntax/fold.rs

@@ -1343,7 +1343,7 @@ pub fn noop_fold_stmt<T: Folder>(Spanned {node, span}: Stmt, folder: &mut T)
 }
 
 #[cfg(test)]
-mod test {
+mod tests {
     use std::io;
     use ast;
     use util::parser_testing::{string_to_crate, matches_codepattern};

src/libsyntax/parse/lexer/comments.rs

@@ -383,7 +383,7 @@ pub fn gather_comments_and_literals(span_diagnostic: &diagnostic::SpanHandler,
 }
 
 #[cfg(test)]
-mod test {
+mod tests {
     use super::*;
 
     #[test] fn test_block_doc_comment_1() {

src/libsyntax/parse/lexer/mod.rs

@@ -1501,7 +1501,7 @@ fn ident_continue(c: Option<char>) -> bool {
 }
 
 #[cfg(test)]
-mod test {
+mod tests {
     use super::*;
 
     use codemap::{BytePos, CodeMap, Span, NO_EXPANSION};

src/libsyntax/parse/mod.rs

@@ -761,7 +761,7 @@ pub fn integer_lit(s: &str, suffix: Option<&str>, sd: &SpanHandler, sp: Span) ->
 }
 
 #[cfg(test)]
-mod test {
+mod tests {
     use super::*;
     use std::rc::Rc;
     use codemap::{Span, BytePos, Pos, Spanned, NO_EXPANSION};

src/libsyntax/parse/token.rs

@@ -746,7 +746,7 @@ pub fn fresh_mark() -> ast::Mrk {
 }
 
 #[cfg(test)]
-mod test {
+mod tests {
     use super::*;
     use ast;
     use ext::mtwt;

src/libsyntax/print/pprust.rs

@@ -3008,7 +3008,7 @@ impl<'a> State<'a> {
 fn repeat(s: &str, n: usize) -> String { iter::repeat(s).take(n).collect() }
 
 #[cfg(test)]
-mod test {
+mod tests {
     use super::*;
 
     use ast;

src/libsyntax/util/parser_testing.rs

@@ -142,7 +142,7 @@ pub fn is_whitespace(c: char) -> bool {
 }
 
 #[cfg(test)]
-mod test {
+mod tests {
     use super::*;
 
     #[test] fn eqmodws() {

src/libsyntax/util/small_vector.rs

@@ -204,7 +204,7 @@ impl<T> MoveMap<T> for SmallVector<T> {
 }
 
 #[cfg(test)]
-mod test {
+mod tests {
     use super::*;
 
     #[test]

src/libterm/terminfo/parm.rs

@@ -573,7 +573,7 @@ fn format(val: Param, op: FormatOp, flags: Flags) -> Result<Vec<u8> ,String> {
 }
 
 #[cfg(test)]
-mod test {
+mod tests {
     use super::{expand,Param,Words,Variables,Number};
     use std::result::Result::Ok;
 

src/libterm/terminfo/parser/compiled.rs

@@ -345,7 +345,7 @@ pub fn msys_terminfo() -> Box<TermInfo> {
 }
 
 #[cfg(test)]
-mod test {
+mod tests {
 
     use super::{boolnames, boolfnames, numnames, numfnames, stringnames, stringfnames};
 

src/test/run-pass/issue-16597.rs

@@ -11,7 +11,7 @@
 // compile-flags:--test
 // ignore-pretty turns out the pretty-printer doesn't handle gensym'd things...
 
-mod test {
+mod tests {
     use super::*;
 
     #[test]