Fill in the tutorial section on testing

This commit is contained in:
Marijn Haverbeke 2011-11-04 12:23:35 +01:00
parent af1ce1f3de
commit 2c033f83ef
2 changed files with 82 additions and 9 deletions

View File

@ -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",

View File

@ -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)).