Skip to content

Commit a6f0074

Browse files
committed
pare down cargo parts
1 parent 3b35bc0 commit a6f0074

File tree

1 file changed

+25
-58
lines changed

1 file changed

+25
-58
lines changed

text/0000-custom-test-frameworks.md

Lines changed: 25 additions & 58 deletions
Original file line numberDiff line numberDiff line change
@@ -80,8 +80,8 @@ extern crate proc_macro;
8080
use proc_macro::{TestFrameworkContext, TokenStream};
8181

8282
// attributes() is optional
83-
#[test_framework(attributes(foo, bar))]
84-
pub fn mytest(context: &TestFrameworkContext) -> TokenStream {
83+
#[test_framework]
84+
pub fn test(context: &TestFrameworkContext) -> TokenStream {
8585
// ...
8686
}
8787
```
@@ -104,28 +104,22 @@ struct AnnotatedItem
104104

105105
`items` here contains an `AnnotatedItem` for every item in the
106106
target crate that has one of the attributes declared in `attributes`
107-
along with attributes sharing the name of the framework (`mytest`, here).
108-
109-
A test framework could declare that it reacts to multiple different
110-
attributes, in which case it would get all items with any of the
111-
listed attributes. These items be modules, functions, structs,
112-
statics, or whatever else the test framework wants to support. Note
113-
that the test framework function can only see all the annotated
114-
items, not modify them; modification would have to happen with regular
115-
procedural macros. The returned `TokenStream` must declare the `main()`
116-
that is to become the entry-point for the binary produced when this
117-
test framework is used.
107+
along with attributes sharing the name of the framework (`test`, here).
108+
109+
The annotated function _must_ be named "test" for a test framework and
110+
"bench" for a bench framework. We currently do not support
111+
any other kind of framework, but we may in the future.
118112

119113
So an example transformation would be to take something like this:
120114

121115
```rust
122-
#[quickcheck]
116+
#[test]
123117
fn foo(x: u8) {
124118
// ...
125119
}
126120

127121
mod bar {
128-
#[quickcheck]
122+
#[test]
129123
fn bar(x: String, y: u8) {
130124
// ...
131125
}
@@ -173,9 +167,7 @@ This section works like this:
173167

174168
```rust
175169
[testing.framework]
176-
folders = ["bench"]
177-
lib = true # true by default
178-
single-target = true # false by default
170+
kind = "test" # or bench
179171
```
180172

181173
`lib` specifies if the `--lib` mode exists for this framework by default,
@@ -193,59 +185,26 @@ under a new `[[testing.frameworks]]` section in their
193185
```toml
194186
[[testing.frameworks]]
195187
provider = { rust-fuzz = "1.0" }
196-
name = "fuzz" # optional, overrides the crate name
197-
folders = ["fuzz"] # optional, overrides `folders` on framework crate
198-
lib = false # optional, overrides `lib` on framework crate
199188
```
200189

201190
This pulls in the framework named "fuzz", which uses the
202191
implementation provided by the `rust-fuzz` crate. When run, it will be
203192
applied to all files in the `fuzz` directory. By default, the following
204-
frameworks are defined:
193+
framework is defined:
205194

206195
```toml
207196
[[testing.frameworks]]
208-
name = "test"
209197
provider = { test = "1.0" }
210-
folders = ["tests"]
211-
lib = true
212-
213-
[[testing.frameworks]]
214-
name = "bench"
215-
provider = { ?? = "1.0" }
216-
folders = ["benches"]
217-
lib = true # could also be split into two
218-
219-
[[testing.frameworks]]
220-
name = "example"
221-
provider = { ?? = "1.0" }
222-
folders = ["examples"]
223-
lib = false
224198
```
225199

226-
Whereas having two frameworks of the same name is an error, if you define
227-
a framework named "test", "bench", or "example", it will override the implicitly
228-
defined builtin frameworks.
200+
(We may define a default framework for bench in the future)
229201

230-
To invoke a particular framework, a user invokes `cargo test --framework
231-
<name>`. `cargo bench` is an alias for `cargo
232-
test --framework bench`. Any additional
233-
arguments are passed to the testing binary. By convention, the
234-
first position argument should allow filtering which targets
235-
(tests/benchmarks/etc.) are run.
202+
Declaring a test framework will replace the existing default one. You cannot declare
203+
more than one test or bench framework.
236204

237-
You can also add targets to a framework a la `[[test]]` and `[[example]]` via `[[testing.target]]`
238-
239-
```toml
240-
[[testing.target]]
241-
framework = fuzz
242-
path = "foo.rs"
243-
name = "foo"
244-
```
245-
246-
`[[test]]` and `[[example]]` in a crate's `Cargo.toml` are aliases of
247-
`[[testing.target]] framework = test` and `[[testing.target]] framework = example`
248-
respectively. This also goes for `[[bench]]` if we decide to keep that around.
205+
To invoke a particular framework, a user invokes `cargo test` or `cargo bench`. Any additional
206+
arguments are passed to the testing binary. By convention, the first position argument should allow
207+
filtering which targets (tests/benchmarks/etc.) are run.
249208

250209
## To be designed
251210

@@ -412,5 +371,13 @@ If this RFC lands and [RFC 2287] is rejected, we should probably try to stabiliz
412371
`test::black_box` in some form (maybe `mem::black_box` and `mem::clobber` as detailed
413372
in [this amendment]).
414373

374+
## Cargo integration
375+
376+
A previous iteration of this RFC allowed for test frameworks to declare new attributes
377+
and folders, so you would have `cargo test --kind quickcheck` look for tests in the
378+
`quickcheck/` folder that were annotated with `#[quickcheck]`.
379+
380+
This is no longer the case, but we may wish to add this again.
381+
415382
[RFC 2287]: https://github.com/rust-lang/rfcs/pull/2287
416383
[this amendment]: https://github.com/Manishearth/rfcs/pull/1

0 commit comments

Comments
 (0)