Description
🚀 Feature Proposal
(Possibly not a feature proposal, but also not a bug per se)
Having recently invested time in understanding Jest properly, one of the hardest concepts to understand was the term "test environment". This was especially hard in relation to these configuration options:
globalSetup: './globalSetup.js',
globalTeardown: './globalTeardown.js',
testEnvironment: './myTestEnvironment',
setupFiles: ['./setupFiles'],
setupFilesAfterEnv: ['./setupFilesAfterEnv'],
For reference, it is good to explain some terminology:
test file testA.test.js
test case test() # or it()
test suite describe() (I am not sure this is true. Reason is that the documentation seems to use the word "test file" and "test suite" interchangeably but actually always mean "test file". Never seen describe() referred specifically to "test suite" in the Jest documentation, so maybe it isn't a test suite?)
The problem I had with the documentation
If we take these terms, together with the "test environment" term and the above configuration options, I found some parts of the documentation ambiguous.
https://jestjs.io/docs/en/configuration#setupfiles-array
Since every test runs in its own environment,
Concern: It should probably say "every test file" instead of "every test". Refer to terminology above.
https://jestjs.io/docs/en/configuration#setupfilesafterenv-array
A list of paths to modules that run some code to configure or set up the testing framework before each test.
Concern: It should probably say "before each test file" instead of "before each test". Refer to terminology above.
https://jestjs.io/docs/en/configuration#globalsetup-string
This option allows the use of a custom global setup module which exports an async function that is triggered once before all test suites.
Concern: Not sure what to write here, but "before all test suites" can be interpreted in various ways as a test suite can be considered a describe() block.
Solution proposal
It would be good to go through both the Configuring Jest and Jest CLI Options documentation, and possible all other docs, to align this properly.
I also think that in general, having a completely specific section (possibly as a guide) describing what a test environment is and how it relates to the above specified configuration options would be great. The way I learnt was to setup a project and testing all these files with a bunch of console.log to actually see what happened.
Motivation
To make it easier for newcomers to understand Jest and how to extend its functionality.
Pitch
It belongs in the main Jest documentation as that is what users refer to when learning Jest.