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,13 @@ 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 rng = undefined;
+  if (seed) {
+    rng = rngBuilder(seed).next;
+  }
+  await _runTestsForDescribeBlock(rootDescribeBlock, rng, true);
   await dispatch({name: 'run_finish'});
   return makeRunResult(
     getState().rootDescribeBlock,
@@ -31,6 +36,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 +74,14 @@ const _runTestsForDescribeBlock = async (
   const retryTimes = parseInt(global[RETRY_TIMES], 10) || 0;
   const deferredRetryTests = [];
 
+  // jhwang I did this :)
+  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

@@ -1152,6 +1152,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() * 4294967296);
+  }
+
   return {
     hasDeprecationWarnings,
     options: newOptions,

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

@@ -279,6 +279,11 @@ const runWithoutWatch = async (
     if (!globalConfig.listTests) {
       preRunMessagePrint(outputStream);
     }
+
+    if (globalConfig.seed) {
+      console.log("Seed is", globalConfig.seed);
+    }
+
     return runJest({
       changedFilesPromise,
       contexts,

packages/jest-core/src/lib/__tests__/__snapshots__/logDebugMessages.test.ts.snap

@@ -92,6 +92,7 @@ exports[`prints the config object 1`] = `
     "onlyFailures": false,
     "passWithNoTests": false,
     "projects": [],
+    "randomize": false,
     "reporters": [],
     "rootDir": "/test_root_dir/",
     "runTestsByPath": false,

packages/jest-core/src/runJest.ts

@@ -200,6 +200,7 @@ export default async function runJest({
     allTests = await sequencer.shard(allTests, globalConfig.shard);
   }
 
+  // jhwang allTests actually means all test suites
   allTests = await sequencer.sort(allTests);
 
   if (globalConfig.listTests) {

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) {
+      console.log("Seed is", globalConfig.seed);
+    }
     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/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,38 @@
+// Mulberry 32 taken from
+// https://stackoverflow.com/questions/521295/seeding-the-random-number-generator-in-javascript
+export function mulberry32(seed: number): {next: () => number} {
+  let state = seed;
+
+  function next(): number {
+    state |= 0;
+    state = (state + 0x6d2b79f5) | 0;
+    let t = Math.imul(state ^ (state >>> 15), state | 1);
+    t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+  }
+
+  return {next};
+}
+
+export const rngBuilder = mulberry32;
+
+// 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

@@ -43,10 +43,12 @@ const DEFAULT_GLOBAL_CONFIG: Config.GlobalConfig = {
   outputFile: undefined,
   passWithNoTests: false,
   projects: [],
+  randomize: false,
   replname: undefined,
   reporters: [],
   rootDir: '/test_root_dir/',
   runTestsByPath: false,
+  seed: undefined,
   silent: false,
   skipFilter: false,
   snapshotFormat: {},