[doc] add note explaining when jest.setTimeout should be called

CHANGELOG.md

@@ -14,6 +14,10 @@
 - `[jest-cli]` Fix `testMatch` not working with negations ([#6648](https://github.com/facebook/jest/pull/6648))
 - `[jest-cli]` Don't report promises as open handles ([#6716](https://github.com/facebook/jest/pull/6716))
 
+### Chore & Maintenance
+
+- `[docs]` Add note explaining when `jest.setTimeout` should be called ([#6817](https://github.com/facebook/jest/pull/6817/files))
+
 ## 23.4.2
 
 ### Performance

docs/JestObjectAPI.md

@@ -396,6 +396,8 @@ Set the default timeout interval for tests and before/after hooks in millisecond
 
 _Note: The default timeout interval is 5 seconds if this method is not called._
 
+_Note: The method must be called after the test framework is installed in the environment and before the test runs. A good place to do this is in the `setupTestFrameworkScriptFile`._
+
 Example:
 
 ```js

website/versioned_docs/version-22.0/JestObjectAPI.md

@@ -284,6 +284,8 @@ Set the default timeout interval for tests and before/after hooks in millisecond
 
 _Note: The default timeout interval is 5 seconds if this method is not called._
 
+_Note: The method must be called after the test framework is installed in the environment and before the test runs. A good place to do this is in the `setupTestFrameworkScriptFile`._
+
 Example:
 
 ```js

website/versioned_docs/version-22.1/JestObjectAPI.md

@@ -282,6 +282,8 @@ Set the default timeout interval for tests and before/after hooks in millisecond
 
 _Note: The default timeout interval is 5 seconds if this method is not called._
 
+_Note: The method must be called after the test framework is installed in the environment and before the test runs. A good place to do this is in the `setupTestFrameworkScriptFile`._
+
 Example:
 
 ```js

website/versioned_docs/version-22.2/JestObjectAPI.md

@@ -283,6 +283,8 @@ Set the default timeout interval for tests and before/after hooks in millisecond
 
 _Note: The default timeout interval is 5 seconds if this method is not called._
 
+_Note: The method must be called after the test framework is installed in the environment and before the test runs. A good place to do this is in the `setupTestFrameworkScriptFile`._
+
 Example:
 
 ```js

website/versioned_docs/version-22.3/JestObjectAPI.md

@@ -283,6 +283,8 @@ Set the default timeout interval for tests and before/after hooks in millisecond
 
 _Note: The default timeout interval is 5 seconds if this method is not called._
 
+_Note: The method must be called after the test framework is installed in the environment and before the test runs. A good place to do this is in the `setupTestFrameworkScriptFile`._
+
 Example:
 
 ```js

website/versioned_docs/version-22.4/JestObjectAPI.md

@@ -365,6 +365,8 @@ Set the default timeout interval for tests and before/after hooks in millisecond
 
 _Note: The default timeout interval is 5 seconds if this method is not called._
 
+_Note: The method must be called after the test framework is installed in the environment and before the test runs. A good place to do this is in the `setupTestFrameworkScriptFile`._
+
 Example:
 
 ```js

website/versioned_docs/version-23.0/JestObjectAPI.md

@@ -365,6 +365,8 @@ Set the default timeout interval for tests and before/after hooks in millisecond
 
 _Note: The default timeout interval is 5 seconds if this method is not called._
 
+_Note: The method must be called after the test framework is installed in the environment and before the test runs. A good place to do this is in the `setupTestFrameworkScriptFile`._
+
 Example:
 
 ```js

website/versioned_docs/version-23.1/JestObjectAPI.md

@@ -365,6 +365,8 @@ Set the default timeout interval for tests and before/after hooks in millisecond
 
 _Note: The default timeout interval is 5 seconds if this method is not called._
 
+_Note: The method must be called after the test framework is installed in the environment and before the test runs. A good place to do this is in the `setupTestFrameworkScriptFile`._
+
 Example:
 
 ```js

website/versioned_docs/version-23.2/JestObjectAPI.md

@@ -365,6 +365,8 @@ Set the default timeout interval for tests and before/after hooks in millisecond
 
 _Note: The default timeout interval is 5 seconds if this method is not called._
 
+_Note: The method must be called after the test framework is installed in the environment and before the test runs. A good place to do this is in the `setupTestFrameworkScriptFile`._
+
 Example:
 
 ```js

website/versioned_docs/version-23.3/JestObjectAPI.md

@@ -397,6 +397,8 @@ Set the default timeout interval for tests and before/after hooks in millisecond
 
 _Note: The default timeout interval is 5 seconds if this method is not called._
 
+_Note: The method must be called after the test framework is installed in the environment and before the test runs. A good place to do this is in the `setupTestFrameworkScriptFile`._
+
 Example:
 
 ```js