From 5d623f8c70c0fbc5402e68a98bc4b3c550b2b8d0 Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Thu, 5 Jun 2025 08:37:13 -0700 Subject: [PATCH 01/10] Linkify attribute --- src/attributes/testing.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/attributes/testing.md b/src/attributes/testing.md index 93e26a80a..03de51da2 100644 --- a/src/attributes/testing.md +++ b/src/attributes/testing.md @@ -10,10 +10,10 @@ r[attributes.testing.test] ## The `test` attribute r[attributes.testing.test.intro] -The *`test` attribute* marks a function to be executed as a test. r[attributes.testing.test.enabled] These functions are only compiled when in test mode. +The *`test` [attribute][attributes]* marks a function to be executed as a test. r[attributes.testing.test.allowed-positions] Test functions must be free, monomorphic functions that take no arguments, and the return type must implement the [`Termination`] trait, for example: From b2d234ab16364889c5540431fa69f13b1315119d Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Thu, 5 Jun 2025 08:37:31 -0700 Subject: [PATCH 02/10] Add an example to the test intro --- src/attributes/testing.md | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/src/attributes/testing.md b/src/attributes/testing.md index 03de51da2..29b5ce412 100644 --- a/src/attributes/testing.md +++ b/src/attributes/testing.md @@ -15,6 +15,17 @@ r[attributes.testing.test.enabled] These functions are only compiled when in test mode. The *`test` [attribute][attributes]* marks a function to be executed as a test. +> [!EXAMPLE] +> ```rust +> # pub fn add(left: u64, right: u64) -> u64 { left + right } +> +> #[test] +> fn it_works() { +> let result = add(2, 2); +> assert_eq!(result, 4); +> } +> ``` + r[attributes.testing.test.allowed-positions] Test functions must be free, monomorphic functions that take no arguments, and the return type must implement the [`Termination`] trait, for example: From c867c235a5a7cdb2ebae2dabe0355d64cd56dfb0 Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Thu, 5 Jun 2025 08:38:02 -0700 Subject: [PATCH 03/10] Add attributes.testing.test.syntax --- src/attributes/testing.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/src/attributes/testing.md b/src/attributes/testing.md index 29b5ce412..4bd63b4d9 100644 --- a/src/attributes/testing.md +++ b/src/attributes/testing.md @@ -26,6 +26,9 @@ The *`test` [attribute][attributes]* marks a function to be executed as a test. > } > ``` +r[attributes.testing.test.syntax] +The `test` attribute uses the [MetaWord] syntax and thus does not take any inputs. + r[attributes.testing.test.allowed-positions] Test functions must be free, monomorphic functions that take no arguments, and the return type must implement the [`Termination`] trait, for example: From cdc938e2b4203e17e4fba58a2d02b2705c350653 Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Thu, 5 Jun 2025 08:39:24 -0700 Subject: [PATCH 04/10] Reword attributes.testing.test.allowed-positions This is just some rewording for some clarity. --- src/attributes/testing.md | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/src/attributes/testing.md b/src/attributes/testing.md index 4bd63b4d9..c513aa1b4 100644 --- a/src/attributes/testing.md +++ b/src/attributes/testing.md @@ -30,14 +30,14 @@ r[attributes.testing.test.syntax] The `test` attribute uses the [MetaWord] syntax and thus does not take any inputs. r[attributes.testing.test.allowed-positions] -Test functions must be free, monomorphic functions that take no arguments, and the return type must implement the [`Termination`] trait, for example: +The `test` attribute may only be applied to [free functions] that are monomorphic, that take no arguments, and the return type must implement the [`Termination`] trait. + +> [!NOTE] +> Some of types that implement the [`Termination`] trait include: +> * `()` +> * `Result where T: Termination, E: Debug` -* `()` -* `Result where T: Termination, E: Debug` -* `!` - > [!NOTE] > The test mode is enabled by passing the `--test` argument to `rustc` or using `cargo test`. @@ -116,3 +116,4 @@ fn mytest() { [`test` conditional compilation option]: ../conditional-compilation.md#test [attributes]: ../attributes.md [`ExitCode`]: std::process::ExitCode +[free functions]: ../glossary.md#free-item From 98baa62fb5964268830d69467ecdc42577602ddb Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Thu, 5 Jun 2025 08:40:12 -0700 Subject: [PATCH 05/10] Add attributes.testing.test.duplicates I don't really know what to say here, since rustc generates somewhat nonsense when there are duplicates. --- src/attributes/testing.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/src/attributes/testing.md b/src/attributes/testing.md index c513aa1b4..8402fc844 100644 --- a/src/attributes/testing.md +++ b/src/attributes/testing.md @@ -37,7 +37,13 @@ The `test` attribute may only be applied to [free functions] that are monomorphi > * `()` > * `Result where T: Termination, E: Debug` +r[attributes.testing.test.duplicates] +Only the first instance of `test` on an function is honored. Subsequent `test` attributes are ignored. +> [!NOTE] +> `rustc` currently warns on duplicate `test` attributes. + + > [!NOTE] > The test mode is enabled by passing the `--test` argument to `rustc` or using `cargo test`. From 84386479063bb23abf51d0e8eff101d21215f9f2 Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Thu, 5 Jun 2025 08:41:34 -0700 Subject: [PATCH 06/10] Move attributes.testing.test.enabled Moving to follow the attribute template. --- src/attributes/testing.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/attributes/testing.md b/src/attributes/testing.md index 8402fc844..3d5da8cc5 100644 --- a/src/attributes/testing.md +++ b/src/attributes/testing.md @@ -10,9 +10,6 @@ r[attributes.testing.test] ## The `test` attribute r[attributes.testing.test.intro] - -r[attributes.testing.test.enabled] -These functions are only compiled when in test mode. The *`test` [attribute][attributes]* marks a function to be executed as a test. > [!EXAMPLE] @@ -45,6 +42,9 @@ Only the first instance of `test` on an function is honored. Subsequent `test` a +r[attributes.testing.test.enabled] +These functions are only compiled when in test mode. + > [!NOTE] > The test mode is enabled by passing the `--test` argument to `rustc` or using `cargo test`. From df602be9cdf473fb5a8cc70ce2c97b767b36378b Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Thu, 5 Jun 2025 08:41:44 -0700 Subject: [PATCH 07/10] Move example into an example block --- src/attributes/testing.md | 23 ++++++++++++----------- 1 file changed, 12 insertions(+), 11 deletions(-) diff --git a/src/attributes/testing.md b/src/attributes/testing.md index 3d5da8cc5..8fe526254 100644 --- a/src/attributes/testing.md +++ b/src/attributes/testing.md @@ -56,17 +56,18 @@ In particular: * Tests that return `ExitCode::SUCCESS` pass, and tests that return `ExitCode::FAILURE` fail. * Tests that do not terminate neither pass nor fail. -```rust -# use std::io; -# fn setup_the_thing() -> io::Result { Ok(1) } -# fn do_the_thing(s: &i32) -> io::Result<()> { Ok(()) } -#[test] -fn test_the_thing() -> io::Result<()> { - let state = setup_the_thing()?; // expected to succeed - do_the_thing(&state)?; // expected to succeed - Ok(()) -} -``` +> [!EXAMPLE] +> ```rust +> # use std::io; +> # fn setup_the_thing() -> io::Result { Ok(1) } +> # fn do_the_thing(s: &i32) -> io::Result<()> { Ok(()) } +> #[test] +> fn test_the_thing() -> io::Result<()> { +> let state = setup_the_thing()?; // expected to succeed +> do_the_thing(&state)?; // expected to succeed +> Ok(()) +> } +> ``` r[attributes.testing.ignore] ## The `ignore` attribute From 7a56de6862bc2b678a032a3687c25f0ba1c3d821 Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Thu, 5 Jun 2025 09:08:31 -0700 Subject: [PATCH 08/10] Add attributes.testing.test.stdlib --- src/attributes/testing.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/src/attributes/testing.md b/src/attributes/testing.md index 8fe526254..d9213f50e 100644 --- a/src/attributes/testing.md +++ b/src/attributes/testing.md @@ -42,6 +42,9 @@ Only the first instance of `test` on an function is honored. Subsequent `test` a +r[attributes.testing.test.stdlib] +The `test` attribute is exported from the standard library prelude as [`std::prelude::v1::test`]. + r[attributes.testing.test.enabled] These functions are only compiled when in test mode. From 1563bab0ef999838084ec841b821790b03676a93 Mon Sep 17 00:00:00 2001 From: Travis Cross Date: Tue, 1 Jul 2025 22:19:39 +0000 Subject: [PATCH 09/10] Reword a rewording a bit When we have a list of the form, "something is this, something is that, and...", the last clause should follow the pattern. --- src/attributes/testing.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/attributes/testing.md b/src/attributes/testing.md index d9213f50e..2d861428b 100644 --- a/src/attributes/testing.md +++ b/src/attributes/testing.md @@ -27,7 +27,7 @@ r[attributes.testing.test.syntax] The `test` attribute uses the [MetaWord] syntax and thus does not take any inputs. r[attributes.testing.test.allowed-positions] -The `test` attribute may only be applied to [free functions] that are monomorphic, that take no arguments, and the return type must implement the [`Termination`] trait. +The `test` attribute may only be applied to [free functions] that are monomorphic, that take no arguments, and where the return type implements the [`Termination`] trait. > [!NOTE] > Some of types that implement the [`Termination`] trait include: From d8fb884bb9221354ffee829aca2d0158a5c9fa10 Mon Sep 17 00:00:00 2001 From: Travis Cross Date: Tue, 1 Jul 2025 22:44:12 +0000 Subject: [PATCH 10/10] Move bit about what's ignored to admonition It's a bit unclear whether we want to guarantee that duplicates are ignored. Let's move the description of that behavior into the admonition. --- src/attributes/testing.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/attributes/testing.md b/src/attributes/testing.md index 2d861428b..e6aae7981 100644 --- a/src/attributes/testing.md +++ b/src/attributes/testing.md @@ -35,10 +35,10 @@ The `test` attribute may only be applied to [free functions] that are monomorphi > * `Result where T: Termination, E: Debug` r[attributes.testing.test.duplicates] -Only the first instance of `test` on an function is honored. Subsequent `test` attributes are ignored. +Only the first instance of `test` on a function is honored. > [!NOTE] -> `rustc` currently warns on duplicate `test` attributes. +> Subsequent `test` attributes are currently ignored and `rustc` warns about these.