feat: add a seed value to test runs

CHANGELOG.md

@@ -2,6 +2,7 @@
 
 ### Features
 
+- `[@jest/cli, jest-config, @jest/environment, jest-environment-node, jest-environment-jsdom, @jest/reporters, jest-runtime, @jest/types]` Add `getSeed()` to the jest object available at runtime ([#13400](https://github.com/facebook/jest/pull/13400/))
 - `[jest-config]` Add `readInitialConfig` utility function ([#13356](https://github.com/facebook/jest/pull/13356))
 - `[jest-core]` Enable testResultsProcessor to be async ([#13343](https://github.com/facebook/jest/pull/13343))
 - `[expect, @jest/expect-utils]` Allow `isA` utility to take a type argument ([#13355](https://github.com/facebook/jest/pull/13355))

docs/CLI.md

@@ -350,6 +350,17 @@ The default regex matching works fine on small runs, but becomes slow if provide
 
 :::
 
+### `--seed=<num>`
+
+Provides a seed number that the tests have access to via `jest.getSeed()`.
+If this option isn't specified Jest will randomly generate a seed.
+
+The seed value must be between `-0x80000000` to `0x7fffffff` inclusive.
+
+```bash
+jest --seed=1324
+```
+
 ### `--selectProjects <project1> ... <projectN>`
 
 Run the tests of the specified projects. Jest uses the attribute `displayName` in the configuration to identify each project. If you use this option, you should provide a `displayName` to all your projects.

docs/JestObjectAPI.md

@@ -908,6 +908,15 @@ This function is not available when using legacy fake timers implementation.
 
 ## Misc
 
+### `jest.getSeed()`
+Every time Jest runs a seed value is randomly generated which you could use in a pseudorandom number generator or anywhere else.
+
+:::tip
+
+You can manually define this value with the CLI argument `--seed=<num>`.
+
+:::
+
 ### `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.

e2e/Utils.ts

@@ -157,6 +157,9 @@ export const copyDir = (src: string, dest: string) => {
   }
 };
 
+export const replaceSeed = (str: string) =>
+  str.replace(/Seed:        (-?\d+)/g, 'Seed:       <<REPLACED>>');
+
 export const replaceTime = (str: string) =>
   str
     .replace(/\d*\.?\d+ m?s\b/g, '<<REPLACED>>')
@@ -201,7 +204,7 @@ export const extractSummary = (stdout: string) => {
   const match = stdout
     .replace(/(?:\\[rn])+/g, '\n')
     .match(
-      /Test Suites:.*\nTests.*\nSnapshots.*\nTime.*(\nRan all test suites)*.*\n*$/gm,
+      /Seed:.*\nTest Suites:.*\nTests.*\nSnapshots.*\nTime.*(\nRan all test suites)*.*\n*$/gm,
     );
   if (!match) {
     throw new Error(dedent`
@@ -211,7 +214,7 @@ export const extractSummary = (stdout: string) => {
     `);
   }
 
-  const summary = replaceTime(match[0]);
+  const summary = replaceSeed(replaceTime(match[0]));
 
   const rest = stdout
     .replace(match[0], '')
@@ -245,7 +248,7 @@ const sortTests = (stdout: string) =>
 export const extractSortedSummary = (stdout: string) => {
   const {rest, summary} = extractSummary(stdout);
   return {
-    rest: sortTests(replaceTime(rest)),
+    rest: sortTests(replaceSeed(replaceTime(rest))),
     summary,
   };
 };
@@ -254,7 +257,7 @@ export const extractSummaries = (
   stdout: string,
 ): Array<{rest: string; summary: string}> => {
   const regex =
-    /Test Suites:.*\nTests.*\nSnapshots.*\nTime.*(\nRan all test suites)*.*\n*$/gm;
+    /Seed:.*\nTest Suites:.*\nTests.*\nSnapshots.*\nTime.*(\nRan all test suites)*.*\n*$/gm;
 
   let match = regex.exec(stdout);
   const matches: Array<RegExpExecArray> = [];

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

@@ -9,7 +9,8 @@ Force exiting Jest: Have you considered using \`--detectOpenHandles\` to detect
 `;
 
 exports[`CLI accepts exact file names if matchers matched 2`] = `
-"Test Suites: 1 passed, 1 total
+"Seed:       <<REPLACED>>
+Test Suites: 1 passed, 1 total
 Tests:       1 passed, 1 total
 Snapshots:   0 total
 Time:        <<REPLACED>>

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

@@ -41,7 +41,8 @@ exports[`console printing 1`] = `
 `;
 
 exports[`console printing 2`] = `
-"Test Suites: 1 passed, 1 total
+"Seed:       <<REPLACED>>
+Test Suites: 1 passed, 1 total
 Tests:       1 passed, 1 total
 Snapshots:   0 total
 Time:        <<REPLACED>>
@@ -92,7 +93,8 @@ exports[`console printing with --verbose 2`] = `
 `;
 
 exports[`console printing with --verbose 3`] = `
-"Test Suites: 1 passed, 1 total
+"Seed:       <<REPLACED>>
+Test Suites: 1 passed, 1 total
 Tests:       1 passed, 1 total
 Snapshots:   0 total
 Time:        <<REPLACED>>
@@ -127,7 +129,8 @@ exports[`does not error out when using winston 2`] = `
 `;
 
 exports[`does not error out when using winston 3`] = `
-"Test Suites: 1 passed, 1 total
+"Seed:       <<REPLACED>>
+Test Suites: 1 passed, 1 total
 Tests:       1 passed, 1 total
 Snapshots:   0 total
 Time:        <<REPLACED>>
@@ -139,7 +142,8 @@ exports[`does not print to console with --silent 1`] = `""`;
 exports[`does not print to console with --silent 2`] = `"PASS __tests__/console.test.js"`;
 
 exports[`does not print to console with --silent 3`] = `
-"Test Suites: 1 passed, 1 total
+"Seed:       <<REPLACED>>
+Test Suites: 1 passed, 1 total
 Tests:       1 passed, 1 total
 Snapshots:   0 total
 Time:        <<REPLACED>>"
@@ -174,7 +178,8 @@ exports[`respects --noStackTrace 2`] = `
 `;
 
 exports[`respects --noStackTrace 3`] = `
-"Test Suites: 1 passed, 1 total
+"Seed:       <<REPLACED>>
+Test Suites: 1 passed, 1 total
 Tests:       1 passed, 1 total
 Snapshots:   0 total
 Time:        <<REPLACED>>
@@ -210,7 +215,8 @@ exports[`respects noStackTrace in config 2`] = `
 `;
 
 exports[`respects noStackTrace in config 3`] = `
-"Test Suites: 1 passed, 1 total
+"Seed:       <<REPLACED>>
+Test Suites: 1 passed, 1 total
 Tests:       1 passed, 1 total
 Snapshots:   0 total
 Time:        <<REPLACED>>
@@ -225,7 +231,8 @@ exports[`the jsdom console is the same as the test console 2`] = `
 `;
 
 exports[`the jsdom console is the same as the test console 3`] = `
-"Test Suites: 1 passed, 1 total
+"Seed:       <<REPLACED>>
+Test Suites: 1 passed, 1 total
 Tests:       1 passed, 1 total
 Snapshots:   0 total
 Time:        <<REPLACED>>

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

@@ -14,7 +14,8 @@ exports[`console debugging with --verbose 2`] = `
 `;
 
 exports[`console debugging with --verbose 3`] = `
-"Test Suites: 1 passed, 1 total
+"Seed:       <<REPLACED>>
+Test Suites: 1 passed, 1 total
 Tests:       1 passed, 1 total
 Snapshots:   1 passed, 1 total
 Time:        <<REPLACED>>

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

@@ -9,7 +9,8 @@ Force exiting Jest: Have you considered using \`--detectOpenHandles\` to detect
 `;
 
 exports[`prints console.logs when run with forceExit 2`] = `
-"Test Suites: 1 passed, 1 total
+"Seed:       <<REPLACED>>
+Test Suites: 1 passed, 1 total
 Tests:       1 passed, 1 total
 Snapshots:   0 total
 Time:        <<REPLACED>>

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

@@ -61,7 +61,8 @@ All files                            |      60 |        0 |      50 |      60 |
 `;
 
 exports[`json reporter printing with --coverage 1`] = `
-"Test Suites: 1 failed, 1 total
+"Seed:       <<REPLACED>>
+Test Suites: 1 failed, 1 total
 Tests:       1 failed, 1 skipped, 2 passed, 4 total
 Snapshots:   0 total
 Time:        <<REPLACED>>

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

@@ -8,7 +8,8 @@ Jest: "global" coverage threshold for lines (100%) not met: 0%"
 `;
 
 exports[`excludes tests matched by path threshold groups from global group 2`] = `
-"Test Suites: 1 passed, 1 total
+"Seed:       <<REPLACED>>
+Test Suites: 1 passed, 1 total
 Tests:       1 passed, 1 total
 Snapshots:   0 total
 Time:        <<REPLACED>>
@@ -42,7 +43,8 @@ Jest: "global" coverage threshold for lines (90%) not met: 50%"
 `;
 
 exports[`exits with 1 if coverage threshold is not met 2`] = `
-"Test Suites: 1 passed, 1 total
+"Seed:       <<REPLACED>>
+Test Suites: 1 passed, 1 total
 Tests:       1 passed, 1 total
 Snapshots:   0 total
 Time:        <<REPLACED>>
@@ -66,7 +68,8 @@ Jest: Coverage data for apple.js was not found."
 `;
 
 exports[`exits with 1 if path threshold group is not found in coverage data 2`] = `
-"Test Suites: 1 passed, 1 total
+"Seed:       <<REPLACED>>
+Test Suites: 1 passed, 1 total
 Tests:       1 passed, 1 total
 Snapshots:   0 total
 Time:        <<REPLACED>>
@@ -92,7 +95,8 @@ Jest: "./banana.js" coverage threshold for lines (100%) not met: 50%"
 `;
 
 exports[`file is matched by all path and glob threshold groups 2`] = `
-"Test Suites: 1 passed, 1 total
+"Seed:       <<REPLACED>>
+Test Suites: 1 passed, 1 total
 Tests:       1 passed, 1 total
 Snapshots:   0 total
 Time:        <<REPLACED>>

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

@@ -78,7 +78,8 @@ exports[`Custom Reporters Integration default reporters enabled 1`] = `
 `;
 
 exports[`Custom Reporters Integration default reporters enabled 2`] = `
-"Test Suites: 1 passed, 1 total
+"Seed:       <<REPLACED>>
+Test Suites: 1 passed, 1 total
 Tests:       1 passed, 1 total
 Snapshots:   0 total
 Time:        <<REPLACED>>

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

@@ -43,6 +43,7 @@ exports[`should work without error 1`] = `
 
       at Object.toBe (__tests__/dom.test.js:18:41)
 
+Seed:       <<REPLACED>>
 Test Suites: 1 failed, 1 total
 Tests:       2 failed, 2 total
 Snapshots:   0 total

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

@@ -3,7 +3,8 @@
 exports[`hook in describe with skipped test 1`] = `
 Object {
   "rest": "",
-  "summary": "Test Suites: 1 skipped, 0 of 1 total
+  "summary": "Seed:       <<REPLACED>>
+Test Suites: 1 skipped, 0 of 1 total
 Tests:       1 skipped, 1 total
 Snapshots:   0 total
 Time:        <<REPLACED>>
@@ -30,7 +31,8 @@ Object {
 
       at beforeEach (__tests__/hookInEmptyDescribe.test.js:9:3)
       at Object.describe (__tests__/hookInEmptyDescribe.test.js:8:1)",
-  "summary": "Test Suites: 1 failed, 1 total
+  "summary": "Seed:       <<REPLACED>>
+Test Suites: 1 failed, 1 total
 Tests:       1 passed, 1 total
 Snapshots:   0 total
 Time:        <<REPLACED>>
@@ -57,7 +59,8 @@ Object {
 
       at beforeEach (__tests__/hookInEmptyNestedDescribe.test.js:9:3)
       at Object.describe (__tests__/hookInEmptyNestedDescribe.test.js:8:1)",
-  "summary": "Test Suites: 1 failed, 1 total
+  "summary": "Seed:       <<REPLACED>>
+Test Suites: 1 failed, 1 total
 Tests:       1 passed, 1 total
 Snapshots:   0 total
 Time:        <<REPLACED>>
@@ -129,7 +132,8 @@ Object {
 
       at beforeAll (__tests__/multipleHooksInEmptyDescribe.test.js:12:3)
       at Object.describe (__tests__/multipleHooksInEmptyDescribe.test.js:8:1)",
-  "summary": "Test Suites: 1 failed, 1 total
+  "summary": "Seed:       <<REPLACED>>
+Test Suites: 1 failed, 1 total
 Tests:       1 passed, 1 total
 Snapshots:   0 total
 Time:        <<REPLACED>>

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

@@ -1,7 +1,8 @@
 // Jest Snapshot v1, https://goo.gl/fbAQLP
 
 exports[`--findRelatedTests flag coverage configuration is applied correctly 1`] = `
-"Test Suites: 1 passed, 1 total
+"Seed:       <<REPLACED>>
+Test Suites: 1 passed, 1 total
 Tests:       1 passed, 1 total
 Snapshots:   0 total
 Time:        <<REPLACED>>
@@ -23,7 +24,8 @@ All files |     100 |      100 |     100 |     100 |
 `;
 
 exports[`--findRelatedTests flag generates coverage report for filename 1`] = `
-"Test Suites: 2 passed, 2 total
+"Seed:       <<REPLACED>>
+Test Suites: 2 passed, 2 total
 Tests:       2 passed, 2 total
 Snapshots:   0 total
 Time:        <<REPLACED>>
@@ -46,7 +48,8 @@ All files |     100 |      100 |     100 |     100 |
 `;
 
 exports[`--findRelatedTests flag generates coverage report for filename 4`] = `
-"Test Suites: 1 passed, 1 total
+"Seed:       <<REPLACED>>
+Test Suites: 1 passed, 1 total
 Tests:       1 passed, 1 total
 Snapshots:   0 total
 Time:        <<REPLACED>>