diff --git a/crates/cargo-test-support/src/cross_compile.rs b/crates/cargo-test-support/src/cross_compile.rs
index ce3d0444251..67281926e43 100644
--- a/crates/cargo-test-support/src/cross_compile.rs
+++ b/crates/cargo-test-support/src/cross_compile.rs
@@ -1,3 +1,14 @@
+//! Support for cross-compile tests with the `--target` flag.
+//!
+//! Note that cross-testing is very limited. You need to install the
+//! "alternate" target to the host (32-bit for 64-bit hosts or vice-versa).
+//!
+//! Set CFG_DISABLE_CROSS_TESTS=1 environment variable to disable these tests
+//! if you are unable to use the alternate target. Unfortunately 32-bit
+//! support on macOS is going away, so macOS users are out of luck.
+//!
+//! These tests are all disabled on rust-lang/rust's CI, but run in Cargo's CI.
+
 use crate::{basic_bin_manifest, main_file, project};
 use std::env;
 use std::process::Command;
diff --git a/tests/testsuite/alt_registry.rs b/tests/testsuite/alt_registry.rs
index 6441ab0a8c4..8343bd471fc 100644
--- a/tests/testsuite/alt_registry.rs
+++ b/tests/testsuite/alt_registry.rs
@@ -1,3 +1,5 @@
+//! Tests for alternative registries.
+
 use cargo::util::IntoUrl;
 use cargo_test_support::publish::validate_alt_upload;
 use cargo_test_support::registry::{self, Package};
diff --git a/tests/testsuite/bad_config.rs b/tests/testsuite/bad_config.rs
index af448e70b16..14e626e5e68 100644
--- a/tests/testsuite/bad_config.rs
+++ b/tests/testsuite/bad_config.rs
@@ -1,3 +1,5 @@
+//! Tests for some invalid .cargo/config files.
+
 use cargo_test_support::registry::Package;
 use cargo_test_support::{basic_manifest, project};
 
diff --git a/tests/testsuite/bad_manifest_path.rs b/tests/testsuite/bad_manifest_path.rs
index 8e54f5f641b..9ee84ed0f0b 100644
--- a/tests/testsuite/bad_manifest_path.rs
+++ b/tests/testsuite/bad_manifest_path.rs
@@ -1,3 +1,5 @@
+//! Tests for invalid --manifest-path arguments.
+
 use cargo_test_support::{basic_bin_manifest, main_file, project};
 
 fn assert_not_a_cargo_toml(command: &str, manifest_path_argument: &str) {
diff --git a/tests/testsuite/bench.rs b/tests/testsuite/bench.rs
index d3d5bb93bda..9e03871ab3e 100644
--- a/tests/testsuite/bench.rs
+++ b/tests/testsuite/bench.rs
@@ -1,3 +1,5 @@
+//! Tests for the `cargo bench` command.
+
 use cargo_test_support::is_nightly;
 use cargo_test_support::paths::CargoPathExt;
 use cargo_test_support::{basic_bin_manifest, basic_lib_manifest, basic_manifest, project};
diff --git a/tests/testsuite/build.rs b/tests/testsuite/build.rs
index 97c4c8d4825..8d9013aef9c 100644
--- a/tests/testsuite/build.rs
+++ b/tests/testsuite/build.rs
@@ -1,3 +1,5 @@
+//! Tests for the `cargo build` command.
+
 use cargo::util::paths::dylib_path_envvar;
 use cargo_test_support::paths::{root, CargoPathExt};
 use cargo_test_support::registry::Package;
@@ -4607,3 +4609,65 @@ d
         )
         .run();
 }
+
+#[cargo_test]
+fn build_lib_only() {
+    let p = project()
+        .file("src/main.rs", "fn main() {}")
+        .file("src/lib.rs", r#" "#)
+        .build();
+
+    p.cargo("build --lib -v")
+        .with_stderr(
+            "\
+[COMPILING] foo v0.0.1 ([CWD])
+[RUNNING] `rustc --crate-name foo src/lib.rs [..]--crate-type lib \
+        --emit=[..]link -C debuginfo=2 \
+        -C metadata=[..] \
+        --out-dir [..] \
+        -L dependency=[CWD]/target/debug/deps`
+[FINISHED] dev [unoptimized + debuginfo] target(s) in [..]",
+        )
+        .run();
+}
+
+#[cargo_test]
+fn build_with_no_lib() {
+    let p = project()
+        .file("Cargo.toml", &basic_bin_manifest("foo"))
+        .file("src/main.rs", "fn main() {}")
+        .build();
+
+    p.cargo("build --lib")
+        .with_status(101)
+        .with_stderr("[ERROR] no library targets found in package `foo`")
+        .run();
+}
+
+#[cargo_test]
+fn build_with_relative_cargo_home_path() {
+    let p = project()
+        .file(
+            "Cargo.toml",
+            r#"
+            [package]
+
+            name = "foo"
+            version = "0.0.1"
+            authors = ["wycats@example.com"]
+
+            [dependencies]
+
+            "test-dependency" = { path = "src/test_dependency" }
+        "#,
+        )
+        .file("src/main.rs", "fn main() {}")
+        .file("src/test_dependency/src/lib.rs", r#" "#)
+        .file(
+            "src/test_dependency/Cargo.toml",
+            &basic_manifest("test-dependency", "0.0.1"),
+        )
+        .build();
+
+    p.cargo("build").env("CARGO_HOME", "./cargo_home/").run();
+}
diff --git a/tests/testsuite/build_lib.rs b/tests/testsuite/build_lib.rs
deleted file mode 100644
index f14e182ee14..00000000000
--- a/tests/testsuite/build_lib.rs
+++ /dev/null
@@ -1,63 +0,0 @@
-use cargo_test_support::{basic_bin_manifest, basic_manifest, project};
-
-#[cargo_test]
-fn build_lib_only() {
-    let p = project()
-        .file("src/main.rs", "fn main() {}")
-        .file("src/lib.rs", r#" "#)
-        .build();
-
-    p.cargo("build --lib -v")
-        .with_stderr(
-            "\
-[COMPILING] foo v0.0.1 ([CWD])
-[RUNNING] `rustc --crate-name foo src/lib.rs [..]--crate-type lib \
-        --emit=[..]link -C debuginfo=2 \
-        -C metadata=[..] \
-        --out-dir [..] \
-        -L dependency=[CWD]/target/debug/deps`
-[FINISHED] dev [unoptimized + debuginfo] target(s) in [..]",
-        )
-        .run();
-}
-
-#[cargo_test]
-fn build_with_no_lib() {
-    let p = project()
-        .file("Cargo.toml", &basic_bin_manifest("foo"))
-        .file("src/main.rs", "fn main() {}")
-        .build();
-
-    p.cargo("build --lib")
-        .with_status(101)
-        .with_stderr("[ERROR] no library targets found in package `foo`")
-        .run();
-}
-
-#[cargo_test]
-fn build_with_relative_cargo_home_path() {
-    let p = project()
-        .file(
-            "Cargo.toml",
-            r#"
-            [package]
-
-            name = "foo"
-            version = "0.0.1"
-            authors = ["wycats@example.com"]
-
-            [dependencies]
-
-            "test-dependency" = { path = "src/test_dependency" }
-        "#,
-        )
-        .file("src/main.rs", "fn main() {}")
-        .file("src/test_dependency/src/lib.rs", r#" "#)
-        .file(
-            "src/test_dependency/Cargo.toml",
-            &basic_manifest("test-dependency", "0.0.1"),
-        )
-        .build();
-
-    p.cargo("build").env("CARGO_HOME", "./cargo_home/").run();
-}
diff --git a/tests/testsuite/build_plan.rs b/tests/testsuite/build_plan.rs
index 3874986c245..6161dd83c7e 100644
--- a/tests/testsuite/build_plan.rs
+++ b/tests/testsuite/build_plan.rs
@@ -1,3 +1,5 @@
+//! Tests for --build-plan feature.
+
 use cargo_test_support::registry::Package;
 use cargo_test_support::{basic_bin_manifest, basic_manifest, main_file, project};
 
diff --git a/tests/testsuite/build_script.rs b/tests/testsuite/build_script.rs
index 6d7f040319b..9faeefdfccd 100644
--- a/tests/testsuite/build_script.rs
+++ b/tests/testsuite/build_script.rs
@@ -1,3 +1,5 @@
+//! Tests for build.rs scripts.
+
 use std::env;
 use std::fs::{self, File};
 use std::io;
diff --git a/tests/testsuite/build_script_env.rs b/tests/testsuite/build_script_env.rs
index f45a430d6cc..b11f381059b 100644
--- a/tests/testsuite/build_script_env.rs
+++ b/tests/testsuite/build_script_env.rs
@@ -1,3 +1,5 @@
+//! Tests for build.rs rerun-if-env-changed.
+
 use std::fs::File;
 
 use cargo_test_support::project;
diff --git a/tests/testsuite/cache_messages.rs b/tests/testsuite/cache_messages.rs
index 4a0b01981dd..e5afc00437d 100644
--- a/tests/testsuite/cache_messages.rs
+++ b/tests/testsuite/cache_messages.rs
@@ -1,3 +1,5 @@
+//! Tests for caching compiler diagnostics.
+
 use cargo_test_support::{
     clippy_is_available, is_coarse_mtime, process, project, registry::Package, sleep_ms,
 };
diff --git a/tests/testsuite/cargo_alias_config.rs b/tests/testsuite/cargo_alias_config.rs
index 8ce0f51adfe..a5a83c0de98 100644
--- a/tests/testsuite/cargo_alias_config.rs
+++ b/tests/testsuite/cargo_alias_config.rs
@@ -1,3 +1,5 @@
+//! Tests for `[alias]` config command aliases.
+
 use cargo_test_support::{basic_bin_manifest, project};
 
 #[cargo_test]
diff --git a/tests/testsuite/cargo_command.rs b/tests/testsuite/cargo_command.rs
index a09751acc77..25e4bf9c53b 100644
--- a/tests/testsuite/cargo_command.rs
+++ b/tests/testsuite/cargo_command.rs
@@ -1,3 +1,5 @@
+//! Tests for custom cargo commands and other global command features.
+
 use std::env;
 use std::fs::{self, File};
 use std::io::prelude::*;
diff --git a/tests/testsuite/cargo_features.rs b/tests/testsuite/cargo_features.rs
index 45524d1c7e1..9319d5ee11a 100644
--- a/tests/testsuite/cargo_features.rs
+++ b/tests/testsuite/cargo_features.rs
@@ -1,3 +1,5 @@
+//! Tests for `cargo-features` definitions.
+
 use cargo_test_support::{project, registry};
 
 #[cargo_test]
diff --git a/tests/testsuite/cfg.rs b/tests/testsuite/cfg.rs
index 2e8aae19582..e12dd75bdbc 100644
--- a/tests/testsuite/cfg.rs
+++ b/tests/testsuite/cfg.rs
@@ -1,3 +1,5 @@
+//! Tests for cfg() expressions.
+
 use cargo_test_support::registry::Package;
 use cargo_test_support::rustc_host;
 use cargo_test_support::{basic_manifest, project};
diff --git a/tests/testsuite/check.rs b/tests/testsuite/check.rs
index be1031106a1..27cfbda7010 100644
--- a/tests/testsuite/check.rs
+++ b/tests/testsuite/check.rs
@@ -1,3 +1,5 @@
+//! Tests for the `cargo check` command.
+
 use std::fmt::{self, Write};
 
 use cargo_test_support::install::exe;
diff --git a/tests/testsuite/clean.rs b/tests/testsuite/clean.rs
index 103b707f1e5..179ca48995b 100644
--- a/tests/testsuite/clean.rs
+++ b/tests/testsuite/clean.rs
@@ -1,3 +1,5 @@
+//! Tests for the `cargo clean` command.
+
 use std::env;
 
 use cargo_test_support::registry::Package;
diff --git a/tests/testsuite/clippy.rs b/tests/testsuite/clippy.rs
index 5e5000ff83f..cf2a37be374 100644
--- a/tests/testsuite/clippy.rs
+++ b/tests/testsuite/clippy.rs
@@ -1,3 +1,5 @@
+//! Tests for the `cargo clippy` command.
+
 use cargo_test_support::{clippy_is_available, project, registry::Package};
 
 #[cargo_test]
diff --git a/tests/testsuite/collisions.rs b/tests/testsuite/collisions.rs
index 46b6a976b7b..9c479b22f79 100644
--- a/tests/testsuite/collisions.rs
+++ b/tests/testsuite/collisions.rs
@@ -1,3 +1,8 @@
+//! Tests for when multiple artifacts have the same output filename.
+//! See https://github.com/rust-lang/cargo/issues/6313 for more details.
+//! Ideally these should never happen, but I don't think we'll ever be able to
+//! prevent all collisions.
+
 use cargo_test_support::basic_manifest;
 use cargo_test_support::project;
 use std::env;
diff --git a/tests/testsuite/concurrent.rs b/tests/testsuite/concurrent.rs
index 878fe5770bf..41addb8ae65 100644
--- a/tests/testsuite/concurrent.rs
+++ b/tests/testsuite/concurrent.rs
@@ -1,3 +1,5 @@
+//! Tests for running multiple `cargo` processes at the same time.
+
 use std::fs::{self, File};
 use std::io::Write;
 use std::net::TcpListener;
diff --git a/tests/testsuite/config.rs b/tests/testsuite/config.rs
index d6af8614fea..c3da985d1b4 100644
--- a/tests/testsuite/config.rs
+++ b/tests/testsuite/config.rs
@@ -1,3 +1,5 @@
+//! Tests for config settings.
+
 use std::borrow::Borrow;
 use std::collections;
 use std::fs;
diff --git a/tests/testsuite/corrupt_git.rs b/tests/testsuite/corrupt_git.rs
index 39b9e258474..22f61ea941a 100644
--- a/tests/testsuite/corrupt_git.rs
+++ b/tests/testsuite/corrupt_git.rs
@@ -1,3 +1,5 @@
+//! Tests for corrupt git repos.
+
 use std::fs;
 use std::path::{Path, PathBuf};
 
diff --git a/tests/testsuite/cross_compile.rs b/tests/testsuite/cross_compile.rs
index ae36b1e8e09..bf5fb5a5471 100644
--- a/tests/testsuite/cross_compile.rs
+++ b/tests/testsuite/cross_compile.rs
@@ -1,3 +1,7 @@
+//! Tests for cross compiling with --target.
+//!
+//! See `cargo_test_support::cross_compile` for more detail.
+
 use cargo_test_support::{basic_bin_manifest, basic_manifest, cross_compile, project};
 use cargo_test_support::{is_nightly, rustc_host};
 
diff --git a/tests/testsuite/cross_publish.rs b/tests/testsuite/cross_publish.rs
index 95ed071a4e8..bd6d2a9a356 100644
--- a/tests/testsuite/cross_publish.rs
+++ b/tests/testsuite/cross_publish.rs
@@ -1,3 +1,5 @@
+//! Tests for publishing using the `--target` flag.
+
 use std::fs::File;
 
 use cargo_test_support::{cross_compile, project, publish, registry};
diff --git a/tests/testsuite/custom_target.rs b/tests/testsuite/custom_target.rs
index ca28b28238b..3970bc8d43f 100644
--- a/tests/testsuite/custom_target.rs
+++ b/tests/testsuite/custom_target.rs
@@ -1,3 +1,5 @@
+//! Tests for custom json target specifications.
+
 use cargo_test_support::is_nightly;
 use cargo_test_support::{basic_manifest, project};
 
diff --git a/tests/testsuite/death.rs b/tests/testsuite/death.rs
index 9fae5448084..39ad914a6b3 100644
--- a/tests/testsuite/death.rs
+++ b/tests/testsuite/death.rs
@@ -1,3 +1,5 @@
+//! Tests for ctrl-C handling.
+
 use std::fs;
 use std::io::{self, Read};
 use std::net::TcpListener;
diff --git a/tests/testsuite/dep_info.rs b/tests/testsuite/dep_info.rs
index fe2b8c0dab3..886ef862cc4 100644
--- a/tests/testsuite/dep_info.rs
+++ b/tests/testsuite/dep_info.rs
@@ -1,3 +1,6 @@
+//! Tests for dep-info files. This includes the dep-info file Cargo creates in
+//! the output directory, and the ones stored in the fingerprint.
+
 use cargo_test_support::paths::{self, CargoPathExt};
 use cargo_test_support::registry::Package;
 use cargo_test_support::{
diff --git a/tests/testsuite/directory.rs b/tests/testsuite/directory.rs
index a7d60d1a7d2..8e1ec1b67fa 100644
--- a/tests/testsuite/directory.rs
+++ b/tests/testsuite/directory.rs
@@ -1,3 +1,5 @@
+//! Tests for directory sources.
+
 use std::collections::HashMap;
 use std::fs::{self, File};
 use std::io::prelude::*;
diff --git a/tests/testsuite/doc.rs b/tests/testsuite/doc.rs
index 33c15a9b8e8..305fe6ca20f 100644
--- a/tests/testsuite/doc.rs
+++ b/tests/testsuite/doc.rs
@@ -1,3 +1,5 @@
+//! Tests for the `cargo doc` command.
+
 use std::fs::{self, File};
 use std::io::Read;
 use std::str;
diff --git a/tests/testsuite/edition.rs b/tests/testsuite/edition.rs
index 7007f67a462..184b9b3cd0f 100644
--- a/tests/testsuite/edition.rs
+++ b/tests/testsuite/edition.rs
@@ -1,3 +1,5 @@
+//! Tests for edition setting.
+
 use cargo_test_support::{basic_lib_manifest, project};
 
 #[cargo_test]
diff --git a/tests/testsuite/features.rs b/tests/testsuite/features.rs
index e7d6040fd0b..128c3ae3305 100644
--- a/tests/testsuite/features.rs
+++ b/tests/testsuite/features.rs
@@ -1,3 +1,5 @@
+//! Tests for `[features]` table.
+
 use std::fs::File;
 use std::io::prelude::*;
 
diff --git a/tests/testsuite/fetch.rs b/tests/testsuite/fetch.rs
index 2978962025f..d3748eec998 100644
--- a/tests/testsuite/fetch.rs
+++ b/tests/testsuite/fetch.rs
@@ -1,3 +1,5 @@
+//! Tests for the `cargo fetch` command.
+
 use cargo_test_support::registry::Package;
 use cargo_test_support::rustc_host;
 use cargo_test_support::{basic_manifest, cross_compile, project};
diff --git a/tests/testsuite/fix.rs b/tests/testsuite/fix.rs
index 1c31865c10b..3bc7b71fa37 100644
--- a/tests/testsuite/fix.rs
+++ b/tests/testsuite/fix.rs
@@ -1,3 +1,5 @@
+//! Tests for the `cargo fix` command.
+
 use std::fs::File;
 
 use cargo_test_support::git;
diff --git a/tests/testsuite/freshness.rs b/tests/testsuite/freshness.rs
index 9bdbc2cffec..c393d8a91a2 100644
--- a/tests/testsuite/freshness.rs
+++ b/tests/testsuite/freshness.rs
@@ -1,3 +1,5 @@
+//! Tests for fingerprinting (rebuild detection).
+
 use filetime::FileTime;
 use std::fs::{self, File, OpenOptions};
 use std::io;
diff --git a/tests/testsuite/generate_lockfile.rs b/tests/testsuite/generate_lockfile.rs
index 23a71408b41..2d19882e063 100644
--- a/tests/testsuite/generate_lockfile.rs
+++ b/tests/testsuite/generate_lockfile.rs
@@ -1,3 +1,5 @@
+//! Tests for the `cargo generate-lockfile` command.
+
 use std::fs::{self, File};
 use std::io::prelude::*;
 
diff --git a/tests/testsuite/git.rs b/tests/testsuite/git.rs
index 3b81677d93b..ba9ace4b7ac 100644
--- a/tests/testsuite/git.rs
+++ b/tests/testsuite/git.rs
@@ -1,3 +1,5 @@
+//! Tests for git support.
+
 use git2;
 use std::env;
 use std::fs::{self, File};
diff --git a/tests/testsuite/build_auth.rs b/tests/testsuite/git_auth.rs
similarity index 99%
rename from tests/testsuite/build_auth.rs
rename to tests/testsuite/git_auth.rs
index d76f93e90b6..39f6c0d4e91 100644
--- a/tests/testsuite/build_auth.rs
+++ b/tests/testsuite/git_auth.rs
@@ -1,3 +1,5 @@
+//! Tests for git authentication.
+
 use std::collections::HashSet;
 use std::io::prelude::*;
 use std::io::BufReader;
diff --git a/tests/testsuite/small_fd_limits.rs b/tests/testsuite/git_gc.rs
similarity index 98%
rename from tests/testsuite/small_fd_limits.rs
rename to tests/testsuite/git_gc.rs
index 2a468e588b8..f4bee6514f2 100644
--- a/tests/testsuite/small_fd_limits.rs
+++ b/tests/testsuite/git_gc.rs
@@ -1,3 +1,5 @@
+//! Tests for git garbage collection.
+
 use std::env;
 use std::ffi::OsStr;
 use std::path::PathBuf;
diff --git a/tests/testsuite/init.rs b/tests/testsuite/init.rs
index 6fef7b7b269..5bb348ce623 100644
--- a/tests/testsuite/init.rs
+++ b/tests/testsuite/init.rs
@@ -1,3 +1,5 @@
+//! Tests for the `cargo init` command.
+
 use cargo_test_support;
 use std::env;
 use std::fs::{self, File};
diff --git a/tests/testsuite/install.rs b/tests/testsuite/install.rs
index fa011f1e18a..3df720a9d1d 100644
--- a/tests/testsuite/install.rs
+++ b/tests/testsuite/install.rs
@@ -1,3 +1,5 @@
+//! Tests for the `cargo install` command.
+
 use std::fs::{self, File, OpenOptions};
 use std::io::prelude::*;
 
diff --git a/tests/testsuite/install_upgrade.rs b/tests/testsuite/install_upgrade.rs
index f591b80a28b..ee69bd85b71 100644
--- a/tests/testsuite/install_upgrade.rs
+++ b/tests/testsuite/install_upgrade.rs
@@ -1,3 +1,5 @@
+//! Tests for `cargo install` where it upgrades a package if it is out-of-date.
+
 use cargo::core::PackageId;
 use std::collections::BTreeSet;
 use std::env;
diff --git a/tests/testsuite/jobserver.rs b/tests/testsuite/jobserver.rs
index b0d90cc36f5..9e91c956cd7 100644
--- a/tests/testsuite/jobserver.rs
+++ b/tests/testsuite/jobserver.rs
@@ -1,3 +1,5 @@
+//! Tests for the jobserver protocol.
+
 use std::net::TcpListener;
 use std::process::Command;
 use std::thread;
diff --git a/tests/testsuite/list_targets.rs b/tests/testsuite/list_targets.rs
index a370a368292..09506f5dbce 100644
--- a/tests/testsuite/list_targets.rs
+++ b/tests/testsuite/list_targets.rs
@@ -1,3 +1,5 @@
+//! Tests for target filter flags giving suggestions on which targets are available.
+
 use cargo_test_support::project;
 
 const EXAMPLE: u8 = 0x1;
diff --git a/tests/testsuite/local_registry.rs b/tests/testsuite/local_registry.rs
index 8cffb29568e..f9fbbd351bb 100644
--- a/tests/testsuite/local_registry.rs
+++ b/tests/testsuite/local_registry.rs
@@ -1,3 +1,5 @@
+//! Tests for local-registry sources.
+
 use std::fs::{self, File};
 use std::io::prelude::*;
 
diff --git a/tests/testsuite/lockfile_compat.rs b/tests/testsuite/lockfile_compat.rs
index 2f0c34c4d30..5ffcbe56055 100644
--- a/tests/testsuite/lockfile_compat.rs
+++ b/tests/testsuite/lockfile_compat.rs
@@ -1,3 +1,5 @@
+//! Tests for supporting older versions of the Cargo.lock file format.
+
 use cargo_test_support::git;
 use cargo_test_support::registry::Package;
 use cargo_test_support::{basic_manifest, lines_match, project};
diff --git a/tests/testsuite/login.rs b/tests/testsuite/login.rs
index 69822207ada..01fe7e556cb 100644
--- a/tests/testsuite/login.rs
+++ b/tests/testsuite/login.rs
@@ -1,3 +1,5 @@
+//! Tests for the `cargo login` command.
+
 use std::fs::{self, File};
 use std::io::prelude::*;
 use std::path::PathBuf;
diff --git a/tests/testsuite/main.rs b/tests/testsuite/main.rs
index 280fe025653..9c22bbdc29d 100644
--- a/tests/testsuite/main.rs
+++ b/tests/testsuite/main.rs
@@ -16,8 +16,6 @@ mod bad_config;
 mod bad_manifest_path;
 mod bench;
 mod build;
-mod build_auth;
-mod build_lib;
 mod build_plan;
 mod build_script;
 mod build_script_env;
@@ -47,6 +45,8 @@ mod fix;
 mod freshness;
 mod generate_lockfile;
 mod git;
+mod git_auth;
+mod git_gc;
 mod init;
 mod install;
 mod install_upgrade;
@@ -59,14 +59,15 @@ mod member_errors;
 mod message_format;
 mod metabuild;
 mod metadata;
+mod minimal_versions;
 mod net_config;
 mod new;
 mod offline;
 mod out_dir;
-mod overrides;
 mod package;
 mod patch;
 mod path;
+mod paths;
 mod plugins;
 mod proc_macro;
 mod profile_config;
@@ -80,8 +81,8 @@ mod publish_lockfile;
 mod read_manifest;
 mod registry;
 mod rename_deps;
+mod replace;
 mod required_features;
-mod resolve;
 mod run;
 mod rustc;
 mod rustc_info_cache;
@@ -90,7 +91,6 @@ mod rustdocflags;
 mod rustflags;
 mod search;
 mod shell_quoting;
-mod small_fd_limits;
 mod standard_lib;
 mod test;
 mod timings;
diff --git a/tests/testsuite/member_errors.rs b/tests/testsuite/member_errors.rs
index e1d855bd0d6..10024dad74c 100644
--- a/tests/testsuite/member_errors.rs
+++ b/tests/testsuite/member_errors.rs
@@ -1,3 +1,5 @@
+//! Tests for workspace member errors.
+
 use cargo::core::resolver::ResolveError;
 use cargo::core::{compiler::CompileMode, Shell, Workspace};
 use cargo::ops::{self, CompileOptions};
diff --git a/tests/testsuite/message_format.rs b/tests/testsuite/message_format.rs
index 96de3355c34..df02cc079ec 100644
--- a/tests/testsuite/message_format.rs
+++ b/tests/testsuite/message_format.rs
@@ -1,3 +1,5 @@
+//! Tests for --message-format flag.
+
 use cargo_test_support::{basic_manifest, project};
 
 #[cargo_test]
diff --git a/tests/testsuite/metabuild.rs b/tests/testsuite/metabuild.rs
index 1024dc0be0e..004a39e569e 100644
--- a/tests/testsuite/metabuild.rs
+++ b/tests/testsuite/metabuild.rs
@@ -1,3 +1,5 @@
+//! Tests for the metabuild feature (declarative build scripts).
+
 use cargo_test_support::{
     basic_lib_manifest, basic_manifest, is_coarse_mtime, project, registry::Package, rustc_host,
     Project,
diff --git a/tests/testsuite/metadata.rs b/tests/testsuite/metadata.rs
index 47c9e9b84e1..f58adff5a44 100644
--- a/tests/testsuite/metadata.rs
+++ b/tests/testsuite/metadata.rs
@@ -1,3 +1,5 @@
+//! Tests for the `cargo metadata` command.
+
 use cargo_test_support::cross_compile::alternate;
 use cargo_test_support::registry::Package;
 use cargo_test_support::{basic_bin_manifest, basic_lib_manifest, main_file, project, rustc_host};
diff --git a/tests/testsuite/resolve.rs b/tests/testsuite/minimal_versions.rs
similarity index 88%
rename from tests/testsuite/resolve.rs
rename to tests/testsuite/minimal_versions.rs
index d40094946e8..5d8951ae5ec 100644
--- a/tests/testsuite/resolve.rs
+++ b/tests/testsuite/minimal_versions.rs
@@ -1,3 +1,7 @@
+//! Tests for minimal-version resolution.
+//!
+//! Note: Some tests are located in the resolver-tests package.
+
 use cargo_test_support::project;
 use cargo_test_support::registry::Package;
 
diff --git a/tests/testsuite/net_config.rs b/tests/testsuite/net_config.rs
index e62e0bd577a..158305d7393 100644
--- a/tests/testsuite/net_config.rs
+++ b/tests/testsuite/net_config.rs
@@ -1,3 +1,5 @@
+//! Tests for network configuration.
+
 use cargo_test_support::project;
 
 #[cargo_test]
diff --git a/tests/testsuite/new.rs b/tests/testsuite/new.rs
index 49e059746e8..bb94fd26a6c 100644
--- a/tests/testsuite/new.rs
+++ b/tests/testsuite/new.rs
@@ -1,3 +1,5 @@
+//! Tests for the `cargo new` command.
+
 use std::env;
 use std::fs::{self, File};
 use std::io::prelude::*;
diff --git a/tests/testsuite/offline.rs b/tests/testsuite/offline.rs
index 0ca57953390..65d98aa4d09 100644
--- a/tests/testsuite/offline.rs
+++ b/tests/testsuite/offline.rs
@@ -1,3 +1,5 @@
+//! Tests for --offline flag.
+
 use cargo_test_support::{basic_manifest, git, main_file, path2url, project, registry::Package};
 use std::fs;
 
diff --git a/tests/testsuite/out_dir.rs b/tests/testsuite/out_dir.rs
index 24aa304b08a..9c2f774fab8 100644
--- a/tests/testsuite/out_dir.rs
+++ b/tests/testsuite/out_dir.rs
@@ -1,3 +1,5 @@
+//! Tests for --out-dir flag.
+
 use std::env;
 use std::fs::{self, File};
 use std::path::Path;
diff --git a/tests/testsuite/package.rs b/tests/testsuite/package.rs
index feb272f78da..811642afa39 100644
--- a/tests/testsuite/package.rs
+++ b/tests/testsuite/package.rs
@@ -1,3 +1,5 @@
+//! Tests for the `cargo package` command.
+
 use std;
 use std::fs::File;
 use std::io::prelude::*;
diff --git a/tests/testsuite/patch.rs b/tests/testsuite/patch.rs
index 2add4f8e972..6660cdb36d8 100644
--- a/tests/testsuite/patch.rs
+++ b/tests/testsuite/patch.rs
@@ -1,3 +1,5 @@
+//! Tests for `[patch]` table source replacement.
+
 use std::fs::{self, File};
 use std::io::{Read, Write};
 
diff --git a/tests/testsuite/path.rs b/tests/testsuite/path.rs
index d983b7c29f4..d1c4eff5dd4 100644
--- a/tests/testsuite/path.rs
+++ b/tests/testsuite/path.rs
@@ -1,3 +1,5 @@
+//! Tests for `path` dependencies.
+
 use std::fs::{self, File};
 use std::io::prelude::*;
 
@@ -1015,32 +1017,3 @@ fn workspace_produces_rlib() {
     assert!(p.root().join("target/debug/libtop.rlib").is_file());
     assert!(!p.root().join("target/debug/libfoo.rlib").is_file());
 }
-
-#[cargo_test]
-fn thin_lto_works() {
-    let p = project()
-        .file(
-            "Cargo.toml",
-            r#"
-            [project]
-            name = "top"
-            version = "0.5.0"
-            authors = []
-
-            [profile.release]
-            lto = 'thin'
-        "#,
-        )
-        .file("src/main.rs", "fn main() {}")
-        .build();
-
-    p.cargo("build --release -v")
-        .with_stderr(
-            "\
-[COMPILING] top [..]
-[RUNNING] `rustc [..] -C lto=thin [..]`
-[FINISHED] [..]
-",
-        )
-        .run();
-}
diff --git a/tests/testsuite/paths.rs b/tests/testsuite/paths.rs
new file mode 100644
index 00000000000..448376833fe
--- /dev/null
+++ b/tests/testsuite/paths.rs
@@ -0,0 +1,226 @@
+//! Tests for `paths` overrides.
+
+use cargo_test_support::registry::Package;
+use cargo_test_support::{basic_manifest, project};
+
+#[cargo_test]
+fn broken_path_override_warns() {
+    Package::new("bar", "0.1.0").publish();
+    Package::new("bar", "0.2.0").publish();
+
+    let p = project()
+        .file(
+            "Cargo.toml",
+            r#"
+            [package]
+            name = "foo"
+            version = "0.0.1"
+            authors = []
+
+            [dependencies]
+            a = { path = "a1" }
+        "#,
+        )
+        .file("src/lib.rs", "")
+        .file(
+            "a1/Cargo.toml",
+            r#"
+            [package]
+            name = "a"
+            version = "0.0.1"
+            authors = []
+
+            [dependencies]
+            bar = "0.1"
+        "#,
+        )
+        .file("a1/src/lib.rs", "")
+        .file(
+            "a2/Cargo.toml",
+            r#"
+            [package]
+            name = "a"
+            version = "0.0.1"
+            authors = []
+
+            [dependencies]
+            bar = "0.2"
+        "#,
+        )
+        .file("a2/src/lib.rs", "")
+        .file(".cargo/config", r#"paths = ["a2"]"#)
+        .build();
+
+    p.cargo("build")
+        .with_stderr(
+            "\
+[UPDATING] [..]
+warning: path override for crate `a` has altered the original list of
+dependencies; the dependency on `bar` was either added or
+modified to not match the previously resolved version
+
+This is currently allowed but is known to produce buggy behavior with spurious
+recompiles and changes to the crate graph. Path overrides unfortunately were
+never intended to support this feature, so for now this message is just a
+warning. In the future, however, this message will become a hard error.
+
+To change the dependency graph via an override it's recommended to use the
+`[replace]` feature of Cargo instead of the path override feature. This is
+documented online at the url below for more information.
+
+https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html#overriding-dependencies
+
+[DOWNLOADING] crates ...
+[DOWNLOADED] [..]
+[COMPILING] [..]
+[COMPILING] [..]
+[COMPILING] [..]
+[FINISHED] [..]
+",
+        )
+        .run();
+}
+
+#[cargo_test]
+fn override_to_path_dep() {
+    Package::new("bar", "0.1.0").dep("baz", "0.1").publish();
+    Package::new("baz", "0.1.0").publish();
+
+    let p = project()
+        .file(
+            "Cargo.toml",
+            r#"
+            [package]
+            name = "foo"
+            version = "0.0.1"
+            authors = []
+
+            [dependencies]
+            bar = "0.1.0"
+        "#,
+        )
+        .file("src/lib.rs", "")
+        .file(
+            "bar/Cargo.toml",
+            r#"
+            [package]
+            name = "bar"
+            version = "0.0.1"
+            authors = []
+
+            [dependencies]
+            baz = { path = "baz" }
+        "#,
+        )
+        .file("bar/src/lib.rs", "")
+        .file("bar/baz/Cargo.toml", &basic_manifest("baz", "0.0.1"))
+        .file("bar/baz/src/lib.rs", "")
+        .file(".cargo/config", r#"paths = ["bar"]"#)
+        .build();
+
+    p.cargo("build").run();
+}
+
+#[cargo_test]
+fn paths_ok_with_optional() {
+    Package::new("baz", "0.1.0").publish();
+
+    let p = project()
+        .file(
+            "Cargo.toml",
+            r#"
+            [package]
+            name = "foo"
+            version = "0.0.1"
+            authors = []
+
+            [dependencies]
+            bar = { path = "bar" }
+        "#,
+        )
+        .file("src/lib.rs", "")
+        .file(
+            "bar/Cargo.toml",
+            r#"
+            [package]
+            name = "bar"
+            version = "0.1.0"
+            authors = []
+
+            [dependencies]
+            baz = { version = "0.1", optional = true }
+        "#,
+        )
+        .file("bar/src/lib.rs", "")
+        .file(
+            "bar2/Cargo.toml",
+            r#"
+            [package]
+            name = "bar"
+            version = "0.1.0"
+            authors = []
+
+            [dependencies]
+            baz = { version = "0.1", optional = true }
+        "#,
+        )
+        .file("bar2/src/lib.rs", "")
+        .file(".cargo/config", r#"paths = ["bar2"]"#)
+        .build();
+
+    p.cargo("build")
+        .with_stderr(
+            "\
+[COMPILING] bar v0.1.0 ([..]bar2)
+[COMPILING] foo v0.0.1 ([..])
+[FINISHED] [..]
+",
+        )
+        .run();
+}
+
+#[cargo_test]
+fn paths_add_optional_bad() {
+    Package::new("baz", "0.1.0").publish();
+
+    let p = project()
+        .file(
+            "Cargo.toml",
+            r#"
+            [package]
+            name = "foo"
+            version = "0.0.1"
+            authors = []
+
+            [dependencies]
+            bar = { path = "bar" }
+        "#,
+        )
+        .file("src/lib.rs", "")
+        .file("bar/Cargo.toml", &basic_manifest("bar", "0.1.0"))
+        .file("bar/src/lib.rs", "")
+        .file(
+            "bar2/Cargo.toml",
+            r#"
+            [package]
+            name = "bar"
+            version = "0.1.0"
+            authors = []
+
+            [dependencies]
+            baz = { version = "0.1", optional = true }
+        "#,
+        )
+        .file("bar2/src/lib.rs", "")
+        .file(".cargo/config", r#"paths = ["bar2"]"#)
+        .build();
+
+    p.cargo("build")
+        .with_stderr_contains(
+            "\
+warning: path override for crate `bar` has altered the original list of
+dependencies; the dependency on `baz` was either added or\
+",
+        )
+        .run();
+}
diff --git a/tests/testsuite/plugins.rs b/tests/testsuite/plugins.rs
index 54701393496..c66182f5667 100644
--- a/tests/testsuite/plugins.rs
+++ b/tests/testsuite/plugins.rs
@@ -1,3 +1,5 @@
+//! Tests for rustc plugins.
+
 use cargo_test_support::{basic_manifest, project};
 use cargo_test_support::{is_nightly, rustc_host};
 
diff --git a/tests/testsuite/proc_macro.rs b/tests/testsuite/proc_macro.rs
index d3774bf09c6..8c5326c365a 100644
--- a/tests/testsuite/proc_macro.rs
+++ b/tests/testsuite/proc_macro.rs
@@ -1,3 +1,5 @@
+//! Tests for proc-macros.
+
 use cargo_test_support::is_nightly;
 use cargo_test_support::project;
 
diff --git a/tests/testsuite/profile_config.rs b/tests/testsuite/profile_config.rs
index f48c46ff99c..481ae3786d1 100644
--- a/tests/testsuite/profile_config.rs
+++ b/tests/testsuite/profile_config.rs
@@ -1,3 +1,5 @@
+//! Tests for profiles defined in config files.
+
 use cargo_test_support::{basic_lib_manifest, paths, project};
 
 #[cargo_test]
diff --git a/tests/testsuite/profile_custom.rs b/tests/testsuite/profile_custom.rs
index 1b95a80aff3..c7c3455cff7 100644
--- a/tests/testsuite/profile_custom.rs
+++ b/tests/testsuite/profile_custom.rs
@@ -1,3 +1,5 @@
+//! Tests for named profiles.
+
 use cargo_test_support::{basic_lib_manifest, project};
 
 #[cargo_test]
diff --git a/tests/testsuite/profile_overrides.rs b/tests/testsuite/profile_overrides.rs
index da197fcd419..ddb61562d49 100644
--- a/tests/testsuite/profile_overrides.rs
+++ b/tests/testsuite/profile_overrides.rs
@@ -1,3 +1,5 @@
+//! Tests for profile overrides (build-override and per-package overrides).
+
 use cargo_test_support::registry::Package;
 use cargo_test_support::{basic_lib_manifest, basic_manifest, project};
 
diff --git a/tests/testsuite/profile_targets.rs b/tests/testsuite/profile_targets.rs
index 2fc76b66775..3df8fe88411 100644
--- a/tests/testsuite/profile_targets.rs
+++ b/tests/testsuite/profile_targets.rs
@@ -1,6 +1,8 @@
-use cargo_test_support::{basic_manifest, is_nightly, project, Project};
+//! Tests for checking exactly how profiles correspond with each unit. For
+//! example, the `test` profile applying to test targets, but not other
+//! targets, etc.
 
-// These tests try to exercise exactly which profiles are selected for every target.
+use cargo_test_support::{basic_manifest, is_nightly, project, Project};
 
 fn all_target_project() -> Project {
     // This abuses the `codegen-units` setting so that we can verify exactly
diff --git a/tests/testsuite/profiles.rs b/tests/testsuite/profiles.rs
index ee90dbe451e..9f6d0b5b315 100644
--- a/tests/testsuite/profiles.rs
+++ b/tests/testsuite/profiles.rs
@@ -1,3 +1,5 @@
+//! Tests for profiles.
+
 use std::env;
 
 use cargo_test_support::project;
@@ -437,3 +439,32 @@ fn debug_0_report() {
         )
         .run();
 }
+
+#[cargo_test]
+fn thin_lto_works() {
+    let p = project()
+        .file(
+            "Cargo.toml",
+            r#"
+            [project]
+            name = "top"
+            version = "0.5.0"
+            authors = []
+
+            [profile.release]
+            lto = 'thin'
+        "#,
+        )
+        .file("src/main.rs", "fn main() {}")
+        .build();
+
+    p.cargo("build --release -v")
+        .with_stderr(
+            "\
+[COMPILING] top [..]
+[RUNNING] `rustc [..] -C lto=thin [..]`
+[FINISHED] [..]
+",
+        )
+        .run();
+}
diff --git a/tests/testsuite/pub_priv.rs b/tests/testsuite/pub_priv.rs
index d17e2365294..97748d8bc2d 100644
--- a/tests/testsuite/pub_priv.rs
+++ b/tests/testsuite/pub_priv.rs
@@ -1,3 +1,5 @@
+//! Tests for public/private dependencies.
+
 use cargo_test_support::registry::Package;
 use cargo_test_support::{is_nightly, project};
 
diff --git a/tests/testsuite/publish.rs b/tests/testsuite/publish.rs
index 545f2302cf9..99dc98206d3 100644
--- a/tests/testsuite/publish.rs
+++ b/tests/testsuite/publish.rs
@@ -1,3 +1,5 @@
+//! Tests for the `cargo publish` command.
+
 use std::fs::{self, File};
 use std::io::prelude::*;
 
diff --git a/tests/testsuite/publish_lockfile.rs b/tests/testsuite/publish_lockfile.rs
index 2e49f4e0c76..d949aa62f8e 100644
--- a/tests/testsuite/publish_lockfile.rs
+++ b/tests/testsuite/publish_lockfile.rs
@@ -1,3 +1,5 @@
+//! Tests for including `Cargo.lock` when publishing/packaging.
+
 use std;
 use std::fs::File;
 
diff --git a/tests/testsuite/read_manifest.rs b/tests/testsuite/read_manifest.rs
index 33f86c6eee8..7ca0c6f9bd4 100644
--- a/tests/testsuite/read_manifest.rs
+++ b/tests/testsuite/read_manifest.rs
@@ -1,3 +1,5 @@
+//! Tests for the `cargo read-manifest` command.
+
 use cargo_test_support::{basic_bin_manifest, main_file, project};
 
 static MANIFEST_OUTPUT: &str = r#"
diff --git a/tests/testsuite/registry.rs b/tests/testsuite/registry.rs
index b4de94e21e3..7e06afa942c 100644
--- a/tests/testsuite/registry.rs
+++ b/tests/testsuite/registry.rs
@@ -1,3 +1,5 @@
+//! Tests for normal registry dependencies.
+
 use std::fs::{self, File};
 use std::io::prelude::*;
 use std::path::Path;
diff --git a/tests/testsuite/rename_deps.rs b/tests/testsuite/rename_deps.rs
index ade3867d36c..c1dd6d2c3f6 100644
--- a/tests/testsuite/rename_deps.rs
+++ b/tests/testsuite/rename_deps.rs
@@ -1,3 +1,5 @@
+//! Tests for renaming dependencies.
+
 use cargo_test_support::git;
 use cargo_test_support::paths;
 use cargo_test_support::registry::Package;
diff --git a/tests/testsuite/overrides.rs b/tests/testsuite/replace.rs
similarity index 83%
rename from tests/testsuite/overrides.rs
rename to tests/testsuite/replace.rs
index 341dba6f4b6..155959343dd 100644
--- a/tests/testsuite/overrides.rs
+++ b/tests/testsuite/replace.rs
@@ -1,3 +1,5 @@
+//! Tests for `[replace]` table source replacement.
+
 use cargo_test_support::git;
 use cargo_test_support::paths;
 use cargo_test_support::registry::Package;
@@ -813,84 +815,6 @@ fn no_override_self() {
     p.cargo("build --verbose").run();
 }
 
-#[cargo_test]
-fn broken_path_override_warns() {
-    Package::new("bar", "0.1.0").publish();
-    Package::new("bar", "0.2.0").publish();
-
-    let p = project()
-        .file(
-            "Cargo.toml",
-            r#"
-            [package]
-            name = "foo"
-            version = "0.0.1"
-            authors = []
-
-            [dependencies]
-            a = { path = "a1" }
-        "#,
-        )
-        .file("src/lib.rs", "")
-        .file(
-            "a1/Cargo.toml",
-            r#"
-            [package]
-            name = "a"
-            version = "0.0.1"
-            authors = []
-
-            [dependencies]
-            bar = "0.1"
-        "#,
-        )
-        .file("a1/src/lib.rs", "")
-        .file(
-            "a2/Cargo.toml",
-            r#"
-            [package]
-            name = "a"
-            version = "0.0.1"
-            authors = []
-
-            [dependencies]
-            bar = "0.2"
-        "#,
-        )
-        .file("a2/src/lib.rs", "")
-        .file(".cargo/config", r#"paths = ["a2"]"#)
-        .build();
-
-    p.cargo("build")
-        .with_stderr(
-            "\
-[UPDATING] [..]
-warning: path override for crate `a` has altered the original list of
-dependencies; the dependency on `bar` was either added or
-modified to not match the previously resolved version
-
-This is currently allowed but is known to produce buggy behavior with spurious
-recompiles and changes to the crate graph. Path overrides unfortunately were
-never intended to support this feature, so for now this message is just a
-warning. In the future, however, this message will become a hard error.
-
-To change the dependency graph via an override it's recommended to use the
-`[replace]` feature of Cargo instead of the path override feature. This is
-documented online at the url below for more information.
-
-https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html#overriding-dependencies
-
-[DOWNLOADING] crates ...
-[DOWNLOADED] [..]
-[COMPILING] [..]
-[COMPILING] [..]
-[COMPILING] [..]
-[FINISHED] [..]
-",
-        )
-        .run();
-}
-
 #[cargo_test]
 fn override_an_override() {
     Package::new("chrono", "0.2.0")
@@ -1118,46 +1042,6 @@ fn no_warnings_when_replace_is_used_in_another_workspace_member() {
         .run();
 }
 
-#[cargo_test]
-fn override_to_path_dep() {
-    Package::new("bar", "0.1.0").dep("baz", "0.1").publish();
-    Package::new("baz", "0.1.0").publish();
-
-    let p = project()
-        .file(
-            "Cargo.toml",
-            r#"
-            [package]
-            name = "foo"
-            version = "0.0.1"
-            authors = []
-
-            [dependencies]
-            bar = "0.1.0"
-        "#,
-        )
-        .file("src/lib.rs", "")
-        .file(
-            "bar/Cargo.toml",
-            r#"
-            [package]
-            name = "bar"
-            version = "0.0.1"
-            authors = []
-
-            [dependencies]
-            baz = { path = "baz" }
-        "#,
-        )
-        .file("bar/src/lib.rs", "")
-        .file("bar/baz/Cargo.toml", &basic_manifest("baz", "0.0.1"))
-        .file("bar/baz/src/lib.rs", "")
-        .file(".cargo/config", r#"paths = ["bar"]"#)
-        .build();
-
-    p.cargo("build").run();
-}
-
 #[cargo_test]
 fn replace_to_path_dep() {
     Package::new("bar", "0.1.0").dep("baz", "0.1").publish();
@@ -1203,110 +1087,6 @@ fn replace_to_path_dep() {
     p.cargo("build").run();
 }
 
-#[cargo_test]
-fn paths_ok_with_optional() {
-    Package::new("baz", "0.1.0").publish();
-
-    let p = project()
-        .file(
-            "Cargo.toml",
-            r#"
-            [package]
-            name = "foo"
-            version = "0.0.1"
-            authors = []
-
-            [dependencies]
-            bar = { path = "bar" }
-        "#,
-        )
-        .file("src/lib.rs", "")
-        .file(
-            "bar/Cargo.toml",
-            r#"
-            [package]
-            name = "bar"
-            version = "0.1.0"
-            authors = []
-
-            [dependencies]
-            baz = { version = "0.1", optional = true }
-        "#,
-        )
-        .file("bar/src/lib.rs", "")
-        .file(
-            "bar2/Cargo.toml",
-            r#"
-            [package]
-            name = "bar"
-            version = "0.1.0"
-            authors = []
-
-            [dependencies]
-            baz = { version = "0.1", optional = true }
-        "#,
-        )
-        .file("bar2/src/lib.rs", "")
-        .file(".cargo/config", r#"paths = ["bar2"]"#)
-        .build();
-
-    p.cargo("build")
-        .with_stderr(
-            "\
-[COMPILING] bar v0.1.0 ([..]bar2)
-[COMPILING] foo v0.0.1 ([..])
-[FINISHED] [..]
-",
-        )
-        .run();
-}
-
-#[cargo_test]
-fn paths_add_optional_bad() {
-    Package::new("baz", "0.1.0").publish();
-
-    let p = project()
-        .file(
-            "Cargo.toml",
-            r#"
-            [package]
-            name = "foo"
-            version = "0.0.1"
-            authors = []
-
-            [dependencies]
-            bar = { path = "bar" }
-        "#,
-        )
-        .file("src/lib.rs", "")
-        .file("bar/Cargo.toml", &basic_manifest("bar", "0.1.0"))
-        .file("bar/src/lib.rs", "")
-        .file(
-            "bar2/Cargo.toml",
-            r#"
-            [package]
-            name = "bar"
-            version = "0.1.0"
-            authors = []
-
-            [dependencies]
-            baz = { version = "0.1", optional = true }
-        "#,
-        )
-        .file("bar2/src/lib.rs", "")
-        .file(".cargo/config", r#"paths = ["bar2"]"#)
-        .build();
-
-    p.cargo("build")
-        .with_stderr_contains(
-            "\
-warning: path override for crate `bar` has altered the original list of
-dependencies; the dependency on `baz` was either added or\
-",
-        )
-        .run();
-}
-
 #[cargo_test]
 fn override_with_default_feature() {
     Package::new("another", "0.1.0").publish();
diff --git a/tests/testsuite/required_features.rs b/tests/testsuite/required_features.rs
index 5384ba755d4..6afd917ee19 100644
--- a/tests/testsuite/required_features.rs
+++ b/tests/testsuite/required_features.rs
@@ -1,3 +1,5 @@
+//! Tests for targets with `required-features`.
+
 use cargo_test_support::install::{
     assert_has_installed_exe, assert_has_not_installed_exe, cargo_home,
 };
diff --git a/tests/testsuite/run.rs b/tests/testsuite/run.rs
index 41d1ec4a3fd..918c2320373 100644
--- a/tests/testsuite/run.rs
+++ b/tests/testsuite/run.rs
@@ -1,3 +1,5 @@
+//! Tests for the `cargo run` command.
+
 use cargo::util::paths::dylib_path_envvar;
 use cargo_test_support::{basic_bin_manifest, basic_lib_manifest, project, Project};
 
diff --git a/tests/testsuite/rustc.rs b/tests/testsuite/rustc.rs
index 1c208897874..b8b081eb287 100644
--- a/tests/testsuite/rustc.rs
+++ b/tests/testsuite/rustc.rs
@@ -1,3 +1,5 @@
+//! Tests for the `cargo rustc` command.
+
 use cargo_test_support::{basic_bin_manifest, basic_lib_manifest, basic_manifest, project};
 
 const CARGO_RUSTC_ERROR: &str =
diff --git a/tests/testsuite/rustc_info_cache.rs b/tests/testsuite/rustc_info_cache.rs
index fcc39e6bed0..52d0eccdec1 100644
--- a/tests/testsuite/rustc_info_cache.rs
+++ b/tests/testsuite/rustc_info_cache.rs
@@ -1,3 +1,5 @@
+//! Tests for the cache file for the rustc version info.
+
 use cargo_test_support::paths::CargoPathExt;
 use cargo_test_support::{basic_manifest, project};
 use std::env;
diff --git a/tests/testsuite/rustdoc.rs b/tests/testsuite/rustdoc.rs
index f270902d979..26f9a68513b 100644
--- a/tests/testsuite/rustdoc.rs
+++ b/tests/testsuite/rustdoc.rs
@@ -1,3 +1,5 @@
+//! Tests for the `cargo rustdoc` command.
+
 use cargo_test_support::{basic_manifest, project};
 
 #[cargo_test]
diff --git a/tests/testsuite/rustdocflags.rs b/tests/testsuite/rustdocflags.rs
index 7cfb220c851..5a15c446cad 100644
--- a/tests/testsuite/rustdocflags.rs
+++ b/tests/testsuite/rustdocflags.rs
@@ -1,3 +1,5 @@
+//! Tests for setting custom rustdoc flags.
+
 use cargo_test_support::project;
 
 #[cargo_test]
diff --git a/tests/testsuite/rustflags.rs b/tests/testsuite/rustflags.rs
index 30c3685c742..781935adee8 100644
--- a/tests/testsuite/rustflags.rs
+++ b/tests/testsuite/rustflags.rs
@@ -1,3 +1,5 @@
+//! Tests for setting custom rustc flags.
+
 use std::fs::{self, File};
 use std::io::Write;
 
diff --git a/tests/testsuite/search.rs b/tests/testsuite/search.rs
index f70857dcd13..6229358e602 100644
--- a/tests/testsuite/search.rs
+++ b/tests/testsuite/search.rs
@@ -1,3 +1,5 @@
+//! Tests for the `cargo search` command.
+
 use std::collections::HashSet;
 use std::fs::{self, File};
 use std::io::prelude::*;
diff --git a/tests/testsuite/shell_quoting.rs b/tests/testsuite/shell_quoting.rs
index 50d58d559ff..a45f8c6a089 100644
--- a/tests/testsuite/shell_quoting.rs
+++ b/tests/testsuite/shell_quoting.rs
@@ -1,6 +1,6 @@
-//! this file tests that when the commands being run are shown
+//! This file tests that when the commands being run are shown
 //! in the output, their arguments are quoted properly
-//! so that the command can be run in a terminal
+//! so that the command can be run in a terminal.
 
 use cargo_test_support::project;
 
diff --git a/tests/testsuite/standard_lib.rs b/tests/testsuite/standard_lib.rs
index 6df837bd0ea..48f8b237f11 100644
--- a/tests/testsuite/standard_lib.rs
+++ b/tests/testsuite/standard_lib.rs
@@ -1,3 +1,9 @@
+//! Tests for building the standard library (-Zbuild-std).
+//!
+//! These tests all use a "mock" standard library so that we don't have to
+//! rebuild the real one. There is a separate integration test `build-std`
+//! which builds the real thing, but that should be avoided if possible.
+
 use cargo_test_support::registry::{Dependency, Package};
 use cargo_test_support::ProjectBuilder;
 use cargo_test_support::{is_nightly, paths, project, rustc_host, Execs};
diff --git a/tests/testsuite/test.rs b/tests/testsuite/test.rs
index 6201f09f5a9..a092002fcc8 100644
--- a/tests/testsuite/test.rs
+++ b/tests/testsuite/test.rs
@@ -1,3 +1,5 @@
+//! Tests for the `cargo test` command.
+
 use cargo;
 use cargo_test_support::paths::CargoPathExt;
 use cargo_test_support::registry::Package;
diff --git a/tests/testsuite/timings.rs b/tests/testsuite/timings.rs
index 6f4e6b3ffa8..cd173dd74c9 100644
--- a/tests/testsuite/timings.rs
+++ b/tests/testsuite/timings.rs
@@ -1,3 +1,5 @@
+//! Tests for -Ztimings.
+
 use cargo_test_support::project;
 use cargo_test_support::registry::Package;
 
diff --git a/tests/testsuite/tool_paths.rs b/tests/testsuite/tool_paths.rs
index 49ced238f36..956c83adfd5 100644
--- a/tests/testsuite/tool_paths.rs
+++ b/tests/testsuite/tool_paths.rs
@@ -1,3 +1,5 @@
+//! Tests for configuration values that point to programs.
+
 use cargo_test_support::rustc_host;
 use cargo_test_support::{basic_lib_manifest, project};
 
diff --git a/tests/testsuite/update.rs b/tests/testsuite/update.rs
index 6cfc67a2a3e..bd672f04022 100644
--- a/tests/testsuite/update.rs
+++ b/tests/testsuite/update.rs
@@ -1,3 +1,5 @@
+//! Tests for the `cargo update` command.
+
 use std::fs::File;
 use std::io::prelude::*;
 
diff --git a/tests/testsuite/vendor.rs b/tests/testsuite/vendor.rs
index 61f1d2452a5..4e448602f04 100644
--- a/tests/testsuite/vendor.rs
+++ b/tests/testsuite/vendor.rs
@@ -1,3 +1,5 @@
+//! Tests for the `cargo vendor` command.
+
 use cargo_test_support::git;
 use cargo_test_support::registry::Package;
 use cargo_test_support::{basic_lib_manifest, project, Project};
diff --git a/tests/testsuite/verify_project.rs b/tests/testsuite/verify_project.rs
index a9bdb909b6b..53b3accb0b4 100644
--- a/tests/testsuite/verify_project.rs
+++ b/tests/testsuite/verify_project.rs
@@ -1,3 +1,5 @@
+//! Tests for the `cargo verify-project` command.
+
 use cargo_test_support::{basic_bin_manifest, main_file, project};
 
 fn verify_project_success_output() -> String {
diff --git a/tests/testsuite/version.rs b/tests/testsuite/version.rs
index 0cb9fcc97b5..5d6fde1c131 100644
--- a/tests/testsuite/version.rs
+++ b/tests/testsuite/version.rs
@@ -1,3 +1,5 @@
+//! Tests for displaying the cargo version.
+
 use cargo;
 use cargo_test_support::project;
 
diff --git a/tests/testsuite/warn_on_failure.rs b/tests/testsuite/warn_on_failure.rs
index 0688326fd0f..7be49e4e41a 100644
--- a/tests/testsuite/warn_on_failure.rs
+++ b/tests/testsuite/warn_on_failure.rs
@@ -1,3 +1,5 @@
+//! Tests for whether or not warnings are displayed for build scripts.
+
 use cargo_test_support::registry::Package;
 use cargo_test_support::{project, Project};
 
diff --git a/tests/testsuite/workspaces.rs b/tests/testsuite/workspaces.rs
index d3444e1aab2..9d09eb5de67 100644
--- a/tests/testsuite/workspaces.rs
+++ b/tests/testsuite/workspaces.rs
@@ -1,3 +1,5 @@
+//! Tests for workspaces.
+
 use std::env;
 use std::fs::{self, File};
 use std::io::{Read, Write};