Skip to content

Commit b1d0c5b

Browse files
committed
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.
1 parent 38a959a commit b1d0c5b

File tree

1 file changed

+76
-50
lines changed

1 file changed

+76
-50
lines changed

src/doc/book/testing.md

+76-50
Original file line numberDiff line numberDiff line change
@@ -38,8 +38,9 @@ currently has no body. That's good enough to pass! We can run the tests with
3838

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

4445
running 1 test
4546
test tests::it_works ... ok
@@ -61,11 +62,11 @@ those later. For now, see this line:
6162
test tests::it_works ... ok
6263
```
6364

64-
Note the `it_works`. This comes from the name of our function:
65+
Note the `tests::it_works`. This comes from the name of our module and function:
6566

6667
```rust
6768
fn it_works() {
68-
# }
69+
}
6970
```
7071

7172
We also get a summary line:
@@ -78,10 +79,12 @@ So why does our do-nothing test pass? Any test which doesn't `panic!` passes,
7879
and any test that does `panic!` fails. Let's make our test fail:
7980

8081
```rust
81-
# fn main() {}
82-
#[test]
83-
fn it_works() {
84-
assert!(false);
82+
#[cfg(test)]
83+
mod tests {
84+
#[test]
85+
fn it_works() {
86+
assert!(false);
87+
}
8588
}
8689
```
8790

@@ -91,16 +94,18 @@ run our tests again:
9194

9295
```bash
9396
$ cargo test
94-
Compiling adder v0.1.0 (file:///home/you/projects/adder)
95-
Running target/debug/deps/adder-91b3e234d4ed382a
97+
Compiling adder v0.1.0 (file:///private/tmp/adder)
98+
Finished debug [unoptimized + debuginfo] target(s) in 0.17 secs
99+
Running target/debug/deps/adder-941f01916ca4a642
96100

97101
running 1 test
98102
test tests::it_works ... FAILED
99103

100104
failures:
101105

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

105110

106111
failures:
@@ -148,20 +153,24 @@ This is useful if you want to integrate `cargo test` into other tooling.
148153
We can invert our test's failure with another attribute: `should_panic`:
149154

150155
```rust
151-
# fn main() {}
152-
#[test]
153-
#[should_panic]
154-
fn it_works() {
155-
assert!(false);
156+
#[cfg(test)]
157+
mod tests {
158+
#[test]
159+
#[should_panic]
160+
fn it_works() {
161+
assert!(false);
162+
}
156163
}
164+
157165
```
158166

159167
This test will now succeed if we `panic!` and fail if we complete. Let's try it:
160168

161169
```bash
162170
$ cargo test
163-
Compiling adder v0.1.0 (file:///home/you/projects/adder)
164-
Running target/debug/deps/adder-91b3e234d4ed382a
171+
Compiling adder v0.1.0 (file:///private/tmp/adder)
172+
Finished debug [unoptimized + debuginfo] target(s) in 0.17 secs
173+
Running target/debug/deps/adder-941f01916ca4a642
165174

166175
running 1 test
167176
test tests::it_works ... ok
@@ -179,11 +188,13 @@ Rust provides another macro, `assert_eq!`, that compares two arguments for
179188
equality:
180189

181190
```rust
182-
# fn main() {}
183-
#[test]
184-
#[should_panic]
185-
fn it_works() {
186-
assert_eq!("Hello", "world");
191+
#[cfg(test)]
192+
mod tests {
193+
#[test]
194+
#[should_panic]
195+
fn it_works() {
196+
assert_eq!("Hello", "world");
197+
}
187198
}
188199
```
189200

@@ -192,8 +203,9 @@ passes:
192203

193204
```bash
194205
$ cargo test
195-
Compiling adder v0.1.0 (file:///home/you/projects/adder)
196-
Running target/debug/deps/adder-91b3e234d4ed382a
206+
Compiling adder v0.1.0 (file:///private/tmp/adder)
207+
Finished debug [unoptimized + debuginfo] target(s) in 0.21 secs
208+
Running target/debug/deps/adder-941f01916ca4a642
197209

198210
running 1 test
199211
test tests::it_works ... ok
@@ -214,25 +226,31 @@ make sure that the failure message contains the provided text. A safer version
214226
of the example above would be:
215227

216228
```rust
217-
# fn main() {}
218-
#[test]
219-
#[should_panic(expected = "assertion failed")]
220-
fn it_works() {
221-
assert_eq!("Hello", "world");
229+
#[cfg(test)]
230+
mod tests {
231+
#[test]
232+
#[should_panic(expected = "assertion failed")]
233+
fn it_works() {
234+
assert_eq!("Hello", "world");
235+
}
222236
}
223237
```
224238

225239
That's all there is to the basics! Let's write one 'real' test:
226240

227241
```rust,ignore
228-
# fn main() {}
229242
pub fn add_two(a: i32) -> i32 {
230243
a + 2
231244
}
232245
233-
#[test]
234-
fn it_works() {
235-
assert_eq!(4, add_two(2));
246+
#[cfg(test)]
247+
mod tests {
248+
use super::add_two;
249+
250+
#[test]
251+
fn it_works() {
252+
assert_eq!(4, add_two(2));
253+
}
236254
}
237255
```
238256

@@ -245,16 +263,24 @@ Sometimes a few specific tests can be very time-consuming to execute. These
245263
can be disabled by default by using the `ignore` attribute:
246264

247265
```rust
248-
# fn main() {}
249-
#[test]
250-
fn it_works() {
251-
assert_eq!(4, add_two(2));
266+
pub fn add_two(a: i32) -> i32 {
267+
a + 2
252268
}
253269

254-
#[test]
255-
#[ignore]
256-
fn expensive_test() {
257-
// code that takes an hour to run
270+
#[cfg(test)]
271+
mod tests {
272+
use super::add_two;
273+
274+
#[test]
275+
fn it_works() {
276+
assert_eq!(4, add_two(2));
277+
}
278+
279+
#[test]
280+
#[ignore]
281+
fn expensive_test() {
282+
// code that takes an hour to run
283+
}
258284
}
259285
```
260286

@@ -263,12 +289,13 @@ not:
263289

264290
```bash
265291
$ cargo test
266-
Compiling adder v0.1.0 (file:///home/you/projects/adder)
267-
Running target/debug/deps/adder-91b3e234d4ed382a
292+
Compiling adder v0.1.0 (file:///private/tmp/adder)
293+
Finished debug [unoptimized + debuginfo] target(s) in 0.20 secs
294+
Running target/debug/deps/adder-941f01916ca4a642
268295

269296
running 2 tests
270-
test expensive_test ... ignored
271-
test it_works ... ok
297+
test tests::expensive_test ... ignored
298+
test tests::it_works ... ok
272299

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

@@ -283,10 +310,11 @@ The expensive tests can be run explicitly using `cargo test -- --ignored`:
283310

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

288316
running 1 test
289-
test expensive_test ... ok
317+
test tests::expensive_test ... ok
290318

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

@@ -310,7 +338,6 @@ was missing from our last example. Let's explain what this does.
310338
The idiomatic way of writing our example looks like this:
311339

312340
```rust,ignore
313-
# fn main() {}
314341
pub fn add_two(a: i32) -> i32 {
315342
a + 2
316343
}
@@ -339,7 +366,6 @@ a large module, and so this is a common use of globs. Let's change our
339366
`src/lib.rs` to make use of it:
340367

341368
```rust,ignore
342-
# fn main() {}
343369
pub fn add_two(a: i32) -> i32 {
344370
a + 2
345371
}

0 commit comments

Comments
 (0)