Merge commit '199f9811ae68b15879cbe18b7ef7ebd61eefcf23~' into 9505-je…

…st-resolve-async

.circleci/config.yml

@@ -19,26 +19,15 @@ jobs:
     parameters:
       node-version:
         type: string
-      partial:
-        type: boolean
-        default: false
     working_directory: ~/jest
     executor: node/default
     steps:
       - checkout
       - node/install:
           node-version: << parameters.node-version >>
       - node/install-packages: *install
-      - when:
-          condition: << parameters.partial >>
-          steps:
-            - run:
-                command: yarn test-ci-partial
-      - unless:
-          condition: << parameters.partial >>
-          steps:
-            - run:
-                command: yarn test-ci
+      - run:
+          command: yarn test-ci-partial
       - store_test_results:
           path: reports/junit
 
@@ -59,14 +48,9 @@ jobs:
 workflows:
   build-and-deploy:
     jobs:
-      - test-node:
-          matrix:
-            parameters:
-              node-version: ['lts/*']
       - test-node:
           name: test-node-partial-<< matrix.node-version >>
-          partial: true
           matrix:
             parameters:
-              node-version: ['12', '16', '17']
+              node-version: ['12', '14', '16', '17']
       - test-jest-jasmine

.codecov.yml

@@ -0,0 +1,13 @@
+codecov:
+  require_ci_to_pass: false
+
+comment: false
+
+coverage:
+  status:
+    patch:
+      default:
+        target: auto
+    project:
+      default:
+        target: auto

.eslintrc.js

@@ -17,6 +17,7 @@ module.exports = {
     node: true,
   },
   extends: [
+    'plugin:markdown/recommended',
     'plugin:import/errors',
     'plugin:eslint-comments/recommended',
     'plugin:prettier/recommended',
@@ -134,10 +135,12 @@ module.exports = {
 
     // to make it more suitable for running on code examples in docs/ folder
     {
-      files: ['*.md'],
+      files: ['**/*.md/**'],
       rules: {
+        '@typescript-eslint/no-unused-vars': 'off',
         'arrow-body-style': 'off',
         'consistent-return': 'off',
+        'import/export': 'off',
         'import/no-extraneous-dependencies': 'off',
         'import/no-unresolved': 'off',
         'no-console': 'off',
@@ -149,7 +152,7 @@ module.exports = {
     },
     // snapshots in examples plus inline snapshots need to keep backtick
     {
-      files: ['*.md', 'e2e/custom-inline-snapshot-matchers/__tests__/*'],
+      files: ['**/*.md/**', 'e2e/custom-inline-snapshot-matchers/__tests__/*'],
       rules: {
         quotes: [
           'error',
@@ -242,7 +245,7 @@ module.exports = {
       },
     },
     {
-      files: ['**/__typetests__/**', '*.md'],
+      files: ['**/__typetests__/**', '**/*.md/**'],
       rules: {
         'jest/no-focused-tests': 'off',
         'jest/no-identical-title': 'off',
@@ -284,7 +287,7 @@ module.exports = {
   parserOptions: {
     sourceType: 'module',
   },
-  plugins: ['markdown', 'import', 'jest'],
+  plugins: ['import', 'jest'],
   rules: {
     'accessor-pairs': ['warn', {setWithoutGet: true}],
     'block-scoped-var': 'off',

.gitattributes

@@ -0,0 +1 @@
+* text=auto

.github/workflows/nodejs.yml

@@ -133,3 +133,34 @@ jobs:
         uses: SimenB/github-actions-cpu-cores@v1
       - name: run tests using jest-jasmine
         run: yarn jest-jasmine-ci --max-workers ${{ steps.cpu-cores.outputs.count }}
+
+  test-coverage:
+    name: Node LTS on Ubuntu with coverage
+    runs-on: ubuntu-latest
+    needs: prepare-yarn-cache
+
+    steps:
+      - uses: actions/checkout@v2
+      - name: Use Node.js LTS
+        uses: actions/setup-node@v2
+        with:
+          node-version: lts/*
+          cache: yarn
+      - name: install
+        run: yarn --immutable
+      - name: build
+        run: yarn build:js
+      - name: Get number of CPU cores
+        id: cpu-cores
+        uses: SimenB/github-actions-cpu-cores@v1
+      - name: run tests with coverage
+        run: |
+          yarn jest-coverage --color --config jest.config.ci.js --max-workers ${{ steps.cpu-cores.outputs.count }}
+          yarn test-leak
+      - name: map coverage
+        run: node ./scripts/mapCoverage.js
+        if: always()
+      - uses: codecov/codecov-action@v2
+        if: always()
+        with:
+          directory: ./coverage

.yarnrc.yml

@@ -3,6 +3,16 @@ enableGlobalCache: true
 nodeLinker: node-modules
 
 packageExtensions:
+  "@docusaurus/plugin-pwa@*":
+    peerDependencies:
+      "@babel/core": ^7.8.0
+  react-dev-utils@*:
+    peerDependencies:
+      typescript: ^4.0.1
+      webpack: ^5.60.0
+    peerDependenciesMeta:
+      typescript:
+        optional: true
   react-native-codegen@*:
     peerDependencies:
       "@babel/preset-env": ^7.1.6

CHANGELOG.md

@@ -2,39 +2,51 @@
 
 ### Features
 
-- `[expect]` [**BREAKING**] Migrate to ESM ([#12344](https://github.com/facebook/jest/pull/12344))
+- `[babel-jest]` Export `createTransformer` function ([#12399](https://github.com/facebook/jest/pull/12399))
+- `[expect]` Expose `AsymmetricMatchers`, `MatcherFunction` and `MatcherFunctionWithState` interfaces ([#12363](https://github.com/facebook/jest/pull/12363), [#12376](https://github.com/facebook/jest/pull/12376))
 - `[jest-config]` [**BREAKING**] Stop shipping `jest-environment-jsdom` by default ([#12354](https://github.com/facebook/jest/pull/12354))
 - `[jest-config]` [**BREAKING**] Stop shipping `jest-jasmine2` by default ([#12355](https://github.com/facebook/jest/pull/12355))
+- `[jest-config, @jest/types]` Add `ci` to `GlobalConfig` ([#12378](https://github.com/facebook/jest/pull/12378))
 - `[jest-environment-jsdom]` [**BREAKING**] Upgrade jsdom to 19.0.0 ([#12290](https://github.com/facebook/jest/pull/12290))
 - `[jest-environment-jsdom]` [**BREAKING**] Add default `browser` condition to `exportConditions` for `jsdom` environment ([#11924](https://github.com/facebook/jest/pull/11924))
-- `[jest-environment-jsdom]` [**BREAKING**] Migrate to ESM ([#12340](https://github.com/facebook/jest/pull/12340))
 - `[jest-environment-node]` [**BREAKING**] Add default `node` and `node-addon` conditions to `exportConditions` for `node` environment ([#11924](https://github.com/facebook/jest/pull/11924))
-- `[jest-environment-node]` [**BREAKING**] Migrate to ESM ([#12340](https://github.com/facebook/jest/pull/12340))
 - `[@jest/expect-utils]` New module exporting utils for `expect` ([#12323](https://github.com/facebook/jest/pull/12323))
-- `[jest-jasmine2, jest-runtime]` [**BREAKING**] Use `Symbol` to pass `jest.setTimeout` value instead of `jasmine` specific logic ([#12124](https://github.com/facebook/jest/pull/12124))
-- `[jest-jasmine2, jest-types]` [**BREAKING**] Move all `jasmine` specific types from `@jest/types` to its own package ([#12125](https://github.com/facebook/jest/pull/12125))
 - `[jest-resolver]` [**BREAKING**] Add support for `package.json` `exports` ([11961](https://github.com/facebook/jest/pull/11961))
-- `[jest-snapshot]` [**BREAKING**] Migrate to ESM ([#12342](https://github.com/facebook/jest/pull/12342))
+- `[jest-resolve, jest-runtime]` Add support for `data:` URI import and mock ([#12392](https://github.com/facebook/jest/pull/12392))
+- `[@jest/schemas]` New module for JSON schemas for Jest's config ([#12384](https://github.com/facebook/jest/pull/12384))
 - `[jest-worker]` [**BREAKING**] Allow only absolute `workerPath` ([#12343](https://github.com/facebook/jest/pull/12343))
+- `[pretty-format]` New `maxWidth` parameter ([#12402](https://github.com/facebook/jest/pull/12402))
 
 ### Fixes
 
 - `[expect]` Move typings of `.not`, `.rejects` and `.resolves` modifiers outside of `Matchers` interface ([#12346](https://github.com/facebook/jest/pull/12346))
+- `[jest-config]` Correctly detect CI environment and update snapshots accordingly ([#12378](https://github.com/facebook/jest/pull/12378))
+- `[jest-config]` Pass `moduleTypes` to `ts-node` to enforce CJS when transpiling ([#12397](https://github.com/facebook/jest/pull/12397))
 - `[jest-environment-jsdom]` Make `jsdom` accessible to extending environments again ([#12232](https://github.com/facebook/jest/pull/12232))
-- `[jest-phabricator]` [**BREAKING**] Convert to ESM ([#12341](https://github.com/facebook/jest/pull/12341))
+- `[jest-jasmine2, jest-types]` [**BREAKING**] Move all `jasmine` specific types from `@jest/types` to its own package ([#12125](https://github.com/facebook/jest/pull/12125))
+- `[jest-matcher-utils]` Pass maxWidth to `pretty-format` to avoid printing every element in arrays by default ([#12402](https://github.com/facebook/jest/pull/12402))
 
 ### Chore & Maintenance
 
 - `[*]` [**BREAKING**] Drop support for Node v10 and v15 and target first LTS `16.13.0` ([#12220](https://github.com/facebook/jest/pull/12220))
 - `[*]` [**BREAKING**] Drop support for `[email protected]`, minimum version is now `4.2` ([#11142](https://github.com/facebook/jest/pull/11142))
 - `[*]` Bundle all `.d.ts` files into a single `index.d.ts` per module ([#12345](https://github.com/facebook/jest/pull/12345))
+- `[docs]` Add note about not mixing `done()` with Promises ([#11077](https://github.com/facebook/jest/pull/11077))
+- `[docs, examples]` Update React examples to match with the new React guidelines for code examples ([#12217](https://github.com/facebook/jest/pull/12217))
 - `[expect]` [**BREAKING**] Remove support for importing `build/utils` ([#12323](https://github.com/facebook/jest/pull/12323))
+- `[expect]` [**BREAKING**] Migrate to ESM ([#12344](https://github.com/facebook/jest/pull/12344))
 - `[jest-cli]` Update `yargs` to v17 ([#12357](https://github.com/facebook/jest/pull/12357))
 - `[jest-config]` [**BREAKING**] Remove `getTestEnvironment` export ([#12353](https://github.com/facebook/jest/pull/12353))
 - `[@jest/core]` Use `index.ts` instead of `jest.ts` as main export ([#12329](https://github.com/facebook/jest/pull/12329))
+- `[jest-environment-jsdom]` [**BREAKING**] Migrate to ESM ([#12340](https://github.com/facebook/jest/pull/12340))
+- `[jest-environment-node]` [**BREAKING**] Migrate to ESM ([#12340](https://github.com/facebook/jest/pull/12340))
 - `[@jest/fake-timers]` Update `@sinonjs/fake_timers` to v9 ([#12357](https://github.com/facebook/jest/pull/12357))
+- `[jest-jasmine2, jest-runtime]` [**BREAKING**] Use `Symbol` to pass `jest.setTimeout` value instead of `jasmine` specific logic ([#12124](https://github.com/facebook/jest/pull/12124))
+- `[jest-phabricator]` [**BREAKING**] Migrate to ESM ([#12341](https://github.com/facebook/jest/pull/12341))
 - `[jest-resolve]` [**BREAKING**] Make `requireResolveFunction` argument mandatory ([#12353](https://github.com/facebook/jest/pull/12353))
 - `[jest-runner]` [**BREAKING**] Remove some type exports from `@jest/test-result` ([#12353](https://github.com/facebook/jest/pull/12353))
+- `[jest-serializer]` [**BREAKING**] Deprecate package in favour of using `v8` APIs directly ([#12391](https://github.com/facebook/jest/pull/12391))
+- `[jest-snapshot]` [**BREAKING**] Migrate to ESM ([#12342](https://github.com/facebook/jest/pull/12342))
 - `[jest-transform]` Update `write-file-atomic` to v4 ([#12357](https://github.com/facebook/jest/pull/12357))
 - `[jest]` Use `index.ts` instead of `jest.ts` as main export ([#12329](https://github.com/facebook/jest/pull/12329))
 

docs/Configuration.md

@@ -893,14 +893,14 @@ _Note: The `runner` property value can omit the `jest-runner-` prefix of the pac
 To write a test-runner, export a class with which accepts `globalConfig` in the constructor, and has a `runTests` method with the signature:
 
 ```ts
-async runTests(
+async function runTests(
   tests: Array<Test>,
   watcher: TestWatcher,
   onStart: OnTestStart,
   onResult: OnTestSuccess,
   onFailure: OnTestFailure,
   options: TestRunnerOptions,
-): Promise<void>
+): Promise<void>;
 ```
 
 If you need to restrict your test-runner to only run in serial rather than being executed in parallel your class should have the property `isSerial` to be set as `true`.
@@ -947,7 +947,7 @@ The number of seconds after which a test is considered as slow and reported as s
 
 Default: `undefined`
 
-Allows overriding specific snapshot formatting options documented in the [pretty-format readme](https://www.npmjs.com/package/pretty-format#usage-with-options). For example, this config would have the snapshot formatter not print a prefix for "Object" and "Array":
+Allows overriding specific snapshot formatting options documented in the [pretty-format readme](https://www.npmjs.com/package/pretty-format#usage-with-options), with the exceptions of `compareKeys` and `plugins`. For example, this config would have the snapshot formatter not print a prefix for "Object" and "Array":
 
 ```json
 {

docs/Es6ClassMocks.md

@@ -236,6 +236,76 @@ jest.mock('./sound-player', () => {
 
 This will throw **_TypeError: \_soundPlayer2.default is not a constructor_**, unless the code is transpiled to ES5, e.g. by `@babel/preset-env`. (ES5 doesn't have arrow functions nor classes, so both will be transpiled to plain functions.)
 
+## 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:
+
+```javascript
+// your jest test file below
+import SoundPlayer from './sound-player';
+import SoundPlayerConsumer from './sound-player-consumer';
+
+const playSoundFileMock = jest
+  .spyOn(SoundPlayer.prototype, 'playSoundFile')
+  .mockImplementation(() => {
+    console.log('mocked function');
+  }); // comment this line if just want to "spy"
+
+it('player consumer plays music', () => {
+  const player = new SoundPlayerConsumer();
+  player.playSomethingCool();
+  expect(playSoundFileMock).toHaveBeenCalled();
+});
+```
+
+### Static, getter and setter methods
+
+Lets imagine our class `SoundPlayer` has a getter method `foo` and a static method `brand`
+
+```javascript
+export default class SoundPlayer {
+  constructor() {
+    this.foo = 'bar';
+  }
+
+  playSoundFile(fileName) {
+    console.log('Playing sound file ' + fileName);
+  }
+
+  get foo() {
+    return 'bar';
+  }
+  static brand() {
+    return 'player-brand';
+  }
+}
+```
+
+You can mock/spy them easily, here is an example:
+
+```javascript
+// your jest test file below
+import SoundPlayer from './sound-player';
+import SoundPlayerConsumer from './sound-player-consumer';
+
+const staticMethodMock = jest
+  .spyOn(SoundPlayer, 'brand')
+  .mockImplementation(() => 'some-mocked-brand');
+
+const getterMethodMock = jest
+  .spyOn(SoundPlayer.prototype, 'foo', 'get')
+  .mockImplementation(() => 'some-mocked-result');
+
+it('custom methods are called', () => {
+  const player = new SoundPlayer();
+  const foo = player.foo;
+  const brand = SoundPlayer.brand();
+
+  expect(staticMethodMock).toHaveBeenCalled();
+  expect(getterMethodMock).toHaveBeenCalled();
+});
+```
+
 ## Keeping track of usage (spying on the mock)
 
 Injecting a test implementation is helpful, but you will probably also want to test whether the class constructor and methods are called with the correct parameters.

docs/ExpectAPI.md

@@ -1158,6 +1158,8 @@ test('the flavor list contains lime', () => {
 });
 ```
 
+This matcher also accepts others iterables such as strings, sets, node lists and HTML collections.
+
 ### `.toContainEqual(item)`
 
 Use `.toContainEqual` when you want to check that an item with a specific structure and values is contained in an array. For testing the items in the array, this matcher recursively checks the equality of all fields, rather than checking for object identity.

docs/GettingStarted.md

@@ -147,6 +147,8 @@ Jest can be used in projects that use [webpack](https://webpack.js.org/) to mana
 
 Jest can be used in projects that use [parcel-bundler](https://parceljs.org/) to manage assets, styles, and compilation similar to webpack. Parcel requires zero configuration. Refer to the official [docs](https://parceljs.org/docs/) to get started.
 
+### Using TypeScript
+
 ### Using TypeScript via Babel
 
 Jest supports TypeScript, via Babel. First, make sure you followed the instructions on [using Babel](#using-babel) above. Next, install the `@babel/preset-typescript` via `yarn`:

docs/GlobalAPI.md

@@ -398,7 +398,7 @@ test('will not be ran', () => {
 
 Also under the alias: `xdescribe(name, fn)`
 
-You can use `describe.skip` if you do not want to run a particular describe block:
+You can use `describe.skip` if you do not want to run the tests of a particular `describe` block:
 
 ```js
 describe('my beverage', () => {
@@ -416,7 +416,7 @@ describe.skip('my other beverage', () => {
 });
 ```
 
-Using `describe.skip` is often a cleaner alternative to temporarily commenting out a chunk of tests.
+Using `describe.skip` is often a cleaner alternative to temporarily commenting out a chunk of tests. Beware that the `describe` block will still run. If you have some setup that also should be skipped, do it in a `beforeAll` or `beforeEach` block.
 
 ### `describe.skip.each(table)(name, fn)`
 

docs/Puppeteer.md

@@ -98,7 +98,7 @@ class PuppeteerEnvironment extends NodeEnvironment {
     }
 
     // connect to puppeteer
-    this.global.__BROWSER__ = await puppeteer.connect({
+    this.global.__BROWSER_GLOBAL__ = await puppeteer.connect({
       browserWSEndpoint: wsEndpoint,
     });
   }
@@ -142,7 +142,7 @@ describe(
   () => {
     let page;
     beforeAll(async () => {
-      page = await global.__BROWSER__.newPage();
+      page = await global.__BROWSER_GLOBAL__.newPage();
       await page.goto('https://google.com');
     }, timeout);
 

docs/SnapshotTesting.md

@@ -12,7 +12,6 @@ A typical snapshot test case renders a UI component, takes a snapshot, then comp
 A similar approach can be taken when it comes to testing your React components. Instead of rendering the graphical UI, which would require building the entire app, you can use a test renderer to quickly generate a serializable value for your React tree. Consider this [example test](https://github.com/facebook/jest/blob/main/examples/snapshot/__tests__/link.test.js) for a [Link component](https://github.com/facebook/jest/blob/main/examples/snapshot/Link.js):
 
 ```tsx
-import React from 'react';
 import renderer from 'react-test-renderer';
 import Link from '../Link';
 

docs/TestingAsyncCode.md

@@ -47,6 +47,8 @@ If `done()` is never called, the test will fail (with timeout error), which is w
 
 If the `expect` statement fails, it throws an error and `done()` is not called. If we want to see in the test log why it failed, we have to wrap `expect` in a `try` block and pass the error in the `catch` block to `done`. Otherwise, we end up with an opaque timeout error that doesn't show what value was received by `expect(data)`.
 
+_Note: `done()` should not be mixed with Promises as this tends to lead to memory leaks in your tests._
+
 ## Promises
 
 If your code uses promises, there is a more straightforward way to handle asynchronous tests. Return a promise from your test, and Jest will wait for that promise to resolve. If the promise is rejected, the test will automatically fail.