Merge branch 'main' into patch-1

CHANGELOG.md

@@ -3,7 +3,9 @@
 ### Features
 
 - `[jest-cli]` Include type definitions to generated config files ([#14078](https://github.com/facebook/jest/pull/14078))
+- `[jest-core, jest-circus, jest-reporter, jest-runner]` Added support for reporting about start individual test cases using jest-circus ([#14174](https://github.com/jestjs/jest/pull/14174))
 - `[jest-snapshot]` Support arrays as property matchers ([#14025](https://github.com/facebook/jest/pull/14025))
+- `[jest-snapshot]` Add `toMatchNamedSnapshot` to bring snapshot support to concurrent mode ([#14045](https://github.com/facebook/jest/pull/14045))
 
 ### Fixes
 
@@ -14,6 +16,7 @@
 - `[jest-mock]` Tweak typings to allow `jest.replaceProperty()` replace methods ([#14008](https://github.com/facebook/jest/pull/14008))
 - `[jest-mock]` Improve user input validation and error messages of `spyOn` and `replaceProperty` methods ([#14087](https://github.com/facebook/jest/pull/14087))
 - `[jest-runtime]` Bind `jest.isolateModulesAsync` to `this` ([#14083](https://github.com/facebook/jest/pull/14083))
+- `[jest-runtime]` Forward `wrapperLength` to the `Script` constructor as `columnOffset` for accurate debugging ([#14148](https://github.com/facebook/jest/pull/14148))
 - `[jest-snapshot]` Fix a potential bug when not using prettier and improve performance ([#14036](https://github.com/facebook/jest/pull/14036))
 - `[@jest/transform]` Do not instrument `.json` modules ([#14048](https://github.com/facebook/jest/pull/14048))
 

docs/ExpectAPI.md

@@ -744,6 +744,16 @@ You can provide an optional `propertyMatchers` object argument, which has asymme
 
 You can provide an optional `hint` string argument that is appended to the test name. Although Jest always appends a number at the end of a snapshot name, short descriptive hints might be more useful than numbers to differentiate **multiple** snapshots in a **single** `it` or `test` block. Jest sorts snapshots by name in the corresponding `.snap` file.
 
+### `.toMatchNamedSnapshot(snapshotName, propertyMatchers?)`
+
+This ensures that a value matches the most recent snapshot. Check out [the Snapshot Testing guide](SnapshotTesting.md) for more information.
+
+You can provide an optional `propertyMatchers` object argument, which has asymmetric matchers as values of a subset of expected properties, **if** the received value will be an **object** instance. It is like `toMatchObject` with flexible criteria for a subset of properties, followed by a snapshot test as exact criteria for the rest of the properties.
+
+By setting the `snapshotName` explicitly (as opposed to letting Jest infer the name from context) it can be guaranteed to be consistent across test runs, whatever the context at the time of evaluation. Jest always appends a number at the end of a snapshot name.
+
+Jest sorts snapshots by name in the corresponding `.snap` file.
+
 ### `.toMatchInlineSnapshot(propertyMatchers?, inlineSnapshot)`
 
 Ensures that a value matches the most recent snapshot.
@@ -876,6 +886,12 @@ exports[`drinking flavors throws on octopus 1`] = `"yuck, octopus flavor"`;
 
 Check out [React Tree Snapshot Testing](/blog/2016/07/27/jest-14) for more information on snapshot testing.
 
+### `.toThrowErrorMatchingNamedSnapshot(snapshotName)`
+
+Use `.toThrowErrorMatchingNamedSnapshot` to test that a function throws an error matching the most recent snapshot when it is called.
+
+By setting the `snapshotName` explicitly (as opposed to letting Jest infer the name from context) it can be guaranteed to be consistent across test runs, whatever the context at the time of evaluation. Jest always appends a number at the end of a snapshot name.
+
 ### `.toThrowErrorMatchingInlineSnapshot(inlineSnapshot)`
 
 Use `.toThrowErrorMatchingInlineSnapshot` to test that a function throws an error matching the most recent snapshot when it is called.

docs/SnapshotTesting.md

@@ -52,6 +52,12 @@ More information on how snapshot testing works and why we built it can be found
 
 :::
 
+:::tip
+
+The `toMatchSnapshot` matcher infers the name based on the test function context when the snapshot is evaluated. This can cause snapshots in tests that are run concurrently to have different names on each test run. If you want to guarantee consistent names, you can use the `toMatchNamedSnapshot` matcher.
+
+:::
+
 ### Updating Snapshots
 
 It's straightforward to spot when a snapshot test fails after a bug has been introduced. When that happens, go ahead and fix the issue and make sure your snapshot tests are passing again. Now, let's talk about the case when a snapshot test is failing due to an intentional implementation change.
@@ -160,7 +166,7 @@ it('will fail every time', () => {
 
 // Snapshot
 exports[`will fail every time 1`] = `
-Object {
+{
   "createdAt": 2018-05-19T23:36:09.816Z,
   "id": 3,
   "name": "LeBron James",
@@ -186,7 +192,7 @@ it('will check the matchers and pass', () => {
 
 // Snapshot
 exports[`will check the matchers and pass 1`] = `
-Object {
+{
   "createdAt": Any<Date>,
   "id": Any<Number>,
   "name": "LeBron James",
@@ -211,7 +217,7 @@ it('will check the values and pass', () => {
 
 // Snapshot
 exports[`will check the values and pass 1`] = `
-Object {
+{
   "createdAt": Any<Date>,
   "name": 'Bond... James Bond',
 }

e2e/__tests__/__snapshots__/customReportersOnCircus.test.ts.snap

@@ -14,3 +14,12 @@ exports[`Custom Reporters Integration on jest-circus push test case results for
 "onTestCaseResult: sample, status: todo, numExpectations: 0
 onTestFileResult testCaseResult 0: sample, status: todo, numExpectations: 0"
 `;
+
+exports[`Custom Reporters Integration on jest-circus push test case start 1`] = `
+"onTestCaseStart: test 1, mode: undefined, ancestorTitles: Custom Reporters
+onTestCaseStart: test 2, mode: undefined, ancestorTitles: Custom Reporters"
+`;
+
+exports[`Custom Reporters Integration on jest-circus doesn't push test case start for skip tests 1`] = `""`;
+
+exports[`Custom Reporters Integration on jest-circus doesn't push test case start for todo tests 1`] = `""`;

e2e/__tests__/__snapshots__/globals.test.ts.snap

@@ -24,9 +24,9 @@ exports[`cannot have describe with no implementation 1`] = `
     Missing second argument. It must be a callback function.
 
     > 1 | describe('describe, no implementation');
-        |          ^
+        |                                        ^
 
-      at Object.<anonymous> (__tests__/onlyConstructs.test.js:1:10)"
+      at Object.<anonymous> (__tests__/onlyConstructs.test.js:1:40)"
 `;
 
 exports[`cannot have describe with no implementation 2`] = `

e2e/__tests__/__snapshots__/toThrowErrorMatchingNamedSnapshot.test.ts.snap

@@ -0,0 +1,8 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`support-reject 1`] = `
+"// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[\`support-reject 1\`] = \`"octopus"\`;
+"
+`;

e2e/__tests__/customReportersOnCircus.test.ts

@@ -54,4 +54,40 @@ describe('Custom Reporters Integration on jest-circus', () => {
 
     expect(stdout).toMatchSnapshot();
   });
+
+  test('push test case start', () => {
+    const {stdout} = runJest('custom-reporters', [
+      '--config',
+      JSON.stringify({
+        reporters: ['default', '<rootDir>/reporters/TestCaseStartReporter.js'],
+      }),
+      'just2Tests.test.js',
+    ]);
+
+    expect(stdout).toMatchSnapshot();
+  });
+
+  test("doesn't push test case start for todo tests", () => {
+    const {stdout} = runJest('custom-reporters', [
+      '--config',
+      JSON.stringify({
+        reporters: ['default', '<rootDir>/reporters/TestCaseStartReporter.js'],
+      }),
+      'todo.test.js',
+    ]);
+
+    expect(stdout).toMatchSnapshot();
+  });
+
+  test("doesn't push test case start for skip tests", () => {
+    const {stdout} = runJest('custom-reporters', [
+      '--config',
+      JSON.stringify({
+        reporters: ['default', '<rootDir>/reporters/TestCaseStartReporter.js'],
+      }),
+      'skip.test.js',
+    ]);
+
+    expect(stdout).toMatchSnapshot();
+  });
 });

e2e/__tests__/testEnvironmentCircus.test.ts

@@ -23,6 +23,7 @@ it('calls testEnvironment handleTestEvent', () => {
       "run_start",
       "run_describe_start",
       "test_start: test name here",
+      "test_started: test name here",
       "hook_start",
       "hook_success: test name here",
       "hook_start",
@@ -31,6 +32,7 @@ it('calls testEnvironment handleTestEvent', () => {
       "test_fn_success: test name here",
       "test_done: test name here",
       "test_start: second test name here",
+      "test_started: second test name here",
       "hook_start",
       "hook_success: second test name here",
       "hook_start",

e2e/__tests__/testEnvironmentCircusAsync.test.ts

@@ -36,6 +36,7 @@ it('calls asynchronous handleTestEvent in testEnvironment', () => {
       "run_describe_start",
       "run_describe_start",
       "test_start: passing test",
+      "test_started: passing test",
       "hook_start: beforeEach",
       "hook_success: beforeEach",
       "hook_start: beforeEach",
@@ -46,6 +47,7 @@ it('calls asynchronous handleTestEvent in testEnvironment', () => {
       "hook_failure: afterEach",
       "test_done: passing test",
       "test_start: failing test",
+      "test_started: failing test",
       "hook_start: beforeEach",
       "hook_success: beforeEach",
       "hook_start: beforeEach",