Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Test attributes deserve their own section #382

Merged
merged 3 commits into from
Sep 1, 2018
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
50 changes: 41 additions & 9 deletions src/attributes.md
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down Expand Up @@ -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`
<!-- * `!` -->
<!-- * Result<!, E> where E: Error` -->

> Note: The implementation of which return types are allowed is determined by
> the unstable [`Termination`] trait.

<!-- If the previous section needs updating (from "must take no arguments"
onwards, also update it in the crates-and-source-files.md file -->

> 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 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
`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]
Expand Down Expand Up @@ -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
[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
8 changes: 6 additions & 2 deletions src/crates-and-source-files.md
Original file line number Diff line number Diff line change
Expand Up @@ -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<(), E> where E: Error`
<!-- * `!` -->
* `Result<T, E> 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.

<!-- If the previous section needs updating (from "must take no arguments"
onwards, also update it in the attributes.md file, testing section -->

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.
Expand Down