Add --listTests flag (#3441)

* Add --listTests flag

* Fixes.

docs/en/CLI.md

@@ -133,6 +133,10 @@ Write test results to a file when the `--json` option is also specified.
 
 Will run all tests affected by file changes in the last commit made.
 
+### `--listTests`
+
+Lists all tests as JSON that Jest will run given the arguments, and exits. This can be used together with `--findRelatedTests` to know which tests Jest will run.
+
 ### `--logHeapUsage`
 
 Logs the heap usage after every test. Useful to debug memory leaks. Use together with `--runInBand` and `--expose-gc` in node.

integration_tests/__tests__/list_tests-test.js

@@ -0,0 +1,21 @@
+/**
+ * Copyright (c) 2014-present, Facebook, Inc. All rights reserved.
+ *
+ * This source code is licensed under the BSD-style license found in the
+ * LICENSE file in the root directory of this source tree. An additional grant
+ * of patent rights can be found in the PATENTS file in the same directory.
+ *
+ * @emails oncall+jsinfra
+ */
+'use strict';
+
+const runJest = require('../runJest');
+
+describe('--listTests flag', () => {
+  it('causes tests to be printed out as JSON', () => {
+    const {status, stdout} = runJest('list_tests', ['--listTests']);
+
+    expect(status).toBe(0);
+    expect(() => JSON.parse(stdout)).not.toThrow();
+  });
+});

integration_tests/list_tests/__tests__/dummy-test.js

@@ -0,0 +1,14 @@
+/**
+ * Copyright (c) 2014-present, Facebook, Inc. All rights reserved.
+ *
+ * This source code is licensed under the BSD-style license found in the
+ * LICENSE file in the root directory of this source tree. An additional grant
+ * of patent rights can be found in the PATENTS file in the same directory.
+ */
+
+'use strict';
+
+it("isn't actually run", () => {
+  // (because it is only used for --listTests)
+  expect(true).toBe(false);
+});

integration_tests/list_tests/package.json

@@ -0,0 +1,5 @@
+{
+  "jest": {
+    "testEnvironment": "node"
+  }
+}

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

@@ -196,6 +196,11 @@ const options = {
       'commit made.',
     type: 'boolean',
   },
+  listTests: {
+    default: false,
+    description: 'Lists all tests Jest will run given the arguments and exits.',
+    type: 'boolean',
+  },
   logHeapUsage: {
     default: undefined,
     description: 'Logs the heap usage after every test. Useful to debug ' +

packages/jest-cli/src/cli/runCLI.js

@@ -75,7 +75,9 @@ module.exports = async (
       return watch(globalConfig, contexts, argv, pipe, hasteMapInstances);
     } else {
       const startRun = () => {
-        preRunMessage.print(pipe);
+        if (!argv.listTests) {
+          preRunMessage.print(pipe);
+        }
         runJest(
           globalConfig,
           contexts,

packages/jest-cli/src/runJest.js

@@ -154,7 +154,7 @@ const runJest = async (
   pipe: stream$Writable | tty$WriteStream,
   testWatcher: TestWatcher,
   startRun: () => *,
-  onComplete: (testResults: any) => void,
+  onComplete: (testResults: any) => any,
 ) => {
   const maxWorkers = getMaxWorkers(argv);
   const pattern = getTestPathPattern(argv);
@@ -175,6 +175,13 @@ const runJest = async (
   );
 
   allTests = sequencer.sort(allTests);
+
+  if (argv.listTests) {
+    console.log(JSON.stringify(allTests.map(test => test.path)));
+    onComplete && onComplete({success: true});
+    return null;
+  }
+
   if (!allTests.length) {
     new Console(pipe, pipe).log(getNoTestsFoundMessage(testRunData, pattern));
   } else if (