From 381201f759347c60565ce52a63beda88de780102 Mon Sep 17 00:00:00 2001 From: Havvy Date: Tue, 31 Jul 2018 22:44:46 -0700 Subject: [PATCH 1/3] Test attributes deserve their own section --- src/attributes.md | 50 ++++++++++++++++++++++++++++------ src/crates-and-source-files.md | 8 ++++-- 2 files changed, 47 insertions(+), 11 deletions(-) diff --git a/src/attributes.md b/src/attributes.md index 3cd103496..587eb0861 100644 --- a/src/attributes.md +++ b/src/attributes.md @@ -119,14 +119,6 @@ names have meaning. bar;` is equivalent to `mod bar { /* contents of foo.rs */ }`. The path is taken relative to the directory that the current module is in. -## Function-only attributes - -- `test` - indicates that this function is a test function, to only be compiled - in case of `--test`. - - `ignore` - indicates that this test function is disabled. -- `should_panic` - indicates that this test function should panic, inverting the - success condition. - ## FFI attributes On an `extern` block, the following attributes are interpreted: @@ -228,6 +220,42 @@ are transformed into `doc` attributes. See [The Rustdoc Book] for reference material on this attribute. +### Testing + +The compiler comes with a default test framework. It works by attributing +functions with the `test` attribute. These functions are only compiled when +compiling with the test harness. Like [main], functions annotated with this +attribute must take no arguments, must not declare any +[trait or lifetime bounds], must not have any [where clauses], and its return +type must be one of the following: + +* `()` + +* `Result<(), E> where E: Error` + + +> Note: The implementation of which return types are allowed is determined by +> the unstable [`Termination`] trait. + + + +> Note: The test harness is ran by passing the `--test` argument to `rustc` or +> using `cargo test`. + +Tests that return `()` pass as long as they terminate do not panic. Tests that +return a `Result` pass as long as they return `Ok(())`. Tests that do not +terminate neither pass nor fail. + +A function annotated with the `test` attribute can also be annotated with the +`ignore` attribute. The *`ignore` attribute* tells the test harness to not +execute that function as a test. It will still only be compiled when compiling +with the test harness. + +A function annotated with the `test` attribute that returns `()` can also be +annotated with the `should_panic` attribute. The *`should_panic` attribute* +makes the test only pass if it actually panics. + ### Conditional compilation The `cfg` and `cfg_attr` attributes control conditional compilation of [items] @@ -499,4 +527,8 @@ You can implement `derive` for your own traits through [procedural macros]. [external blocks]: items/external-blocks.html [items]: items.html [conditional compilation]: conditional-compilation.html -[trait]: items/traits.html \ No newline at end of file +[trait]: items/traits.html +[main]: crates-and-source-files.html +[`Termination`]: ../std/process/trait.Termination.html +[where clause]: items/where-clauses.html +[trait or lifetime bounds]: trait-bounds.html diff --git a/src/crates-and-source-files.md b/src/crates-and-source-files.md index beffaba3c..7a51dbfb3 100644 --- a/src/crates-and-source-files.md +++ b/src/crates-and-source-files.md @@ -68,16 +68,20 @@ apply to the crate as a whole. A crate that contains a `main` [function] can be compiled to an executable. If a `main` function is present, it must take no arguments, must not declare any -[trait or lifetime bounds], must not have any [where clauses], and its return +[trait or lifetime bounds], must not have any [where clauses], and its return type must be one of the following: * `()` -* `Result where T: on this list, E: Error` +* `Result<(), E> where E: Error` + > Note: The implementation of which return types are allowed is determined by > the unstable [`Termination`] trait. + + The optional [_UTF8 byte order mark_] (UTF8BOM production) indicates that the file is encoded in UTF8. It can only occur at the beginning of the file and is ignored by the compiler. From 4cc9df004c0205d4f4cb42d729fbe4fd58123b4d Mon Sep 17 00:00:00 2001 From: "Havvy (Ryan Scheel)" Date: Sat, 11 Aug 2018 05:31:00 -0700 Subject: [PATCH 2/3] Fix formatting of return from main types list --- src/attributes.md | 2 +- src/crates-and-source-files.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/src/attributes.md b/src/attributes.md index 587eb0861..4d5ee4be7 100644 --- a/src/attributes.md +++ b/src/attributes.md @@ -230,8 +230,8 @@ attribute must take no arguments, must not declare any type must be one of the following: * `()` - * `Result<(), E> where E: Error` + > Note: The implementation of which return types are allowed is determined by diff --git a/src/crates-and-source-files.md b/src/crates-and-source-files.md index 7a51dbfb3..656ae574c 100644 --- a/src/crates-and-source-files.md +++ b/src/crates-and-source-files.md @@ -72,8 +72,8 @@ A crate that contains a `main` [function] can be compiled to an executable. If a type must be one of the following: * `()` - * `Result<(), E> where E: Error` + > Note: The implementation of which return types are allowed is determined by From f30100263048d72090a141798e0059530d2197e8 Mon Sep 17 00:00:00 2001 From: "Havvy (Ryan Scheel)" Date: Sat, 1 Sep 2018 12:31:48 -0700 Subject: [PATCH 3/3] Fix typo --- src/attributes.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/attributes.md b/src/attributes.md index 4d5ee4be7..274e78ba2 100644 --- a/src/attributes.md +++ b/src/attributes.md @@ -243,8 +243,8 @@ type must be one of the following: > Note: The test harness is ran by passing the `--test` argument to `rustc` or > using `cargo test`. -Tests that return `()` pass as long as they terminate do not panic. Tests that -return a `Result` pass as long as they return `Ok(())`. Tests that do not +Tests that return `()` pass as long as they terminate and do not panic. Tests +that return a `Result` pass as long as they return `Ok(())`. Tests that do not terminate neither pass nor fail. A function annotated with the `test` attribute can also be annotated with the