Implement pluggable watch mode

Resolves #4824

This is my first nontrivial contribution to Jest so please be gentle :)

This makes watch mode pluggable, allowing for arbitrary watch plugin
modules to be registered in the global config and used to generate
prompt messages and key listeners when watch mode is activated.

When a particular plugin is activated, Jest no longer handles keypresses
until the plugin calls the `end` callback (see #4824 for design details)

This currently does not implement any existing watch functionality as a
plugin and is rather adding the infrastructure to do so. That will
follow soon :)

@cpojer @aaronabramov I'm not sure if the globalConfig is the best place
for this (to be honest I can't make sense of the the sheer number of
config types). I also haven't gotten around to running a manual test for
this quite yet. More interested in design feedback at this point :)

Test Plan: `jest`

Author: Will Binns-Smith

packages/jest-cli/package.json

@@ -16,6 +16,7 @@
     "jest-changed-files": "^21.2.0",
     "jest-config": "^21.2.1",
     "jest-environment-jsdom": "^21.2.1",
+    "jest-get-type": "^21.2.0",
     "jest-haste-map": "^21.2.0",
     "jest-message-util": "^21.2.1",
     "jest-regex-util": "^21.2.0",

packages/jest-cli/src/__tests__/__fixtures__/watch_plugin.js

@@ -12,3 +12,20 @@ Watch Usage
 ",
 ]
 `;
+
+exports[`Watch mode flows shows prompts for WatchPlugins in alphabetical order 1`] = `
+Array [
+  Array [
+    "
+Watch Usage
+ › Press a to run all tests.
+ › Press p to filter by a filename regex pattern.
+ › Press t to filter by a test name regex pattern.
+ › Press s to do nothing.
+ › Press u to do something else.
+ › Press q to quit watch mode.
+ › Press Enter to trigger a test run.
+",
+  ],
+]
+`;

packages/jest-cli/src/__tests__/__fixtures__/watch_plugin2.js

@@ -30,6 +30,18 @@ jest.doMock(
     },
 );
 
+jest.doMock('./__fixtures__/watch_plugin', () => ({
+  enter: jest.fn(),
+  key: 0x73, // 's' key
+  prompt: 'do nothing',
+}));
+
+jest.doMock('./__fixtures__/watch_plugin2', () => ({
+  enter: jest.fn(),
+  key: 0x75, // 'u' key
+  prompt: 'do something else',
+}));
+
 const watch = require('../watch').default;
 afterEach(runJestMock.mockReset);
 
@@ -89,6 +101,88 @@ describe('Watch mode flows', () => {
     expect(pipe.write.mock.calls.reverse()[0]).toMatchSnapshot();
   });
 
+  it('resolves relative to the package root', () => {
+    expect(async () => {
+      await watch(
+        Object.assign({}, globalConfig, {
+          rootDir: __dirname,
+          watchPlugins: ['./__fixtures__/watch_plugin'],
+        }),
+        contexts,
+        pipe,
+        hasteMapInstances,
+        stdin,
+      );
+    }).not.toThrow();
+  });
+
+  it('shows prompts for WatchPlugins in alphabetical order', async () => {
+    watch(
+      Object.assign({}, globalConfig, {
+        rootDir: __dirname,
+        watchPlugins: [
+          './__fixtures__/watch_plugin2',
+          './__fixtures__/watch_plugin',
+        ],
+      }),
+      contexts,
+      pipe,
+      hasteMapInstances,
+      stdin,
+    );
+
+    expect(pipe.write.mock.calls).toMatchSnapshot();
+  });
+
+  it('triggers enter on a WatchPlugin when its key is pressed', () => {
+    const plugin = require('./__fixtures__/watch_plugin');
+
+    watch(
+      Object.assign({}, globalConfig, {
+        rootDir: __dirname,
+        watchPlugins: ['./__fixtures__/watch_plugin'],
+      }),
+      contexts,
+      pipe,
+      hasteMapInstances,
+      stdin,
+    );
+
+    stdin.emit(plugin.key.toString(16));
+
+    expect(plugin.enter).toHaveBeenCalled();
+  });
+
+  it('prevents Jest from handling keys when active and returns control when end is called', () => {
+    const plugin = require('./__fixtures__/watch_plugin');
+    const plugin2 = require('./__fixtures__/watch_plugin2');
+
+    let pluginEnd;
+    plugin.enter = jest.fn((globalConfig, end) => (pluginEnd = end));
+
+    watch(
+      Object.assign({}, globalConfig, {
+        rootDir: __dirname,
+        watchPlugins: [
+          './__fixtures__/watch_plugin',
+          './__fixtures__/watch_plugin2',
+        ],
+      }),
+      contexts,
+      pipe,
+      hasteMapInstances,
+      stdin,
+    );
+
+    stdin.emit(plugin.key.toString(16));
+    expect(plugin.enter).toHaveBeenCalled();
+    stdin.emit(plugin2.key.toString(16));
+    expect(plugin2.enter).not.toHaveBeenCalled();
+    pluginEnd();
+    stdin.emit(plugin2.key.toString(16));
+    expect(plugin2.enter).toHaveBeenCalled();
+  });
+
   it('Pressing "o" runs test in "only changed files" mode', () => {
     watch(globalConfig, contexts, pipe, hasteMapInstances, stdin);
     runJestMock.mockReset();

packages/jest-cli/src/__tests__/__snapshots__/watch.test.js.snap

@@ -0,0 +1,79 @@
+/**
+ * Copyright (c) 2014-present, Facebook, Inc. 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.
+ *
+ * @flow
+ */
+
+import type {WatchPlugin} from '../types';
+import getType from 'jest-get-type';
+import defaultResolver from '../../../jest-resolve/src/default_resolver';
+
+const RESERVED_KEYS = [
+  0x03, // Jest should handle ctrl-c interrupt
+  0x71, // 'q' is reserved for quit
+];
+
+export default class WatchPluginRegistry {
+  _rootDir: string;
+  _watchPluginsByKey: Map<number, WatchPlugin>;
+
+  constructor(rootDir: string) {
+    this._rootDir = rootDir;
+    this._watchPluginsByKey = new Map();
+  }
+
+  loadPluginPath(pluginModulePath: string) {
+    // $FlowFixMe dynamic require
+    const maybePlugin = require(defaultResolver(pluginModulePath, {
+      basedir: this._rootDir,
+    }));
+
+    // Since we're loading the module from a dynamic path, assert its shape
+    // before assuming it's a valid watch plugin.
+    if (getType(maybePlugin) !== 'object') {
+      throw new Error(
+        `Jest watch plugin ${pluginModulePath} must be an ES Module or export an object`,
+      );
+    }
+    if (getType(maybePlugin.key) !== 'number') {
+      throw new Error(
+        `Jest watch plugin ${pluginModulePath} must export 'key' as a number`,
+      );
+    }
+    if (getType(maybePlugin.prompt) !== 'string') {
+      throw new Error(
+        `Jest watch plugin ${pluginModulePath} must export 'prompt' as a string`,
+      );
+    }
+    if (getType(maybePlugin.enter) !== 'function') {
+      throw new Error(
+        `Jest watch plugin ${pluginModulePath} must export 'enter' as a function`,
+      );
+    }
+
+    const plugin: WatchPlugin = ((maybePlugin: any): WatchPlugin);
+
+    if (RESERVED_KEYS.includes(maybePlugin.key)) {
+      throw new Error(
+        `Jest watch plugin ${pluginModulePath} tried to register reserved key ${String.fromCodePoint(
+          maybePlugin.key,
+        )}`,
+      );
+    }
+    // TODO: Reject registering when another plugin has claimed the key?
+    this._watchPluginsByKey.set(plugin.key, plugin);
+  }
+
+  getPluginByPressedKey(pressedKey: number): ?WatchPlugin {
+    return this._watchPluginsByKey.get(pressedKey);
+  }
+
+  getPluginsOrderedByKey(): Array<WatchPlugin> {
+    return Array.from(this._watchPluginsByKey.values()).sort(
+      (a, b) => a.key - b.key,
+    );
+  }
+}

packages/jest-cli/src/__tests__/watch.test.js

@@ -0,0 +1,16 @@
+/**
+ * Copyright (c) 2014-present, Facebook, Inc. 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.
+ *
+ * @flow
+ */
+
+import type {GlobalConfig} from 'types/Config';
+
+export type WatchPlugin = {
+  key: number,
+  prompt: string,
+  enter: (globalConfig: GlobalConfig, end: () => mixed) => mixed,
+};

packages/jest-cli/src/lib/watch_plugin_registry.js

@@ -9,6 +9,7 @@
 
 import type {GlobalConfig} from 'types/Config';
 import type {Context} from 'types/Context';
+import type {WatchPlugin} from './types';
 
 import ansiEscapes from 'ansi-escapes';
 import chalk from 'chalk';
@@ -26,6 +27,7 @@ import TestWatcher from './test_watcher';
 import Prompt from './lib/Prompt';
 import TestPathPatternPrompt from './test_path_pattern_prompt';
 import TestNamePatternPrompt from './test_name_pattern_prompt';
+import WatchPluginRegistry from './lib/watch_plugin_registry';
 import {KEYS, CLEAR} from './constants';
 
 const isInteractive = process.stdout.isTTY && !isCI;
@@ -47,6 +49,13 @@ export default function watch(
     passWithNoTests: true,
   });
 
+  const watchPlugins = new WatchPluginRegistry(globalConfig.rootDir);
+  if (globalConfig.watchPlugins != null) {
+    for (const pluginModulePath of globalConfig.watchPlugins) {
+      watchPlugins.loadPluginPath(pluginModulePath);
+    }
+  }
+
   const prompt = new Prompt();
   const testPathPatternPrompt = new TestPathPatternPrompt(outputStream, prompt);
   const testNamePatternPrompt = new TestNamePatternPrompt(outputStream, prompt);
@@ -121,7 +130,9 @@ export default function watch(
         // and prevent test runs from the previous run.
         testWatcher = new TestWatcher({isWatchMode: true});
         if (shouldDisplayWatchUsage) {
-          outputStream.write(usage(globalConfig, hasSnapshotFailure));
+          outputStream.write(
+            usage(globalConfig, watchPlugins, hasSnapshotFailure),
+          );
           shouldDisplayWatchUsage = false; // hide Watch Usage after first run
           isWatchUsageDisplayed = true;
         } else {
@@ -138,12 +149,19 @@ export default function watch(
     }).catch(error => console.error(chalk.red(error.stack)));
   };
 
+  let activePlugin: ?WatchPlugin;
   const onKeypress = (key: string) => {
     if (key === KEYS.CONTROL_C || key === KEYS.CONTROL_D) {
       process.exit(0);
       return;
     }
 
+    if (activePlugin != null) {
+      // if a plugin is activate, Jest should let it handle keystrokes, so ignore
+      // them here
+      return;
+    }
+
     if (prompt.isEntering()) {
       prompt.put(key);
       return;
@@ -159,6 +177,20 @@ export default function watch(
       return;
     }
 
+    const matchingWatchPlugin = watchPlugins.getPluginByPressedKey(
+      parseInt(key, 16),
+    );
+    if (matchingWatchPlugin != null) {
+      // "activate" the plugin, which has jest ignore keystrokes so the plugin
+      // can handle them
+      activePlugin = matchingWatchPlugin;
+      activePlugin.enter(
+        globalConfig,
+        // end callback -- returns control to jest to handle keystrokes
+        () => (activePlugin = null),
+      );
+    }
+
     switch (key) {
       case KEYS.Q:
         process.exit(0);
@@ -236,7 +268,9 @@ export default function watch(
         if (!shouldDisplayWatchUsage && !isWatchUsageDisplayed) {
           outputStream.write(ansiEscapes.cursorUp());
           outputStream.write(ansiEscapes.eraseDown);
-          outputStream.write(usage(globalConfig, hasSnapshotFailure));
+          outputStream.write(
+            usage(globalConfig, watchPlugins, hasSnapshotFailure),
+          );
           isWatchUsageDisplayed = true;
           shouldDisplayWatchUsage = false;
         }
@@ -247,7 +281,7 @@ export default function watch(
   const onCancelPatternPrompt = () => {
     outputStream.write(ansiEscapes.cursorHide);
     outputStream.write(ansiEscapes.clearScreen);
-    outputStream.write(usage(globalConfig, hasSnapshotFailure));
+    outputStream.write(usage(globalConfig, watchPlugins, hasSnapshotFailure));
     outputStream.write(ansiEscapes.cursorShow);
   };
 
@@ -284,7 +318,12 @@ const activeFilters = (globalConfig: GlobalConfig, delimiter = '\n') => {
   return '';
 };
 
-const usage = (globalConfig, snapshotFailure, delimiter = '\n') => {
+const usage = (
+  globalConfig,
+  watchPlugins: WatchPluginRegistry,
+  snapshotFailure,
+  delimiter = '\n',
+) => {
   const messages = [
     activeFilters(globalConfig),
 
@@ -320,6 +359,17 @@ const usage = (globalConfig, snapshotFailure, delimiter = '\n') => {
       't' +
       chalk.dim(' to filter by a test name regex pattern.'),
 
+    ...watchPlugins
+      .getPluginsOrderedByKey()
+      .map(
+        plugin =>
+          chalk.dim(' \u203A Press') +
+          ' ' +
+          String.fromCodePoint(plugin.key) +
+          ' ' +
+          chalk.dim(`to ${plugin.prompt}.`),
+      ),
+
     chalk.dim(' \u203A Press ') + 'q' + chalk.dim(' to quit watch mode.'),
 
     chalk.dim(' \u203A Press ') +

packages/jest-cli/src/types.js

@@ -112,6 +112,7 @@ const getConfigs = (
       verbose: options.verbose,
       watch: options.watch,
       watchAll: options.watchAll,
+      watchPlugins: options.watchPlugins,
       watchman: options.watchman,
     }),
     projectConfig: Object.freeze({

packages/jest-cli/src/watch.js

@@ -96,5 +96,6 @@ export default ({
   verbose: false,
   watch: false,
   watchPathIgnorePatterns: [],
+  watchPlugins: [],
   watchman: true,
 }: InitialOptions);

packages/jest-config/src/index.js

@@ -51,6 +51,7 @@ const DEFAULT_GLOBAL_CONFIG: GlobalConfig = {
   verbose: false,
   watch: false,
   watchAll: false,
+  watchPlugins: [],
   watchman: false,
 };