Improve documentation of describe and test ordering.
#5217
Conversation
Explain that describe blocks are executed first (I've had annoying things where describes were being used to set up state instead of before* hooks), note that tests are run serially in the order they are discovered, and add a note about `test.concurrent`.
Codecov Report
@@ Coverage Diff @@
## master #5217 +/- ##
=========================================
- Coverage 60.91% 60.8% -0.12%
=========================================
Files 202 201 -1
Lines 6731 6707 -24
Branches 3 3
=========================================
- Hits 4100 4078 -22
+ Misses 2630 2628 -2
Partials 1 1
Continue to review full report at Codecov.
|
docs/SetupAndTeardown.md
Outdated
| @@ -147,6 +147,67 @@ describe('Scoped / Nested block', () => { | |||
| // 1 - afterAll | |||
| ``` | |||
|
|
|||
| ### Order of execution of describe and test blocks | |||
|
|
|||
| Jest executes all describe handlers in a test file *before* it executes any of the actual tests. This is another reason to do setup and teardown in `before*` and `after*` handlers rather in the describe blocks. Once the describe blocks are complete, by default jest runs all the tests serially in the order they were encountered in the collection phase, waiting for each to finish and be tidied up before moving on. | |||
There was a problem hiding this comment.
Can you capitalize Jest in the middle of the paragraph here? :)
docs/SetupAndTeardown.md
Outdated
| // test for describe inner 2 | ||
| ``` | ||
|
|
||
| ### Concurrent tests |
There was a problem hiding this comment.
Do you mind removing this section again? test.concurrent has some shortcomings and I would prefer not to document it as we may change it in a future release to be better supported.
Also fix typo!
|
Thanks @cpojer , I’ve made those changes. |
|
Awesome, thank you! |
|
This pull request has been automatically locked since there has not been any recent activity after it was closed. Please open a new issue for related bugs. |
Summary
There is no documentation of the order in which
describeandtesthandlers are run, nor any mention of any guarantees that jest makes about their synchronicity. I believe the intention is that tests within a single file are always run one after another unlesstest.concurrentis used, so I wanted to formalize that in the docs.Obviously if that's not true it would be good to see an explanation in the docs of why!
Test plan
Docs changes only and I've checked visually the markdown renders fine.