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

@@ -318,6 +318,26 @@ 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.
+
+:::tip
+
+Additionally you can use the [`--seed`](#--seed) flag to pass the seed value:
+
+```bash
+jest --randomize --seed 1234
+```
+
+:::
+
+:::note
+
+This option is only supported using the default `jest-circus` test runner.
+
+:::
+
 ### `--reporters`
 
 Run tests with specified reporters. [Reporter options](configuration#reporters-arraymodulename--modulename-options) are not available via CLI. Example with multiple reporters:
@@ -350,6 +370,20 @@ 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`](#--randomize) flag.
+
+```bash
+jest --randomize --seed 1234
+```
+
+:::note
+
+This option is only supported using the default `jest-circus` test runner.
+
+:::
+
 ### `--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.