jest-circus runs children in shuffled order

CHANGELOG.md

@@ -2,6 +2,7 @@
 
 ### Features
 
+- `[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))
 - `[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

@@ -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.

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

@@ -0,0 +1,128 @@
+// 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
+This is before all
+This is before each
+test4
+This is after each
+This is before each
+test6
+This is after each
+This is before each
+test5
+This is after each
+This is before each
+test1
+This is after each
+This is before each
+This is before each describe3
+test11
+This is after each
+This is before each
+This is before each describe3
+test12
+This is after each
+This is before each
+This is before each describe3
+test14
+This is after each
+This is before each
+This is before each describe3
+test13
+This is after each
+This is before each
+This is before each describe3
+test15
+This is after each
+This is before each
+This is before each describe3
+test10
+This is after each
+This is before each
+test7
+This is after each
+This is before each
+test8
+This is after each
+This is before each
+test9
+This is after each
+This is after all describe2
+This is before each
+test2
+This is after each
+This is before each
+test3
+This is after each
+This is after all"
+`;
+
+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"
+`;

e2e/__tests__/randomize.test.ts

@@ -0,0 +1,54 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates. All Rights Reserved.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import * as path from 'path';
+import {skipSuiteOnJasmine} from '@jest/test-utils';
+import {extractSummary} from '../Utils';
+import runJest from '../runJest';
+
+skipSuiteOnJasmine();
+
+const dir = path.resolve(__dirname, '../randomize');
+
+test('works with passing tests', () => {
+  const result = runJest(dir, [
+    'success.test.js',
+    '--randomize',
+    '--seed',
+    '123',
+  ]);
+  const {rest} = extractSummary(result.stderr);
+  expect(rest).toMatchSnapshot();
+});
+
+test('works with each', () => {
+  const result = runJest(dir, ['each.test.js', '--randomize', '--seed', '123']);
+  const {rest} = extractSummary(result.stderr);
+  expect(rest).toMatchSnapshot();
+});
+
+test('works with hooks', () => {
+  const result = runJest(dir, [
+    'hooks.test.js',
+    '--randomize',
+    '--seed',
+    '123',
+  ]);
+  // Change in formatting could change this one
+  expect(result.stdout).toMatchSnapshot();
+});
+
+test('works with snapshots', () => {
+  const result = runJest(dir, [
+    'snapshots.test.js',
+    '--randomize',
+    '--seed',
+    '123',
+  ]);
+  const {rest} = extractSummary(result.stderr);
+  expect(rest).toMatchSnapshot();
+});

e2e/randomize/__tests__/__snapshots__/snapshots.test.js.snap

@@ -0,0 +1,31 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`describe1 test4 1`] = `4`;
+
+exports[`describe1 test5 1`] = `5`;
+
+exports[`describe1 test6 1`] = `6`;
+
+exports[`describe2 test4 1`] = `4`;
+
+exports[`describe2 test5 1`] = `5`;
+
+exports[`describe2 test6 1`] = `6`;
+
+exports[`describe3 describe4 test13 1`] = `13`;
+
+exports[`describe3 describe4 test14 1`] = `14`;
+
+exports[`describe3 describe4 test15 1`] = `15`;
+
+exports[`describe3 test10 1`] = `10`;
+
+exports[`describe3 test11 1`] = `11`;
+
+exports[`describe3 test12 1`] = `12`;
+
+exports[`test1 1`] = `1`;
+
+exports[`test2 1`] = `2`;
+
+exports[`test3 1`] = `3`;

e2e/randomize/__tests__/each.test.js

@@ -0,0 +1,28 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates. All Rights Reserved.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+it.each([1, 2, 3])('test%d', () => {
+  expect(true).toBe(true);
+});
+
+describe.each([1, 2])('describe%d', () => {
+  it.each([4, 5, 6])('test%d', () => {
+    expect(true).toBe(true);
+  });
+});
+
+describe('describe3', () => {
+  it.each([10, 11, 12])('test%d', () => {
+    expect(true).toBe(true);
+  });
+
+  describe('describe4', () => {
+    it.each([13, 14, 15])('test%d', () => {
+      expect(true).toBe(true);
+    });
+  });
+});

e2e/randomize/__tests__/hooks.test.js

@@ -0,0 +1,98 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates. All Rights Reserved.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+beforeAll(() => {
+  process.stdout.write('This is before all\n');
+});
+
+beforeEach(() => {
+  process.stdout.write('This is before each\n');
+});
+
+afterEach(() => {
+  process.stdout.write('This is after each\n');
+});
+
+afterAll(() => {
+  process.stdout.write('This is after all\n');
+});
+
+it('test1', () => {
+  process.stdout.write('test1\n');
+});
+
+it('test2', () => {
+  process.stdout.write('test2\n');
+});
+
+it('test3', () => {
+  process.stdout.write('test3\n');
+});
+
+describe('describe1', () => {
+  it('test4', () => {
+    process.stdout.write('test4\n');
+  });
+
+  it('test5', () => {
+    process.stdout.write('test5\n');
+  });
+
+  it('test6', () => {
+    process.stdout.write('test6\n');
+  });
+});
+
+describe('describe2', () => {
+  afterAll(() => {
+    process.stdout.write('This is after all describe2\n');
+  });
+
+  it('test7', () => {
+    process.stdout.write('test7\n');
+  });
+
+  it('test8', () => {
+    process.stdout.write('test8\n');
+  });
+
+  it('test9', () => {
+    process.stdout.write('test9\n');
+  });
+});
+
+describe('describe3', () => {
+  beforeEach(() => {
+    process.stdout.write('This is before each describe3\n');
+  });
+
+  it('test10', () => {
+    process.stdout.write('test10\n');
+  });
+
+  it('test11', () => {
+    process.stdout.write('test11\n');
+  });
+
+  it('test12', () => {
+    process.stdout.write('test12\n');
+  });
+
+  describe('describe4', () => {
+    it('test13', () => {
+      process.stdout.write('test13\n');
+    });
+
+    it('test14', () => {
+      process.stdout.write('test14\n');
+    });
+
+    it('test15', () => {
+      process.stdout.write('test15\n');
+    });
+  });
+});