Skip to content

Commit

Permalink
Rollup merge of rust-lang#37368 - trotter:patch-1, r=steveklabnik
Browse files Browse the repository at this point in the history
Update testing.md to reflect changes to cargo new

`cargo new` now creates a `src/lib.rs` with a `tests` module by default. I've updated the earlier examples in this doc to reflect this. However, I don't know how we want to approach the "introduction" to idiomatic testing that follows in "the tests module" section. I _think_ it should be broken apart, with the module concept being introduced early on, and the `super` concept being addressed when we hit the `add_two` example. I'd like to get agreement on that being the right approach before I do it though.

I _also_ removed the `#fn main() {}` hidden at the beginning of each example, as these cause Rust Playground to not treat the file as a set of tests that it can run. Removing it _should_ cause Rust Playground to display a "Test >" button in the top left when a user runs the code, which will allow them to see the test runner output.
  • Loading branch information
eddyb authored Nov 11, 2016
2 parents eb17276 + 2a832a0 commit a1cca91
Showing 1 changed file with 92 additions and 31 deletions.
123 changes: 92 additions & 31 deletions src/doc/book/testing.md
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,11 @@ $ cd adder
Cargo will automatically generate a simple test when you make a new project.
Here's the contents of `src/lib.rs`:

```rust
```rust,ignore
# // The next line exists to trick play.rust-lang.org into running our code as a
# // test:
# // fn main
#
#[cfg(test)]
mod tests {
#[test]
Expand All @@ -32,17 +36,30 @@ mod tests {
}
```

For now, let's remove the `mod` bit, and focus on just the function:

```rust,ignore
# // The next line exists to trick play.rust-lang.org into running our code as a
# // test:
# // fn main
#
#[test]
fn it_works() {
}
```

Note the `#[test]`. This attribute indicates that this is a test function. It
currently has no body. That's good enough to pass! We can run the tests with
`cargo test`:

```bash
$ cargo test
Compiling adder v0.1.0 (file:///home/you/projects/adder)
Running target/debug/deps/adder-91b3e234d4ed382a
Finished debug [unoptimized + debuginfo] target(s) in 0.15 secs
Running target/debug/deps/adder-941f01916ca4a642

running 1 test
test tests::it_works ... ok
test it_works ... ok

test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured

Expand All @@ -58,13 +75,15 @@ for the test we wrote, and another for documentation tests. We'll talk about
those later. For now, see this line:

```text
test tests::it_works ... ok
test it_works ... ok
```

Note the `it_works`. This comes from the name of our function:

```rust
# fn main() {
fn it_works() {
}
# }
```

Expand All @@ -77,8 +96,11 @@ test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured
So why does our do-nothing test pass? Any test which doesn't `panic!` passes,
and any test that does `panic!` fails. Let's make our test fail:

```rust
# fn main() {}
```rust,ignore
# // The next line exists to trick play.rust-lang.org into running our code as a
# // test:
# // fn main
#
#[test]
fn it_works() {
assert!(false);
Expand All @@ -92,19 +114,21 @@ run our tests again:
```bash
$ cargo test
Compiling adder v0.1.0 (file:///home/you/projects/adder)
Running target/debug/deps/adder-91b3e234d4ed382a
Finished debug [unoptimized + debuginfo] target(s) in 0.17 secs
Running target/debug/deps/adder-941f01916ca4a642

running 1 test
test tests::it_works ... FAILED
test it_works ... FAILED

failures:

---- test::it_works stdout ----
thread 'tests::it_works' panicked at 'assertion failed: false', src/lib.rs:5
---- it_works stdout ----
thread 'it_works' panicked at 'assertion failed: false', src/lib.rs:5
note: Run with `RUST_BACKTRACE=1` for a backtrace.


failures:
tests::it_works
it_works

test result: FAILED. 0 passed; 1 failed; 0 ignored; 0 measured

Expand All @@ -114,7 +138,7 @@ error: test failed
Rust indicates that our test failed:

```text
test tests::it_works ... FAILED
test it_works ... FAILED
```

And that's reflected in the summary line:
Expand Down Expand Up @@ -147,8 +171,11 @@ This is useful if you want to integrate `cargo test` into other tooling.

We can invert our test's failure with another attribute: `should_panic`:

```rust
# fn main() {}
```rust,ignore
# // The next line exists to trick play.rust-lang.org into running our code as a
# // test:
# // fn main
#
#[test]
#[should_panic]
fn it_works() {
Expand All @@ -161,10 +188,11 @@ This test will now succeed if we `panic!` and fail if we complete. Let's try it:
```bash
$ cargo test
Compiling adder v0.1.0 (file:///home/you/projects/adder)
Running target/debug/deps/adder-91b3e234d4ed382a
Finished debug [unoptimized + debuginfo] target(s) in 0.17 secs
Running target/debug/deps/adder-941f01916ca4a642

running 1 test
test tests::it_works ... ok
test it_works ... ok

test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured

Expand All @@ -178,8 +206,11 @@ test result: ok. 0 passed; 0 failed; 0 ignored; 0 measured
Rust provides another macro, `assert_eq!`, that compares two arguments for
equality:

```rust
# fn main() {}
```rust,ignore
# // The next line exists to trick play.rust-lang.org into running our code as a
# // test:
# // fn main
#
#[test]
#[should_panic]
fn it_works() {
Expand All @@ -193,10 +224,11 @@ passes:
```bash
$ cargo test
Compiling adder v0.1.0 (file:///home/you/projects/adder)
Running target/debug/deps/adder-91b3e234d4ed382a
Finished debug [unoptimized + debuginfo] target(s) in 0.21 secs
Running target/debug/deps/adder-941f01916ca4a642

running 1 test
test tests::it_works ... ok
test it_works ... ok

test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured

Expand All @@ -213,8 +245,11 @@ parameter can be added to the `should_panic` attribute. The test harness will
make sure that the failure message contains the provided text. A safer version
of the example above would be:

```rust
# fn main() {}
```rust,ignore
# // The next line exists to trick play.rust-lang.org into running our code as a
# // test:
# // fn main
#
#[test]
#[should_panic(expected = "assertion failed")]
fn it_works() {
Expand All @@ -225,7 +260,10 @@ fn it_works() {
That's all there is to the basics! Let's write one 'real' test:

```rust,ignore
# fn main() {}
# // The next line exists to trick play.rust-lang.org into running our code as a
# // test:
# // fn main
#
pub fn add_two(a: i32) -> i32 {
a + 2
}
Expand All @@ -244,8 +282,15 @@ some known arguments and compare it to the expected output.
Sometimes a few specific tests can be very time-consuming to execute. These
can be disabled by default by using the `ignore` attribute:

```rust
# fn main() {}
```rust,ignore
# // The next line exists to trick play.rust-lang.org into running our code as a
# // test:
# // fn main
#
pub fn add_two(a: i32) -> i32 {
a + 2
}
#[test]
fn it_works() {
assert_eq!(4, add_two(2));
Expand All @@ -264,7 +309,8 @@ not:
```bash
$ cargo test
Compiling adder v0.1.0 (file:///home/you/projects/adder)
Running target/debug/deps/adder-91b3e234d4ed382a
Finished debug [unoptimized + debuginfo] target(s) in 0.20 secs
Running target/debug/deps/adder-941f01916ca4a642

running 2 tests
test expensive_test ... ignored
Expand All @@ -283,7 +329,8 @@ The expensive tests can be run explicitly using `cargo test -- --ignored`:

```bash
$ cargo test -- --ignored
Running target/debug/deps/adder-91b3e234d4ed382a
Finished debug [unoptimized + debuginfo] target(s) in 0.0 secs
Running target/debug/deps/adder-941f01916ca4a642

running 1 test
test expensive_test ... ok
Expand All @@ -310,7 +357,10 @@ was missing from our last example. Let's explain what this does.
The idiomatic way of writing our example looks like this:

```rust,ignore
# fn main() {}
# // The next line exists to trick play.rust-lang.org into running our code as a
# // test:
# // fn main
#
pub fn add_two(a: i32) -> i32 {
a + 2
}
Expand Down Expand Up @@ -339,7 +389,10 @@ a large module, and so this is a common use of globs. Let's change our
`src/lib.rs` to make use of it:

```rust,ignore
# fn main() {}
# // The next line exists to trick play.rust-lang.org into running our code as a
# // test:
# // fn main
#
pub fn add_two(a: i32) -> i32 {
a + 2
}
Expand Down Expand Up @@ -389,9 +442,14 @@ To write an integration test, let's make a `tests` directory and
put a `tests/integration_test.rs` file inside with this as its contents:

```rust,ignore
# // The next line exists to trick play.rust-lang.org into running our code as a
# // test:
# // fn main
#
# // Sadly, this code will not work in play.rust-lang.org, because we have no
# // crate adder to import. You'll need to try this part on your own machine.
extern crate adder;
# fn main() {}
#[test]
fn it_works() {
assert_eq!(4, adder::add_two(2));
Expand Down Expand Up @@ -452,7 +510,10 @@ running examples in your documentation (**note:** this only works in library
crates, not binary crates). Here's a fleshed-out `src/lib.rs` with examples:

```rust,ignore
# fn main() {}
# // The next line exists to trick play.rust-lang.org into running our code as a
# // test:
# // fn main
#
//! The `adder` crate provides functions that add numbers to other numbers.
//!
//! # Examples
Expand Down

0 comments on commit a1cca91

Please sign in to comment.