Merge branch 'main' into gha_logs

CHANGELOG.md

@@ -6,10 +6,12 @@
 - `[jest-config, jest-worker]` Use `os.availableParallelism` if available to calculate number of workers to spawn ([#13738](https://github.com/facebook/jest/pull/13738))
 - `[@jest/globals, jest-mock]` Add `jest.replaceProperty()` that replaces property value ([#13496](https://github.com/facebook/jest/pull/13496))
 - `[jest-haste-map]` ignore Sapling vcs directories (`.sl/`) ([#13674](https://github.com/facebook/jest/pull/13674))
-- `[jest-resolve]` Support subpath imports ([#13705](https://github.com/facebook/jest/pull/13705), [#13723](https://github.com/facebook/jest/pull/13723))
+- `[jest-resolve]` Support subpath imports ([#13705](https://github.com/facebook/jest/pull/13705), [#13723](https://github.com/facebook/jest/pull/13723)), [#13777](https://github.com/facebook/jest/pull/13777))
 - `[jest-runtime]` Add `jest.isolateModulesAsync` for scoped module initialization of asynchronous functions ([#13680](https://github.com/facebook/jest/pull/13680))
+- `[jest-runtime]` Add `jest.isEnvironmentTornDown` function ([#13698](https://github.com/facebook/jest/pull/13698))
 - `[jest-test-result]` Added `skipped` and `focused` status to `FormattedTestResult` ([#13700](https://github.com/facebook/jest/pull/13700))
 - `[@jest/reporters]` New functionality for Github Actions Reporter: automatic log folding ([#13626](https://github.com/facebook/jest/pull/13626))
+- `[jest-transform]` Support for asynchronous `createTransformer` ([#13762](https://github.com/facebook/jest/pull/13762))
 
 ### Fixes
 
@@ -20,6 +22,7 @@
 - `[jest-runtime]` Support Wasm files that import JS resources ([#13608](https://github.com/facebook/jest/pull/13608))
 - `[jest-runtime]` Using the scriptTransformer cache in jest-runner ([#13735](https://github.com/facebook/jest/pull/13735))
 - `[jest-snapshot]` Make sure to import `babel` outside of the sandbox ([#13694](https://github.com/facebook/jest/pull/13694))
+- `[jest-transform]` Ensure the correct configuration is passed to preprocessors specified multiple times in the `transform` option ([#13770](https://github.com/facebook/jest/pull/13770))
 
 ### Chore & Maintenance
 

docs/Es6ClassMocks.md

@@ -263,7 +263,7 @@ This will throw **_TypeError: \_soundPlayer2.default is not a constructor_**, un
 
 ## Mocking a specific method of a class
 
-Lets say that you want to mock or spy the method `playSoundFile` within the class `SoundPlayer`. A simple example:
+Lets say that you want to mock or spy on the method `playSoundFile` within the class `SoundPlayer`. A simple example:
 
 ```javascript
 // your jest test file below
@@ -306,7 +306,7 @@ export default class SoundPlayer {
 }
 ```
 
-You can mock/spy them easily, here is an example:
+You can mock/spy on them easily, here is an example:
 
 ```javascript
 // your jest test file below

docs/GlobalAPI.md

@@ -387,7 +387,7 @@ describe.only.each`
   ${1} | ${1} | ${2}
   ${1} | ${2} | ${3}
   ${2} | ${1} | ${3}
-`('returns $expected when $a is added $b', ({a, b, expected}) => {
+`('returns $expected when $a is added to $b', ({a, b, expected}) => {
   test('passes', () => {
     expect(a + b).toBe(expected);
   });
@@ -456,7 +456,7 @@ describe.skip.each`
   ${1} | ${1} | ${2}
   ${1} | ${2} | ${3}
   ${2} | ${1} | ${3}
-`('returns $expected when $a is added $b', ({a, b, expected}) => {
+`('returns $expected when $a is added to $b', ({a, b, expected}) => {
   test('will not be run', () => {
     expect(a + b).toBe(expected); // will not be run
   });
@@ -525,7 +525,7 @@ test.concurrent('subtraction 2 numbers', async () => {
 
 :::tip
 
-Use [`maxConcurrency`](Configuration.md/#maxconcurrency-number) configuration option to prevent Jest from executing more than the specified amount of tests at the same time.
+Use the [`maxConcurrency`](Configuration.md/#maxconcurrency-number) configuration option to prevent Jest from executing more than the specified amount of tests at the same time.
 
 :::
 
@@ -584,7 +584,7 @@ test.concurrent.each`
   ${1} | ${1} | ${2}
   ${1} | ${2} | ${3}
   ${2} | ${1} | ${3}
-`('returns $expected when $a is added $b', async ({a, b, expected}) => {
+`('returns $expected when $a is added to $b', async ({a, b, expected}) => {
   expect(a + b).toBe(expected);
 });
 ```
@@ -621,7 +621,7 @@ test.concurrent.only.each`
   ${1} | ${1} | ${2}
   ${1} | ${2} | ${3}
   ${2} | ${1} | ${3}
-`('returns $expected when $a is added $b', async ({a, b, expected}) => {
+`('returns $expected when $a is added to $b', async ({a, b, expected}) => {
   expect(a + b).toBe(expected);
 });
 
@@ -662,7 +662,7 @@ test.concurrent.skip.each`
   ${1} | ${1} | ${2}
   ${1} | ${2} | ${3}
   ${2} | ${1} | ${3}
-`('returns $expected when $a is added $b', async ({a, b, expected}) => {
+`('returns $expected when $a is added to $b', async ({a, b, expected}) => {
   expect(a + b).toBe(expected); // will not be run
 });
 
@@ -740,7 +740,7 @@ test.each`
   ${1} | ${1} | ${2}
   ${1} | ${2} | ${3}
   ${2} | ${1} | ${3}
-`('returns $expected when $a is added $b', ({a, b, expected}) => {
+`('returns $expected when $a is added to $b', ({a, b, expected}) => {
   expect(a + b).toBe(expected);
 });
 ```
@@ -759,7 +759,7 @@ Use `test.failing` when you are writing a test and expecting it to fail. These t
 
 :::tip
 
-You can use this type of tests i.e. when writing code in a BDD way. In that case the tests will not show up as failing until they pass. Then you can just remove the `failing` modifier to make them pass.
+You can use this type of test i.e. when writing code in a BDD way. In that case the tests will not show up as failing until they pass. Then you can just remove the `failing` modifier to make them pass.
 
 It can also be a nice way to contribute failing tests to a project, even if you don't know how to fix the bug.
 
@@ -881,7 +881,7 @@ test.only.each`
   ${1} | ${1} | ${2}
   ${1} | ${2} | ${3}
   ${2} | ${1} | ${3}
-`('returns $expected when $a is added $b', ({a, b, expected}) => {
+`('returns $expected when $a is added to $b', ({a, b, expected}) => {
   expect(a + b).toBe(expected);
 });
 
@@ -944,7 +944,7 @@ test.skip.each`
   ${1} | ${1} | ${2}
   ${1} | ${2} | ${3}
   ${2} | ${1} | ${3}
-`('returns $expected when $a is added $b', ({a, b, expected}) => {
+`('returns $expected when $a is added to $b', ({a, b, expected}) => {
   expect(a + b).toBe(expected); // will not be run
 });
 
@@ -967,7 +967,7 @@ test.todo('add should be associative');
 
 :::tip
 
-`test.todo` will throw an error, if you will pass it a test callback function. Use [`test.skip`](#testskipname-fn) instead, if you already implemented the test, but do not want it to run.
+`test.todo` will throw an error if you pass it a test callback function. Use [`test.skip`](#testskipname-fn) instead, if you already implemented the test, but do not want it to run.
 
 :::
 

docs/JestObjectAPI.md

@@ -344,7 +344,7 @@ Returns the `jest` object for chaining.
 
 :::tip
 
-Writing tests in TypeScript? Use [`jest.Mocked`](MockFunctionAPI.md/#jestmockedsource) utility type or [`jest.mocked()`](MockFunctionAPI.md/#jestmockedsource-options) helper method to have your mocked modules typed.
+Writing tests in TypeScript? Use the [`jest.Mocked`](MockFunctionAPI.md/#jestmockedsource) utility type or the [`jest.mocked()`](MockFunctionAPI.md/#jestmockedsource-options) helper method to have your mocked modules typed.
 
 :::
 
@@ -364,6 +364,12 @@ The most common use of this API is for specifying the module a given test intend
 
 Returns the `jest` object for chaining.
 
+### `jest.deepUnmock(moduleName)`
+
+Indicates that the module system should never return a mocked version of the specified module and its dependencies.
+
+Returns the `jest` object for chaining.
+
 ### `jest.doMock(moduleName, factory, options)`
 
 When using `babel-jest`, calls to `mock` will automatically be hoisted to the top of the code block. Use this method if you want to explicitly avoid this behavior.
@@ -600,7 +606,7 @@ console.log(returnsTrue()); // true;
 
 :::tip
 
-See [Mock Functions](MockFunctionAPI.md#jestfnimplementation) page for details on TypeScript usage.
+See the [Mock Functions](MockFunctionAPI.md#jestfnimplementation) page for details on TypeScript usage.
 
 :::
 
@@ -669,7 +675,7 @@ By default, `jest.spyOn` also calls the **spied** method. This is different beha
 
 :::tip
 
-Since `jest.spyOn` is a mock, you could restore the initial state calling [jest.restoreAllMocks](#jestrestoreallmocks) on [afterEach](GlobalAPI.md#aftereachfn-timeout) method.
+Since `jest.spyOn` is a mock, you could restore the initial state by calling [`jest.restoreAllMocks`](#jestrestoreallmocks) in the body of the callback passed to the [afterEach](GlobalAPI.md#aftereachfn-timeout) hook.
 
 :::
 
@@ -747,7 +753,7 @@ afterEach(() => {
 
 test('plays video', () => {
   const spy = jest.spyOn(video, 'play', 'get'); // we pass 'get'
-  const isPlaying = video.play;
+  const isPlaying = video.play();
 
   expect(spy).toHaveBeenCalled();
   expect(isPlaying).toBe(true);
@@ -989,23 +995,9 @@ Use the [`--showSeed`](CLI.md#--showseed) flag to print the seed in the test rep
 
 :::
 
-### `jest.setTimeout(timeout)`
-
-Set the default timeout interval (in milliseconds) for all tests and before/after hooks in the test file. This only affects the test file from which this function is called. The default timeout interval is 5 seconds if this method is not called.
-
-Example:
-
-```js
-jest.setTimeout(1000); // 1 second
-```
-
-:::tip
+### `jest.isEnvironmentTornDown()`
 
-To set timeout intervals on different tests in the same file, use the [`timeout` option on each individual test](GlobalAPI.md#testname-fn-timeout).
-
-If you want to set the timeout for all test files, use [`testTimeout`](Configuration.md#testtimeout-number) configuration option.
-
-:::
+Returns `true` if test environment has been torn down.
 
 ### `jest.retryTimes(numRetries, options)`
 
@@ -1030,3 +1022,21 @@ test('will fail', () => {
 ```
 
 Returns the `jest` object for chaining.
+
+### `jest.setTimeout(timeout)`
+
+Set the default timeout interval (in milliseconds) for all tests and before/after hooks in the test file. This only affects the test file from which this function is called. The default timeout interval is 5 seconds if this method is not called.
+
+Example:
+
+```js
+jest.setTimeout(1000); // 1 second
+```
+
+:::tip
+
+To set timeout intervals on different tests in the same file, use the [`timeout` option on each individual test](GlobalAPI.md#testname-fn-timeout).
+
+If you want to set the timeout for all test files, use [`testTimeout`](Configuration.md#testtimeout-number) configuration option.
+
+:::

docs/MockFunctionAPI.md

@@ -163,6 +163,8 @@ mockFn(3); // 39
 ```
 
 ```ts tab
+import {jest} from '@jest/globals';
+
 const mockFn = jest.fn((scalar: number) => 42 + scalar);
 
 mockFn(0); // 42
@@ -207,12 +209,13 @@ export class SomeClass {
 ```
 
 ```ts title="SomeClass.test.ts"
+import {jest} from '@jest/globals';
 import {SomeClass} from './SomeClass';
 
 jest.mock('./SomeClass'); // this happens automatically with automocking
 
 const mockMethod = jest.fn<(a: string, b: string) => void>();
-SomeClass.mockImplementation(() => {
+jest.mocked(SomeClass).mockImplementation(() => {
   return {
     method: mockMethod,
   };
@@ -239,6 +242,8 @@ mockFn((err, val) => console.log(val)); // false
 ```
 
 ```ts tab
+import {jest} from '@jest/globals';
+
 const mockFn = jest
   .fn<(cb: (a: null, b: boolean) => void) => void>()
   .mockImplementationOnce(cb => cb(null, true))
@@ -296,6 +301,12 @@ jest.fn(function () {
 
 ### `mockFn.mockReturnValue(value)`
 
+Shorthand for:
+
+```js
+jest.fn().mockImplementation(() => value);
+```
+
 Accepts a value that will be returned whenever the mock function is called.
 
 ```js tab
@@ -309,6 +320,8 @@ mock(); // 43
 ```
 
 ```ts tab
+import {jest} from '@jest/globals';
+
 const mock = jest.fn<() => number>();
 
 mock.mockReturnValue(42);
@@ -320,6 +333,12 @@ mock(); // 43
 
 ### `mockFn.mockReturnValueOnce(value)`
 
+Shorthand for:
+
+```js
+jest.fn().mockImplementationOnce(() => value);
+```
+
 Accepts a value that will be returned for one call to the mock function. Can be chained so that successive calls to the mock function return different values. When there are no more `mockReturnValueOnce` values to use, calls will return a value specified by `mockReturnValue`.
 
 ```js tab
@@ -336,6 +355,8 @@ mockFn(); // 'default'
 ```
 
 ```ts tab
+import {jest} from '@jest/globals';
+
 const mockFn = jest
   .fn<() => string>()
   .mockReturnValue('default')
@@ -367,6 +388,8 @@ test('async test', async () => {
 ```
 
 ```ts tab
+import {jest, test} from '@jest/globals';
+
 test('async test', async () => {
   const asyncMock = jest.fn<() => Promise<number>>().mockResolvedValue(43);
 
@@ -400,6 +423,8 @@ test('async test', async () => {
 ```
 
 ```ts tab
+import {jest, test} from '@jest/globals';
+
 test('async test', async () => {
   const asyncMock = jest
     .fn<() => Promise<string>>()
@@ -435,6 +460,8 @@ test('async test', async () => {
 ```
 
 ```ts tab
+import {jest, test} from '@jest/globals';
+
 test('async test', async () => {
   const asyncMock = jest
     .fn<() => Promise<never>>()
@@ -467,6 +494,8 @@ test('async test', async () => {
 ```
 
 ```ts tab
+import {jest, test} from '@jest/globals';
+
 test('async test', async () => {
   const asyncMock = jest
     .fn<() => Promise<string>>()