[docs] Add synchronous test.each setup (#7150)

* Add changelog entry

* Add synchronous test troubeshooting

* Regenerate troubleshooting docs

* Reorder synchronous test docs

CHANGELOG.md

@@ -40,6 +40,7 @@
 
 ### Chore & Maintenance
 
+- `[docs]` Add synchronous test.each setup ([#7150](https://github.com/facebook/jest/pull/7150))
 - `[docs]` Add `this.extend` to the Custom Matchers API reference ([#7130](https://github.com/facebook/jest/pull/7130))
 - `[docs]` Fix default value for `coverageReporters` value in configuration docs ([#7126](https://github.com/facebook/jest/pull/7126))
 - `[docs]` Add link for jest-extended in expect docs ([#7078](https://github.com/facebook/jest/pull/7078))

docs/Troubleshooting.md

@@ -192,6 +192,23 @@ Jest takes advantage of new features added to Node 6. We recommend that you upgr
 
 Make sure you are not using the `babel-plugin-istanbul` plugin. Jest wraps Istanbul, and therefore also tells Istanbul what files to instrument with coverage collection. When using `babel-plugin-istanbul`, every file that is processed by Babel will have coverage collection code, hence it is not being ignored by `coveragePathIgnorePatterns`.
 
+## Defining Tests
+
+Tests must be defined synchronously for Jest to be able to collect your tests.
+
+As an example to show why this is the case, imagine we wrote a test like so:
+
+```js
+// Don't do this it will not work
+setTimeout(() => {
+  it('passes', () => expect(1).toBe(1));
+}, 0);
+```
+
+When Jest runs your test to collect the `test`s it will not find any because we have set the definition to happen asynchronously on the next tick of the event loop.
+
+_Note:_ This means when you are using `test.each` you cannot set the table asynchronously within a `beforeEach` / `beforeAll`.
+
 ## Still unresolved?
 
 See [Help](/help.html).

website/versioned_docs/version-23.6/Troubleshooting.md

@@ -193,6 +193,25 @@ Jest takes advantage of new features added to Node 6. We recommend that you upgr
 
 Make sure you are not using the `babel-plugin-istanbul` plugin. Jest wraps Istanbul, and therefore also tells Istanbul what files to instrument with coverage collection. When using `babel-plugin-istanbul`, every file that is processed by Babel will have coverage collection code, hence it is not being ignored by `coveragePathIgnorePatterns`.
 
+## Defining Tests
+
+Tests must be defined synchronously for Jest to be able to collect your tests.
+
+As an example to show why this is the case, imagine we wrote a test like so:
+
+```js
+// Don't do this it will not work
+setTimeout(() => {
+  it('passes', () => expect(1).toBe(1));
+}, 0);
+```
+
+When Jest runs your test to collect the `test`s it will not find any because we have set the definition to happen asynchronously on the next tick of the event loop.
+
+_Note:_ This means when you are using `test.each` you cannot set the table asynchronously within a `beforeEach` / `beforeAll`.
+
+When Jest runs your test to collect the `test`s it will not find any because we have set the definition to happen asynchronously on the next tick of the event loop.
+
 ## Still unresolved?
 
 See [Help](/help.html).