Update testing.md to reflect changes to cargo new by trotter · Pull Request #37368 · rust-lang/rust

trotter · 2016-10-23T22:15:23Z

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.

rust-highfive · 2016-10-23T22:15:30Z

Thanks for the pull request, and welcome! The Rust team is excited to review your changes, and you should hear from @steveklabnik (or someone else) soon.

If any changes to this PR are deemed necessary, please add them as extra commits. This ensures that the reviewer can see what has changed since they last reviewed the code. Due to the way GitHub handles out-of-date commits, this should also make it reasonably obvious what issues have or haven't been addressed. Large or tricky changes may require several passes of review and changes.

Please see the contribution instructions for more information.

steveklabnik · 2016-10-23T23:24:25Z

I recently confronted this for the new book's testing chapter: rust-lang/book#288

maybe a similar approach would be good? I think I did what you did, but it's late and I'm tired; will re-read this PR tomorrow.

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.

👍 IIRC this was due to a limitation of long-ago Rust.

ollie27 · 2016-10-24T04:04:17Z

The # fn main() {} is to stop rustdoc from surrounding all of the code in a fn main block. See #31249. Removing it will generate links like this which still doesn't work. One (still hacky) solution would be to change it to somthing like # // fn main which will generate links like this instead.

steveklabnik · 2016-10-24T20:36:39Z

Ah, interesting.

@rust-lang/docs what do you think we should do here?

trotter · 2016-10-24T20:57:03Z

Ahh cool. I didn't realize there was a new book underway. I'm happy to take a look at that and use it as an example for making the existing docs reflect the current state of cargo new.

Once we have clarity on what to do around # fn main() {}, I'm happy to go implement 😄

bors · 2016-11-02T06:59:43Z

☔ The latest upstream changes (presumably #37514) made this pull request unmergeable. Please resolve the merge conflicts.

GuillaumeGomez · 2016-11-02T10:47:24Z

GuillaumeGomez · 2016-11-02T10:48:25Z

@steveklabnik: I like these changes so 👍 for me.

steveklabnik · 2016-11-03T10:47:17Z

@trotter I would like to merge this, can you rebase and fix that spacing issue @GuillaumeGomez pointed out?

`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.

trotter · 2016-11-08T15:30:19Z

@steveklabnik Updated, but I want ensure that I didn't muck things up with the removal of # fn main() {} before you merge.

steveklabnik · 2016-11-08T18:54:07Z

 and any test that does `panic!` fails. Let's make our test fail:

 ```rust
-# fn main() {}


so, testing this, i still get a link like
https://play.rust-lang.org/?code=fn%20main()%20%7B%7D%0A%23%5Btest%5D%0Afn%20it_works()%20%7B%0A%7D%0A
which has the main, not wrapping the example.

steveklabnik · 2016-11-08T18:55:00Z

@ollie27 i'm not seeing the behavior you're talking about, am i missing something?

ollie27 · 2016-11-08T20:43:42Z

# fnmain(){}#[test]fnit_works(){}

produces: https://play.rust-lang.org/?code=fn%20main()%20%7B%7D%0A%23%5Btest%5D%0Afn%20it_works()%20%7B%7D%0A

#[test]fnit_works(){}

produces: https://play.rust-lang.org/?code=fn%20main()%20%7B%0A%23%5Btest%5D%0Afn%20it_works()%20%7B%7D%0A%7D

# // please don't add fn main#[test]fnit_works(){}

produces: https://play.rust-lang.org/?code=%2F%2F%20please%20don%27t%20add%20fn%20main%0A%23%5Btest%5D%0Afn%20it_works()%20%7B%7D%0A

Only the third one shows the "Test ▶" button in the playground. Just removing # fn main() {} causes the whole thing to be surrounded in a fn main block like the second example.

steveklabnik · 2016-11-08T20:53:12Z

Oh, the isuse is the test button not being valid.

@trotter can you take away the # main() stuff?

trotter · 2016-11-09T02:39:33Z

@steveklabnik Yep! That's what I'm planning on getting fixed before saying we're done 😄

Without these changes, play.rust-lang.org (as of today) would wrap our examples in `fn main() {}`. This prevents the user from being able to easily run the tests.

@steveklabnik

The narrative flows better if we follow what @steveklabnik is doing in rust-lang/book#288. Therefore, I completely copied it.

I had used `/tmp/adder` for my previous commits. Flipped over to `/home/you/projects/adder` for consistency with other parts of testing.md

trotter · 2016-11-10T16:00:05Z

@steveklabnik This should be good to merge now. I've fixed the examples such that play.rust-lang.org will correctly run the code as tests. I also removed my earlier additions of mod tests in favor of the approach you took in rust-lang/book#288. Let me know if anything else needs changing.

GuillaumeGomez · 2016-11-10T16:50:43Z

Well, still remain a good big squash. :p

steveklabnik · 2016-11-10T17:46:27Z

Whoah, it just looks for fn main() and not something syntactically valid? interesting...

trotter · 2016-11-10T18:43:40Z

Fun. I had been running make docs, but apparently missed these tests that are now failing. I'll investigate tonight most likely.

trotter · 2016-11-10T19:09:00Z

I went ahead and took a quick look. It appears that the doc tests are attempting to run the code and are failing because it has no main function. I see two quick ways to making it happy:

remove the comments from # // fn main and turn it into # fn main() {}. I don't like this though, as it results in not having the 'test' button in play.rust-lang.org.
add ,ignore to the markdown language indicator, which will cause the test runner to ignore these ones. This seems good, as it results in things displaying happily to person reading the documentation and the tests pass. It also seems bad though, in that this code isn't getting exercised by the test runner. This means that any typos that show up later will only be found by sad users telling us that the code didn't run when they ran it on play.rust-lang.org.

My preference is to go with number 2 for now, but I'd also love to know if anyone has thoughts on how to get make check-docs to run these code examples without having an fn main() {} around the whole thing.

steveklabnik · 2016-11-10T21:55:50Z

I am also leaning towards ignore. @rust-lang/docs ?

While the commit message on this one sounds terrible, it's really not so bad. The issue is that our test runner _expects_ a `fn main() {}` in code blocks that it'll test, but this code really shouldn't have them. If it did, then clicking the "play" link in the docs would result in play.rust-lang.org not treating this code as a test example to be run.

trotter · 2016-11-11T06:01:49Z

@steveklabnik OK, I pushed up the changes with ignore. Assuming @rust-lang/docs is cool with it, this should be good to go.

GuillaumeGomez · 2016-11-11T11:17:36Z

Considering the current situation, I think it's ok. Thanks for all your work here @trotter!

steveklabnik · 2016-11-11T16:46:09Z

@bors: r+ rollup

Yup, let's merge. If anyone else has an issue, please let me know 😄

bors · 2016-11-11T16:46:11Z

📌 Commit 2a832a0 has been approved by steveklabnik

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.

Rollup of 30 pull requests - Successful merges: #37190, #37368, #37481, #37503, #37527, #37535, #37551, #37584, #37600, #37613, #37615, #37659, #37662, #37669, #37682, #37688, #37690, #37692, #37693, #37694, #37695, #37696, #37698, #37699, #37705, #37708, #37709, #37716, #37724, #37727 - Failed merges: #37640, #37689, #37717

rust-highfive assigned steveklabnik Oct 23, 2016

GuillaumeGomez requested changes Nov 2, 2016
View reviewed changes

Comment threadsrc/doc/book/testing.md Outdated
GuillaumeGomezNov 2, 2016
Copy link
Copy Markdown
Member
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
bad indent

trotter force-pushed the patch-1 branch from 833beca to b1d0c5bCompare November 8, 2016 15:05

steveklabnik reviewed Nov 8, 2016
View reviewed changes

trotter added 4 commits November 10, 2016 07:30

Instruct play.rust-lang.org to treat code as tests
d9c60ca
Without these changes, play.rust-lang.org (as of today) would wrap our examples in `fn main() {}`. This prevents the user from being able to easily run the tests.

Remove mod tests from earlier sections
35903bb
The narrative flows better if we follow what @steveklabnik is doing in rust-lang/book#288. Therefore, I completely copied it.

Change project path for consistency
dd92809
I had used `/tmp/adder` for my previous commits. Flipped over to `/home/you/projects/adder` for consistency with other parts of testing.md

Remove extraneous word
4cf7644

alexcrichton added the A-docs Area: Documentation for any part of the project, including the compiler, standard library, and tools label Nov 10, 2016

GuillaumeGomez approved these changes Nov 11, 2016
View reviewed changes

eddyb mentioned this pull request Nov 11, 2016
Rollup of 29 pull requests #37726
Closed

eddyb mentioned this pull request Nov 12, 2016
Rollup of 30 pull requests #37730
Merged

bors merged commit 2a832a0 into rust-lang:masterNov 12, 2016

Uh oh!

Uh oh!

Conversation

trotter commented Oct 23, 2016

Uh oh!

rust-highfive commented Oct 23, 2016

Uh oh!

steveklabnik commented Oct 23, 2016

Uh oh!

ollie27 commented Oct 24, 2016

Uh oh!

steveklabnik commented Oct 24, 2016

Uh oh!

trotter commented Oct 24, 2016

Uh oh!

bors commented Nov 2, 2016

Uh oh!

GuillaumeGomezNov 2, 2016

Choose a reason for hiding this comment

Uh oh!

GuillaumeGomez commented Nov 2, 2016

Uh oh!

steveklabnik commented Nov 3, 2016

Uh oh!

trotter commented Nov 8, 2016

Uh oh!

steveklabnikNov 8, 2016

Choose a reason for hiding this comment

Uh oh!

steveklabnik commented Nov 8, 2016

Uh oh!

ollie27 commented Nov 8, 2016

Uh oh!

steveklabnik commented Nov 8, 2016

Uh oh!

trotter commented Nov 9, 2016

Uh oh!

trotter commented Nov 10, 2016

Uh oh!

GuillaumeGomez commented Nov 10, 2016

Uh oh!

steveklabnik commented Nov 10, 2016

Uh oh!

trotter commented Nov 10, 2016

Uh oh!

trotter commented Nov 10, 2016

Uh oh!

steveklabnik commented Nov 10, 2016• edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

trotter commented Nov 11, 2016

Uh oh!

GuillaumeGomez commented Nov 11, 2016

Uh oh!

steveklabnik commented Nov 11, 2016

Uh oh!

bors commented Nov 11, 2016

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

7 participants

steveklabnik commented Nov 10, 2016•
edited
Loading