jest-circus runs children in shuffled order

packages/jest-circus/src/legacy-code-todo-rewrite/jestAdapterInit.ts

@@ -62,6 +62,9 @@ export const initialize = async ({
     getRunnerState().testTimeout = globalConfig.testTimeout;
   }
   getRunnerState().maxConcurrency = globalConfig.maxConcurrency;
+  if (globalConfig.seed) {
+    getRunnerState().seed = globalConfig.seed;
+  }
 
   // @ts-expect-error: missing `concurrent` which is added later
   const globalsObject: Global.TestFrameworkGlobals = {

packages/jest-circus/src/run.ts

@@ -7,6 +7,7 @@
 
 import pLimit = require('p-limit');
 import type {Circus} from '@jest/types';
+import {rngBuilder, shuffleArray} from 'jest-util';
 import {dispatch, getState} from './state';
 import {RETRY_TIMES} from './types';
 import {
@@ -19,9 +20,14 @@ import {
 } from './utils';
 
 const run = async (): Promise<Circus.RunResult> => {
-  const {rootDescribeBlock} = getState();
+  const {rootDescribeBlock, seed} = getState();
   await dispatch({name: 'run_start'});
-  await _runTestsForDescribeBlock(rootDescribeBlock, true);
+  let nextRng: undefined | (() => number) = undefined;
+  if (seed) {
+    const rng = rngBuilder(seed);
+    nextRng = () => rng.next();
+  }
+  await _runTestsForDescribeBlock(rootDescribeBlock, nextRng, true);
   await dispatch({name: 'run_finish'});
   return makeRunResult(
     getState().rootDescribeBlock,
@@ -31,6 +37,7 @@ const run = async (): Promise<Circus.RunResult> => {
 
 const _runTestsForDescribeBlock = async (
   describeBlock: Circus.DescribeBlock,
+  rng: (() => number) | undefined,
   isRootBlock = false,
 ) => {
   await dispatch({describeBlock, name: 'run_describe_start'});
@@ -68,10 +75,13 @@ const _runTestsForDescribeBlock = async (
   const retryTimes = parseInt(global[RETRY_TIMES], 10) || 0;
   const deferredRetryTests = [];
 
+  if (rng) {
+    describeBlock.children = shuffleArray(describeBlock.children, rng);
+  }
   for (const child of describeBlock.children) {
     switch (child.type) {
       case 'describeBlock': {
-        await _runTestsForDescribeBlock(child);
+        await _runTestsForDescribeBlock(child, rng);
         break;
       }
       case 'test': {

packages/jest-circus/src/state.ts

@@ -33,6 +33,7 @@ const createState = (): Circus.State => {
     testNamePattern: null,
     testTimeout: 5000,
     unhandledErrors: [],
+    seed: undefined,
   };
 };
 

packages/jest-cli/src/cli/args.ts

@@ -10,6 +10,10 @@ import type {Config} from '@jest/types';
 import {constants, isJSONString} from 'jest-config';
 
 export function check(argv: Config.Argv): true {
+  if (argv.seed && !argv.randomize) {
+    throw new Error('--seed requires --randomize to be specified.');
+  }
+
   if (
     argv.runInBand &&
     Object.prototype.hasOwnProperty.call(argv, 'maxWorkers')
@@ -449,6 +453,10 @@ export const options: {[key: string]: Options} = {
     string: true,
     type: 'array',
   },
+  randomize: {
+    description: 'Randomise the order of the tests in each describe block',
+    type: 'boolean',
+  },
   reporters: {
     description: 'A list of custom reporters for the test suite.',
     string: true,
@@ -510,6 +518,11 @@ export const options: {[key: string]: Options} = {
       "Allows to use a custom runner instead of Jest's default test runner.",
     type: 'string',
   },
+  seed: {
+    description:
+      'Must be used with the randomize flag. Specify the seed to randomize with.',
+    type: 'number',
+  },
   selectProjects: {
     description:
       'Run the tests of the specified projects. ' +

packages/jest-config/src/index.ts

@@ -153,6 +153,7 @@ const groupOptions = (
     reporters: options.reporters,
     rootDir: options.rootDir,
     runTestsByPath: options.runTestsByPath,
+    seed: options.seed,
     shard: options.shard,
     silent: options.silent,
     skipFilter: options.skipFilter,

packages/jest-config/src/normalize.ts

@@ -1139,6 +1139,11 @@ export default async function normalize(
     newOptions.shard = parseShardPair(argv.shard);
   }
 
+  if (argv.randomize) {
+    // at time of writing we use mulberry32 pseudorandom number generator so 32 bits
+    newOptions.seed = argv.seed ?? Math.floor(Math.random() * Math.pow(2, 32));
+  }
+
   return {
     hasDeprecationWarnings,
     options: newOptions,

packages/jest-core/src/cli/index.ts

@@ -276,9 +276,14 @@ const runWithoutWatch = async (
   filter?: Filter,
 ) => {
   const startRun = async (): Promise<void | null> => {
+    if (globalConfig.seed) {
+      outputStream.write(`Seed is ${globalConfig.seed}\n`);
+    }
+
     if (!globalConfig.listTests) {
       preRunMessagePrint(outputStream);
     }
+
     return runJest({
       changedFilesPromise,
       contexts,

packages/jest-core/src/watch.ts

@@ -287,6 +287,9 @@ export default async function watch(
 
     testWatcher = new TestWatcher({isWatchMode: true});
     isInteractive && outputStream.write(specialChars.CLEAR);
+    if (globalConfig.seed) {
+      outputStream.write(`Seed is ${globalConfig.seed}\n`);
+    }
     preRunMessagePrint(outputStream);
     isRunning = true;
     const configs = contexts.map(context => context.config);

packages/jest-types/src/Circus.ts

@@ -215,6 +215,7 @@ export type State = {
   originalGlobalErrorHandlers?: GlobalErrorHandlers;
   parentProcess: Process | null; // process object from the outer scope
   rootDescribeBlock: DescribeBlock;
+  seed?: number;
   testNamePattern?: RegExp | null;
   testTimeout: number;
   unhandledErrors: Array<Exception>;

packages/jest-types/src/Config.ts

@@ -394,6 +394,7 @@ export type GlobalConfig = {
   reporters?: Array<ReporterConfig>;
   runTestsByPath: boolean;
   rootDir: string;
+  seed?: number;
   shard?: ShardConfig;
   silent?: boolean;
   skipFilter: boolean;
@@ -529,6 +530,7 @@ export type Argv = Arguments<
     preset: string | null | undefined;
     prettierPath: string | null | undefined;
     projects: Array<string>;
+    randomize: boolean;
     reporters: Array<string>;
     resetMocks: boolean;
     resetModules: boolean;
@@ -537,6 +539,7 @@ export type Argv = Arguments<
     rootDir: string;
     roots: Array<string>;
     runInBand: boolean;
+    seed: number;
     selectProjects: Array<string>;
     setupFiles: Array<string>;
     setupFilesAfterEnv: Array<string>;

packages/jest-util/package.json

@@ -22,7 +22,8 @@
     "chalk": "^4.0.0",
     "ci-info": "^3.2.0",
     "graceful-fs": "^4.2.9",
-    "picomatch": "^2.2.3"
+    "picomatch": "^2.2.3",
+    "prando": "^6.0.1"
   },
   "devDependencies": {
     "@types/graceful-fs": "^4.1.3",

packages/jest-util/src/index.ts

@@ -28,3 +28,4 @@ export {default as pluralize} from './pluralize';
 export {default as formatTime} from './formatTime';
 export {default as tryRealpath} from './tryRealpath';
 export {default as requireOrImportModule} from './requireOrImportModule';
+export {default as shuffleArray, rngBuilder} from './shuffleArray';

packages/jest-util/src/shuffleArray.ts

@@ -0,0 +1,24 @@
+import Prando from 'prando';
+
+export const rngBuilder: (seed: number) => { next: () => number } = (seed: number) => new Prando(seed);
+
+// Fisher-Yates shuffle
+// This is performed in-place
+export default function shuffleArray<T>(
+  array: Array<T>,
+  random: () => number = Math.random,
+): Array<T> {
+  const length = array == null ? 0 : array.length;
+  if (!length) {
+    return [];
+  }
+  let index = -1;
+  const lastIndex = length - 1;
+  while (++index < length) {
+    const rand = index + Math.floor(random() * (lastIndex - index + 1));
+    const value = array[index];
+    array[index] = array[rand];
+    array[rand] = value;
+  }
+  return array;
+}

packages/test-utils/src/config.ts

@@ -47,6 +47,7 @@ const DEFAULT_GLOBAL_CONFIG: Config.GlobalConfig = {
   reporters: [],
   rootDir: '/test_root_dir/',
   runTestsByPath: false,
+  seed: undefined,
   silent: false,
   skipFilter: false,
   snapshotFormat: {},

yarn.lock

@@ -12923,6 +12923,7 @@ __metadata:
     ci-info: ^3.2.0
     graceful-fs: ^4.2.9
     picomatch: ^2.2.3
+    prando: ^6.0.1
   languageName: unknown
   linkType: soft
 
@@ -16794,6 +16795,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"prando@npm:^6.0.1":
+  version: 6.0.1
+  resolution: "prando@npm:6.0.1"
+  checksum: c0c25dbb2cb92dff4b0f44781f0e2132886c34ab6a12f7f0839d6073c783d86589d4c632727819d8fb0a5a675a7e27223285c6907261d3b6a49167b4cbdc162a
+  languageName: node
+  linkType: hard
+
 "prelude-ls@npm:^1.2.1":
   version: 1.2.1
   resolution: "prelude-ls@npm:1.2.1"