Auto merge of #5563 - ehuss:cargotest-doc, r=alexcrichton

cargotest: Add some more docs

Hopefully this isn't too wordy.  This isn't intended for rustdoc output, but generally to be read in-editor.

Author: bors

CONTRIBUTING.md

@@ -22,8 +22,8 @@ and unexpected behavior.
 its users' security, please do not open a public issue on GitHub. Instead,
 we ask you to refer to Rust's [security policy].**
 
-Opening an issue is as easy as following [this link][new-issues] and filling out 
-the fields. Here's a template that you can use to file an issue, though it's not 
+Opening an issue is as easy as following [this link][new-issues] and filling out
+the fields. Here's a template that you can use to file an issue, though it's not
 necessary to use it exactly:
 
     <short summary of the problem>
@@ -41,7 +41,7 @@ happened instead. Please use https://gist.github.com/ if your examples run long.
 
 ## Working on issues
 
-If you're looking for somewhere to start, check out the [E-easy][E-Easy] and 
+If you're looking for somewhere to start, check out the [E-easy][E-Easy] and
 [E-mentor][E-mentor] tags.
 
 Feel free to ask for guidelines on how to tackle a problem on [IRC] or open a
@@ -76,7 +76,8 @@ working on.
 * Include tests that cover all non-trivial code. The existing tests
 in `test/` provide templates on how to test Cargo's behavior in a
 sandbox-environment. The internal crate `cargotest` provides a vast amount
-of helpers to minimize boilerplate.
+of helpers to minimize boilerplate.  See [`cargotest/mod.rs`] for an
+introduction to writing tests.
 * Make sure `cargo test` passes. If you do not have the cross-compilers
 installed locally, install them using the instructions returned by
 `cargo test cross_compile::cross_tests` (twice, with `--toolchain nightly`
@@ -181,3 +182,4 @@ adding labels to triage issues:
 [I-nominated]: https://github.com/rust-lang/cargo/labels/I-nominated
 [Code of Conduct]: https://www.rust-lang.org/conduct.html
 [IRC]: https://kiwiirc.com/client/irc.mozilla.org/cargo
+[`cargotest/mod.rs`]: https://github.com/rust-lang/cargo/blob/master/tests/testsuite/cargotest/mod.rs

src/cargo/util/process_builder.rs

@@ -113,7 +113,7 @@ impl ProcessBuilder {
             .and_then(|s| s)
     }
 
-    /// Get all environment variables explicitally set or unset for the process (not inherited
+    /// Get all environment variables explicitly set or unset for the process (not inherited
     /// vars).
     pub fn get_envs(&self) -> &HashMap<String, Option<OsString>> {
         &self.env

tests/testsuite/cargotest/install.rs

@@ -11,6 +11,10 @@ pub fn cargo_home() -> PathBuf {
     paths::home().join(".cargo")
 }
 
+/// A `Matcher` used by `cargo install` tests to check if an executable binary
+/// has been installed.  Example usage:
+///
+///     assert_that(cargo_home(), has_installed_exe("foo"));
 pub struct InstalledExe(pub &'static str);
 
 pub fn exe(name: &str) -> String {

tests/testsuite/cargotest/mod.rs

@@ -1,3 +1,88 @@
+/*
+# Introduction To `cargotest`
+
+Cargo has a wide variety of integration tests that execute the `cargo` binary
+and verify its behavior.  The `cargotest` module contains many helpers to make
+this process easy.
+
+The general form of a test involves creating a "project", running cargo, and
+checking the result.  Projects are created with the `ProjectBuilder` where you
+specify some files to create.  The general form looks like this:
+
+```
+let p = project("foo")
+    .file("Cargo.toml", &basic_bin_manifest("foo"))
+    .file("src/main.rs", r#"fn main() { println!("hi!"); }"#)
+    .build();
+```
+
+To run cargo, call the `cargo` method and use the `hamcrest` matchers to check
+the output.
+
+```
+assert_that(
+    p.cargo("run --bin foo"),
+    execs()
+        .with_status(0)
+        .with_stderr(
+            "\
+[COMPILING] foo [..]
+[FINISHED] [..]
+[RUNNING] `target[/]debug[/]foo`
+",
+        )
+        .with_stdout("hi!"),
+);
+```
+
+The project creates a mini sandbox under the "cargo integration test"
+directory with each test getting a separate directory such as
+`/path/to/cargo/target/cit/t123/`.  Each project appears as a separate
+directory.  There is also an empty `home` directory created that will be used
+as a home directory instead of your normal home directory.
+
+See `cargotest::support::lines_match` for an explanation of the string pattern
+matching.
+
+See the `hamcrest` module for other matchers like
+`is_not(existing_file(path))`.  This is not the actual hamcrest library, but
+instead a lightweight subset of matchers that are used in cargo tests.
+
+Browse the `pub` functions in the `cargotest` module for a variety of other
+helpful utilities.
+
+## Testing Nightly Features
+
+If you are testing a Cargo feature that only works on "nightly" cargo, then
+you need to call `masquerade_as_nightly_cargo` on the process builder like
+this:
+
+```
+p.cargo("build").masquerade_as_nightly_cargo()
+```
+
+If you are testing a feature that only works on *nightly rustc* (such as
+benchmarks), then you should exit the test if it is not running with nightly
+rust, like this:
+
+```
+if !is_nightly() {
+    return;
+}
+```
+
+## Platform-specific Notes
+
+When checking output, be sure to use `[/]` when checking paths to
+automatically support backslashes on Windows.
+
+Be careful when executing binaries on Windows.  You should not rename, delete,
+or overwrite a binary immediately after running it.  Under some conditions
+Windows will fail with errors like "directory not empty" or "failed to remove"
+or "access is denied".
+
+*/
+
 use std::ffi::OsStr;
 use std::time::Duration;
 
@@ -19,6 +104,7 @@ pub static RUSTC: Rustc = Rustc::new(
 ).unwrap()
 );
 
+/// The rustc host such as `x86_64-unknown-linux-gnu`.
 pub fn rustc_host() -> String {
     RUSTC.with(|r| r.host.clone())
 }