From 8ba148b295bfaf6198ce4ce34c9eb6b93346c092 Mon Sep 17 00:00:00 2001
From: Tim Chevalier <chevalier@alum.wellesley.edu>
Date: Tue, 1 Oct 2013 12:05:57 -0700
Subject: [PATCH] docs / rustpkg: Document `rustpkg test` more

Talk about `rustpkg test` in the tutorial, and update its usage message.
---
 doc/tutorial-rustpkg.md | 48 +++++++++++++++++++++++++++++++++++++++++
 src/librustpkg/usage.rs |  6 +++---
 2 files changed, 51 insertions(+), 3 deletions(-)

diff --git a/doc/tutorial-rustpkg.md b/doc/tutorial-rustpkg.md
index 156613cef4d..fb15e0c0cf2 100644
--- a/doc/tutorial-rustpkg.md
+++ b/doc/tutorial-rustpkg.md
@@ -206,6 +206,54 @@ note: Installed package github.com/YOUR_USERNAME/hello-0.1 to /home/yourusername
 
 That's it!
 
+# Testing your Package
+
+Testing your package is simple as well. First, let's change `src/hello/lib.rs` to contain
+a function that can be sensibly tested:
+
+~~~
+#[desc = "A Rust package for determining whether unsigned integers are even."];
+#[license = "MIT"];
+
+pub fn is_even(i: uint) -> bool {
+	i % 2 == 0
+}
+~~~
+
+Once you've edited `lib.rs`, you can create a second crate file, `src/hello/test.rs`,
+to put tests in:
+
+~~~
+#[license = "MIT"];
+extern mod hello;
+use hello::is_even;
+
+#[test]
+fn test_is_even() {
+   assert!(is_even(0));
+   assert!(!is_even(1));
+   assert!(is_even(2));	
+}
+~~~
+
+Note that you have to import the crate you just created in `lib.rs` with the
+`extern mod hello` directive. That's because you're putting the tests in a different
+crate from the main library that you created.
+
+Now, you can use the `rustpkg test` command to build this test crate (and anything else
+it depends on) and run the tests, all in one step:
+
+~~~ {.notrust}
+$ rustpkg test hello
+WARNING: The Rust package manager is experimental and may be unstable
+note: Installed package hello-0.1 to /Users/tjc/.rust
+
+running 1 test
+test test_is_even ... ok
+
+test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured
+~~~
+
 # More resources
 
 There's a lot more going on with `rustpkg`, this is just to get you started.
diff --git a/src/librustpkg/usage.rs b/src/librustpkg/usage.rs
index a8126b49716..4b10451c813 100644
--- a/src/librustpkg/usage.rs
+++ b/src/librustpkg/usage.rs
@@ -141,9 +141,9 @@ information.");
 pub fn test() {
     io::println("rustpkg [options..] test
 
-Build all targets described in the package script in the current directory
-with the test flag. The test bootstraps will be run afterwards and the output
-and exit code will be redirected.
+Build all test crates in the current directory with the test flag.
+Then, run all the resulting test executables, redirecting the output
+and exit code.
 
 Options:
     -c, --cfg      Pass a cfg flag to the package script");