Fill in the tutorial section on testing

2 files changed, 82 insertions, 9 deletions

diff --git a/doc/tutorial/syntax.md b/doc/tutorial/syntax.md
index 0bf00616c6f..d2c36bcb35e 100644
--- a/doc/tutorial/syntax.md
+++ b/doc/tutorial/syntax.md
@@ -281,6 +281,8 @@ exists, convert the result of the expression to the given type.
 
 ## Attributes
 
+<a name="conditional></a>
+
 Every definition can be annotated with attributes. Attributes are meta
 information that can serve a variety of purposes. One of those is
 conditional compilation:
@@ -289,14 +291,20 @@ conditional compilation:
     fn register_win_service() { /* ... */ }
 
 This will cause the function to vanish without a trace during
-compilation on a non-Windows platform. Attributes always look like
-`#[attr]`, where `attr` can be simply a name (as in `#[test]`, which
-is used by the [built-in test framework](test.html)), a name followed
-by `=` and then a literal (as in `#[license = "BSD"]`, which is a
-valid way to annotate a Rust program as being released under a
-BSD-style license), or a name followed by a comma-separated list of
-nested attributes, as in the `cfg` example above, or in this
-[crate](mod.html) metadata declaration:
+compilation on a non-Windows platform, much like `#ifdef` in C (it
+allows `cfg(flag=value)` and `cfg(flag)` forms, where the second
+simply checks whether the configuration flag is defined at all). Flags
+for `target_os` and `target_arch` are set by the compiler. It is
+possible to set additional flags with the `--cfg` command-line option.
+
+Attributes always look like `#[attr]`, where `attr` can be simply a
+name (as in `#[test]`, which is used by the [built-in test
+framework](test.html)), a name followed by `=` and then a literal (as
+in `#[license = "BSD"]`, which is a valid way to annotate a Rust
+program as being released under a BSD-style license), or a name
+followed by a comma-separated list of nested attributes, as in the
+`cfg` example above, or in this [crate](mod.html) metadata
+declaration:
 
     #[link(name = "std",
            vers = "0.1",
diff --git a/doc/tutorial/test.md b/doc/tutorial/test.md
index 636f65947a0..b7185c51085 100644
--- a/doc/tutorial/test.md
+++ b/doc/tutorial/test.md
@@ -1,3 +1,68 @@
 # Testing
 
-FIXME to be written
+The Rust language has a facility for testing built into the language.
+Tests can be interspersed with other code, and annotated with the
+`#[test]` attribute.
+
+    use std;
+    
+    fn twice(x: int) -> int { x + x }
+    
+    #[test]
+    fn test_twice() {
+        let i = -100;
+        while i < 100 {
+            assert twice(i) == 2 * i;
+            i += 1;
+        }
+    }
+
+When you compile the program normally, the `test_twice` function will
+not be used. To actually run the tests, compile with the `--test`
+flag:
+
+    > rustc --lib twice.rs
+    > ./twice
+    running 1 tests
+    test test_twice ... ok
+    result: ok. 1 passed; 0 failed; 0 ignored
+
+Or, if we change the file to fail, for example by replacing `x + x`
+with `x + 1`:
+
+    running 1 tests
+    test test_twice ... FAILED
+    failures:
+        test_twice
+    result: FAILED. 0 passed; 1 failed; 0 ignored
+
+You can pass a command-line argument to a program compiled with
+`--test` to run only the tests whose name matches the given string. If
+we had, for example, test functions `test_twice`, `test_once_1`, and
+`test_once_2`, running our program with `./twice test_once` would run
+the latter two, and running it with `./twice test_once_2` would run
+only the last.
+
+To indicate that a test is supposed to fail instead of pass, you can
+give it a `#[should_fail]` attribute.
+
+    use std;
+    
+    fn divide(a: float, b: float) -> float {
+        if b == 0f { fail; }
+        a / b
+    }
+    
+    #[test]
+    #[should_fail]
+    fn divide_by_zero() { divide(1f, 0f); }
+
+To disable a test completely, add an `#[ignore]` attribute. Running a
+test runner (the program compiled with `--test`) with an `--ignored`
+command-line flag will cause it to also run the tests labelled as
+ignored.
+
+A program compiled as a test runner will have the configuration flag
+`test` defined, so that you can add code that won't be included in a
+normal compile with the `#[cfg(test)]` attribute (see [conditional
+compilation](syntax.md#conditional)).