jest-circus runs children in shuffled order

CHANGELOG.md

@@ -41,6 +41,7 @@
 ### Features
 
 - `[@jest/environment, jest-runtime]` Allow passing a generic type argument to `jest.createMockFromModule<T>()` method ([#13202](https://github.com/facebook/jest/pull/13202))
+- `[jest-circus, jest-cli, jest-config, @jest/core, @jest/types, @jest-util]` Add cli feature to randomize order or tests ([#12922](https://github.com/facebook/jest/pull/12922))
 - `[expect]` Expose `ExpectationResult` type ([#13240](https://github.com/facebook/jest/pull/13240))
 - `[jest-snapshot]` Expose `Context` type ([#13240](https://github.com/facebook/jest/pull/13240))
 - `[@jest/globals]` Add `jest.Mock` type helper ([#13235](https://github.com/facebook/jest/pull/13235))

docs/CLI.md

@@ -28,6 +28,18 @@ Run tests related to changed files based on hg/git (uncommitted files):
 jest -o
 ```
 
+Run tests in a file in a random order (this will print the seed used for random number generation):
+
+```bash
+jest --randomize
+```
+
+Run tests in a file in an order determined by a seed:
+
+```bash
+jest --randomize --seed 1234
+```
+
 Run tests related to `path/to/fileA.js` and `path/to/fileB.js`:
 
 ```bash
@@ -318,6 +330,11 @@ If configuration files are found in the specified paths, _all_ projects specifie
 
 :::
 
+### `--randomize`
+
+Shuffle the order of the tests within a file. The seed used to generate the new order will be printed to stdout.
+In order to determine the seed refer to the `--seed` CLI option.
+
 ### `--reporters`
 
 Run tests with specified reporters. [Reporter options](configuration#reporters-arraymodulename--modulename-options) are not available via CLI. Example with multiple reporters:
@@ -350,6 +367,10 @@ The default regex matching works fine on small runs, but becomes slow if provide
 
 :::
 
+### `--seed`
+
+Run the tests in the order specified by the seed value. Must be used with the `--randomize` flag.
+
 ### `--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.

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

@@ -0,0 +1,344 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`works with each 1`] = `
+"PASS __tests__/each.test.js
+  ✓ test1
+  ✓ test2
+  ✓ test3
+  describe1
+    ✓ test4
+    ✓ test6
+    ✓ test5
+  describe3
+    ✓ test11
+    ✓ test12
+    ✓ test10
+    describe4
+      ✓ test14
+      ✓ test13
+      ✓ test15
+  describe2
+    ✓ test4
+    ✓ test5
+    ✓ test6"
+`;
+
+exports[`works with hooks 1`] = `
+"Seed is 123
+  console.log
+    This is before all
+
+      at Object.log (__tests__/hooks.test.js:2:11)
+
+  console.log
+    This is before each
+
+      at Object.log (__tests__/hooks.test.js:6:11)
+
+  console.log
+    test4
+
+      at Object.log (__tests__/hooks.test.js:31:13)
+
+  console.log
+    This is after each
+
+      at Object.log (__tests__/hooks.test.js:10:11)
+
+  console.log
+    This is before each
+
+      at Object.log (__tests__/hooks.test.js:6:11)
+
+  console.log
+    test6
+
+      at Object.log (__tests__/hooks.test.js:39:13)
+
+  console.log
+    This is after each
+
+      at Object.log (__tests__/hooks.test.js:10:11)
+
+  console.log
+    This is before each
+
+      at Object.log (__tests__/hooks.test.js:6:11)
+
+  console.log
+    test5
+
+      at Object.log (__tests__/hooks.test.js:35:13)
+
+  console.log
+    This is after each
+
+      at Object.log (__tests__/hooks.test.js:10:11)
+
+  console.log
+    This is before each
+
+      at Object.log (__tests__/hooks.test.js:6:11)
+
+  console.log
+    test1
+
+      at Object.log (__tests__/hooks.test.js:18:11)
+
+  console.log
+    This is after each
+
+      at Object.log (__tests__/hooks.test.js:10:11)
+
+  console.log
+    This is before each
+
+      at Object.log (__tests__/hooks.test.js:6:11)
+
+  console.log
+    This is before each describe3
+
+      at Object.log (__tests__/hooks.test.js:63:13)
+
+  console.log
+    test11
+
+      at Object.log (__tests__/hooks.test.js:71:13)
+
+  console.log
+    This is after each
+
+      at Object.log (__tests__/hooks.test.js:10:11)
+
+  console.log
+    This is before each
+
+      at Object.log (__tests__/hooks.test.js:6:11)
+
+  console.log
+    This is before each describe3
+
+      at Object.log (__tests__/hooks.test.js:63:13)
+
+  console.log
+    test12
+
+      at Object.log (__tests__/hooks.test.js:75:13)
+
+  console.log
+    This is after each
+
+      at Object.log (__tests__/hooks.test.js:10:11)
+
+  console.log
+    This is before each
+
+      at Object.log (__tests__/hooks.test.js:6:11)
+
+  console.log
+    This is before each describe3
+
+      at Object.log (__tests__/hooks.test.js:63:13)
+
+  console.log
+    test14
+
+      at Object.log (__tests__/hooks.test.js:84:15)
+
+  console.log
+    This is after each
+
+      at Object.log (__tests__/hooks.test.js:10:11)
+
+  console.log
+    This is before each
+
+      at Object.log (__tests__/hooks.test.js:6:11)
+
+  console.log
+    This is before each describe3
+
+      at Object.log (__tests__/hooks.test.js:63:13)
+
+  console.log
+    test13
+
+      at Object.log (__tests__/hooks.test.js:80:15)
+
+  console.log
+    This is after each
+
+      at Object.log (__tests__/hooks.test.js:10:11)
+
+  console.log
+    This is before each
+
+      at Object.log (__tests__/hooks.test.js:6:11)
+
+  console.log
+    This is before each describe3
+
+      at Object.log (__tests__/hooks.test.js:63:13)
+
+  console.log
+    test15
+
+      at Object.log (__tests__/hooks.test.js:88:15)
+
+  console.log
+    This is after each
+
+      at Object.log (__tests__/hooks.test.js:10:11)
+
+  console.log
+    This is before each
+
+      at Object.log (__tests__/hooks.test.js:6:11)
+
+  console.log
+    This is before each describe3
+
+      at Object.log (__tests__/hooks.test.js:63:13)
+
+  console.log
+    test10
+
+      at Object.log (__tests__/hooks.test.js:67:13)
+
+  console.log
+    This is after each
+
+      at Object.log (__tests__/hooks.test.js:10:11)
+
+  console.log
+    This is before each
+
+      at Object.log (__tests__/hooks.test.js:6:11)
+
+  console.log
+    test7
+
+      at Object.log (__tests__/hooks.test.js:49:13)
+
+  console.log
+    This is after each
+
+      at Object.log (__tests__/hooks.test.js:10:11)
+
+  console.log
+    This is before each
+
+      at Object.log (__tests__/hooks.test.js:6:11)
+
+  console.log
+    test8
+
+      at Object.log (__tests__/hooks.test.js:53:13)
+
+  console.log
+    This is after each
+
+      at Object.log (__tests__/hooks.test.js:10:11)
+
+  console.log
+    This is before each
+
+      at Object.log (__tests__/hooks.test.js:6:11)
+
+  console.log
+    test9
+
+      at Object.log (__tests__/hooks.test.js:57:13)
+
+  console.log
+    This is after each
+
+      at Object.log (__tests__/hooks.test.js:10:11)
+
+  console.log
+    This is after all describe2
+
+      at Object.log (__tests__/hooks.test.js:45:13)
+
+  console.log
+    This is before each
+
+      at Object.log (__tests__/hooks.test.js:6:11)
+
+  console.log
+    test2
+
+      at Object.log (__tests__/hooks.test.js:22:11)
+
+  console.log
+    This is after each
+
+      at Object.log (__tests__/hooks.test.js:10:11)
+
+  console.log
+    This is before each
+
+      at Object.log (__tests__/hooks.test.js:6:11)
+
+  console.log
+    test3
+
+      at Object.log (__tests__/hooks.test.js:26:11)
+
+  console.log
+    This is after each
+
+      at Object.log (__tests__/hooks.test.js:10:11)
+
+  console.log
+    This is after all
+
+      at Object.log (__tests__/hooks.test.js:14:11)
+"
+`;
+
+exports[`works with passing tests 1`] = `
+"PASS __tests__/success.test.js
+  ✓ test1
+  ✓ test2
+  ✓ test3
+  describe1
+    ✓ test4
+    ✓ test6
+    ✓ test5
+  describe3
+    ✓ test11
+    ✓ test12
+    ✓ test10
+    describe4
+      ✓ test14
+      ✓ test13
+      ✓ test15
+  describe2
+    ✓ test7
+    ✓ test8
+    ✓ test9"
+`;
+
+exports[`works with snapshots 1`] = `
+"PASS __tests__/snapshots.test.js
+  ✓ test1
+  ✓ test2
+  ✓ test3
+  describe1
+    ✓ test4
+    ✓ test6
+    ✓ test5
+  describe3
+    ✓ test11
+    ✓ test12
+    ✓ test10
+    describe4
+      ✓ test14
+      ✓ test13
+      ✓ test15
+  describe2
+    ✓ test4
+    ✓ test5
+    ✓ test6"
+`;