testem 3.19.1 → 3.20.0

package/lib/config.js

@@ -8,13 +8,11 @@ or `testem.json` config file.
 
 */
 
-
 const os = require('os');
 const fs = require('fs');
 const yaml = require('js-yaml');
 const log = require('./log');
 const path = require('path');
-const glob = require('glob').glob;
 const url = require('url');
 const querystring = require('querystring');
 const { filter, reduce } = require('./utils/promises');
@@ -29,7 +27,7 @@ const _ = require('lodash');
 
 const knownBrowsers = require('./utils/known-browsers');
 const { convertToPosix } = require('./utils/posix');
-const globAsync = glob;
+const expandGlobPattern = require('./utils/expand_glob_pattern');
 
 class Config {
   constructor(appMode, progOptions, config) {
@@ -39,7 +37,7 @@ class Config {
     this.fileOptions = {};
     this.config = config || {};
     this.getters = {
-      test_page: 'getTestPage'
+      test_page: 'getTestPage',
     };
 
     if (appMode === 'dev') {
@@ -71,12 +69,31 @@ class Config {
 
       // Try all testem.json, testem.yml and testem.js
       // testem.json gets precedence
-      let files = ['testem.json', '.testem.json', '.testem.yml', 'testem.yml', 'testem.js', '.testem.js', 'testem.cjs', '.testem.cjs'];
-      return filter(files.map(this.resolveConfigPath.bind(this)), fileExists).then(matched => {
+      let files = [
+        'testem.json',
+        '.testem.json',
+        '.testem.yml',
+        'testem.yml',
+        'testem.js',
+        '.testem.js',
+        'testem.cjs',
+        '.testem.cjs',
+      ];
+      return filter(
+        files.map(this.resolveConfigPath.bind(this)),
+        fileExists,
+      ).then((matched) => {
         let configFile = matched[0];
         if (matched.length > 1) {
-          let baseNames = matched.map(fileName => path.basename(fileName));
-          console.warn('Found ' + matched.length + ' config files (' + baseNames + '), using ' + baseNames[0]);
+          let baseNames = matched.map((fileName) => path.basename(fileName));
+          console.warn(
+            'Found ' +
+              matched.length +
+              ' config files (' +
+              baseNames +
+              '), using ' +
+              baseNames[0],
+          );
         }
         if (configFile) {
           this.readConfigFile(configFile, callback);
@@ -99,7 +116,7 @@ class Config {
 
   client() {
     return {
-      decycle_depth: this.get('client_decycle_depth')
+      decycle_depth: this.get('client_decycle_depth'),
     };
   }
 
@@ -122,7 +139,8 @@ class Config {
   }
 
   readConfigFile(configFile, callback) {
-    if (!configFile) { // allow empty configFile for programmatic setups
+    if (!configFile) {
+      // allow empty configFile for programmatic setups
       if (callback) {
         callback.call(this);
       }
@@ -143,7 +161,7 @@ class Config {
   readJS(configFile, callback) {
     let exportedConfig = require(this.resolveConfigPath(configFile));
     if (typeof exportedConfig === 'function') {
-      Promise.resolve(exportedConfig()).then(obj => {
+      Promise.resolve(exportedConfig()).then((obj) => {
         this.fileOptions = obj;
         if (callback) {
           callback.call(this);
@@ -158,10 +176,14 @@ class Config {
   }
 
   readYAML(configFile, callback) {
-    return fs.promises.readFile(configFile)
-      .then(data => {
-        this.fileOptions = yaml.load(String(data));
-      }, () => {})
+    return fs.promises
+      .readFile(configFile)
+      .then(
+        (data) => {
+          this.fileOptions = yaml.load(String(data));
+        },
+        () => {},
+      )
       .then(() => {
         if (callback) {
           callback.call(this);
@@ -170,11 +192,15 @@ class Config {
   }
 
   readJSON(configFile, callback) {
-    return fs.promises.readFile(configFile)
-      .then(data => {
-        this.fileOptions = JSON.parse(data.toString());
-        this.progOptions.file = configFile;
-      }, () => {})
+    return fs.promises
+      .readFile(configFile)
+      .then(
+        (data) => {
+          this.fileOptions = JSON.parse(data.toString());
+          this.progOptions.file = configFile;
+        },
+        () => {},
+      )
       .then(() => {
         if (callback) {
           callback.call(this);
@@ -196,11 +222,12 @@ class Config {
 
     let urlObj = url.parse(urlString);
     let outputQueryParams = querystring.parse(urlObj.query) || {};
-    Object.keys(queryParamsObj).forEach(param => {
+    Object.keys(queryParamsObj).forEach((param) => {
       outputQueryParams[param] = queryParamsObj[param];
     });
     urlObj.query = outputQueryParams;
-    urlObj.search = querystring.stringify(outputQueryParams)
+    urlObj.search = querystring
+      .stringify(outputQueryParams)
       .replace(/=&/g, '&')
       .replace(/=$/, '');
     urlObj.path = urlObj.pathname + urlObj.search;
@@ -215,20 +242,32 @@ class Config {
       testPage = [testPage];
     }
 
-    return testPage.map(page => this.mergeUrlAndQueryParams(page, queryParams));
+    return testPage.map((page) =>
+      this.mergeUrlAndQueryParams(page, queryParams),
+    );
   }
 
   getConfigProperty(key) {
     if (this.config && key in this.config) {
       return this.config[key];
     }
-    if (key in this.progOptions && typeof this.progOptions[key] !== 'undefined') {
+    if (
+      key in this.progOptions &&
+      typeof this.progOptions[key] !== 'undefined'
+    ) {
       return this.progOptions[key];
     }
-    if (key in this.fileOptions && typeof this.fileOptions[key] !== 'undefined') {
+    if (
+      key in this.fileOptions &&
+      typeof this.fileOptions[key] !== 'undefined'
+    ) {
       return this.fileOptions[key];
     }
-    if (this.defaultOptions && key in this.defaultOptions && typeof this.defaultOptions[key] !== 'undefined') {
+    if (
+      this.defaultOptions &&
+      key in this.defaultOptions &&
+      typeof this.defaultOptions[key] !== 'undefined'
+    ) {
       return this.defaultOptions[key];
     }
     if (key in this.defaults) {
@@ -264,27 +303,35 @@ class Config {
 
   getAvailableLaunchers(cb) {
     let browsers = knownBrowsers(process.platform, this);
-    browser_launcher.getAvailableBrowsers(this, browsers, (err, availableBrowsers) => {
-      if (err) {
-        return cb(err);
-      }
+    browser_launcher.getAvailableBrowsers(
+      this,
+      browsers,
+      (err, availableBrowsers) => {
+        if (err) {
+          return cb(err);
+        }
 
-      let availableLaunchers = {};
-      availableBrowsers.forEach(browser => {
-        let newLauncher = new LauncherFactory(browser.name, browser, this);
-        availableLaunchers[browser.name.toLowerCase()] = newLauncher;
-      });
+        let availableLaunchers = {};
+        availableBrowsers.forEach((browser) => {
+          let newLauncher = new LauncherFactory(browser.name, browser, this);
+          availableLaunchers[browser.name.toLowerCase()] = newLauncher;
+        });
 
-      // add custom launchers
-      let customLaunchers = this.get('launchers');
-      if (customLaunchers) {
-        for (let name in customLaunchers) {
-          let newLauncher = new LauncherFactory(name, customLaunchers[name], this);
-          availableLaunchers[name.toLowerCase()] = newLauncher;
+        // add custom launchers
+        let customLaunchers = this.get('launchers');
+        if (customLaunchers) {
+          for (let name in customLaunchers) {
+            let newLauncher = new LauncherFactory(
+              name,
+              customLaunchers[name],
+              this,
+            );
+            availableLaunchers[name.toLowerCase()] = newLauncher;
+          }
         }
-      }
-      cb(null, availableLaunchers);
-    });
+        cb(null, availableLaunchers);
+      },
+    );
   }
 
   getLaunchers(cb) {
@@ -310,7 +357,7 @@ class Config {
     let skip = this.get('skip');
     if (skip) {
       skip = skip.toLowerCase().split(',');
-      launchers = launchers.filter(name => skip.indexOf(name) === -1);
+      launchers = launchers.filter((name) => skip.indexOf(name) === -1);
     }
     return launchers;
   }
@@ -320,7 +367,7 @@ class Config {
     let wanted = this.getWantedLauncherNames(available);
     let err = null;
 
-    wanted.forEach(name => {
+    wanted.forEach((name) => {
       let launcher = available[name.toLowerCase()];
       if (!launcher) {
         if (this.appMode === 'dev' || this.get('ignore_missing_launchers')) {
@@ -328,10 +375,12 @@ class Config {
         } else {
           err = new Error(
             'Launcher ' +
-            name +
-            ' not found. Not installed? Available: ' +
-            Object.keys(available).map(elm => `"${elm}"`).join(', ') +
-            '.'
+              name +
+              ' not found. Not installed? Available: ' +
+              Object.keys(available)
+                .map((elm) => `"${elm}"`)
+                .join(', ') +
+              '.',
           );
         }
       } else {
@@ -343,38 +392,62 @@ class Config {
 
   printLauncherInfo() {
     this.getAvailableLaunchers((err, launchers) => {
-      let launch_in_dev = (this.get('launch_in_dev') || [])
-        .map(s => s.toLowerCase());
+      let launch_in_dev = (this.get('launch_in_dev') || []).map((s) =>
+        s.toLowerCase(),
+      );
       let launch_in_ci = this.get('launch_in_ci');
       if (launch_in_ci) {
-        launch_in_ci = launch_in_ci.map(s => s.toLowerCase());
+        launch_in_ci = launch_in_ci.map((s) => s.toLowerCase());
       }
-      launchers = Object.keys(launchers).map(k => launchers[k]);
+      launchers = Object.keys(launchers).map((k) => launchers[k]);
 
-      const launcherColumnWidth = launchers.reduce((acc, current) => acc > current.name.length ? acc : current.name.length, 0);
+      const launcherColumnWidth = launchers.reduce(
+        (acc, current) =>
+          acc > current.name.length ? acc : current.name.length,
+        0,
+      );
       const launcherTitle = 'Launcher'.padEnd(launcherColumnWidth, ' ');
       const launcherTitleDivider = ''.padEnd(launcherColumnWidth, '-');
 
-      console.log('Have ' + launchers.length + ' launchers available; auto-launch info displayed on the right.');
+      console.log(
+        'Have ' +
+          launchers.length +
+          ' launchers available; auto-launch info displayed on the right.',
+      );
       console.log(); // newline
       console.log(`${launcherTitle}  Type          CI  Dev`);
       console.log(`${launcherTitleDivider}  ------------  --  ---`);
-      console.log(launchers.map(launcher => {
-        let protocol = launcher.settings.protocol;
-        let kind = protocol === 'browser' ?
-          'browser' : (
-            protocol === 'tap' ?
-              'process(TAP)' : 'process');
-        let dev = launch_in_dev.indexOf(launcher.name.toLowerCase()) !== -1 ?
-          Chars.mark :
-          ' ';
-        let ci = !launch_in_ci || launch_in_ci.indexOf(launcher.name.toLowerCase()) !== -1 ?
-          Chars.mark :
-          ' ';
-        return (pad(launcher.name, launcherColumnWidth + 2, ' ', 1) +
-          pad(kind, 12, ' ', 1) +
-          '  ' + ci + '    ' + dev + '      ');
-      }).join('\n'));
+      console.log(
+        launchers
+          .map((launcher) => {
+            let protocol = launcher.settings.protocol;
+            let kind =
+              protocol === 'browser'
+                ? 'browser'
+                : protocol === 'tap'
+                  ? 'process(TAP)'
+                  : 'process';
+            let dev =
+              launch_in_dev.indexOf(launcher.name.toLowerCase()) !== -1
+                ? Chars.mark
+                : ' ';
+            let ci =
+              !launch_in_ci ||
+              launch_in_ci.indexOf(launcher.name.toLowerCase()) !== -1
+                ? Chars.mark
+                : ' ';
+            return (
+              pad(launcher.name, launcherColumnWidth + 2, ' ', 1) +
+              pad(kind, 12, ' ', 1) +
+              '  ' +
+              ci +
+              '    ' +
+              dev +
+              '      '
+            );
+          })
+          .join('\n'),
+      );
     });
   }
 
@@ -389,7 +462,7 @@ class Config {
     // Filter glob < 6 negation patterns to still support them
     // See https://github.com/isaacs/node-glob/tree/3f883c43#comments-and-negation
     let positiveWants = [];
-    want.forEach(patternEntry => {
+    want.forEach((patternEntry) => {
       let pattern = isa(patternEntry, String) ? patternEntry : patternEntry.src;
       if (pattern.indexOf('!') === 0) {
         return dontWant.push(pattern.substring(1));
@@ -398,33 +471,51 @@ class Config {
       positiveWants.push(patternEntry);
     });
 
-    dontWant = dontWant.map(p => p ? this.resolvePath(p) : p);
-    return reduce(positiveWants, (allThatIWant, patternEntry) => {
-      let pattern = isa(patternEntry, String) ? patternEntry : patternEntry.src;
-      let attrs = patternEntry.attrs || [];
-      let patternUrl = url.parse(pattern);
-
-      if (patternUrl.protocol === 'file:') {
-        pattern = patternUrl.hostname + patternUrl.path;
-      } else if (patternUrl.protocol) {
-        return allThatIWant.concat({ src: pattern, attrs: attrs });
-      }
+    dontWant = dontWant.map((p) => (p ? this.resolvePath(p) : p));
+    return reduce(
+      positiveWants,
+      (allThatIWant, patternEntry) => {
+        let pattern = isa(patternEntry, String)
+          ? patternEntry
+          : patternEntry.src;
+        let attrs = patternEntry.attrs || [];
+        let patternUrl = url.parse(pattern);
+
+        if (patternUrl.protocol === 'file:') {
+          pattern = patternUrl.hostname + patternUrl.path;
+        } else if (patternUrl.protocol) {
+          return allThatIWant.concat({ src: pattern, attrs: attrs });
+        }
 
-      return globAsync(convertToPosix(this.resolvePath(pattern)), { ignore: dontWant.map(convertToPosix) })
-        .then(files => files.sort())
-        .then(files => allThatIWant.concat(files.map(f => {
-          f = this.reverseResolvePath(f);
-          return { src: f, attrs: attrs };
-        })));
-    }, [])
-      .then(result => _.uniqBy(result, 'src'))
-      .then(result => {
-        if (callback) { callback(null, result); }
-        return result;
-      }, err => {
-        if (callback) { callback(err); }
-        throw err;
-      });
+        return expandGlobPattern(
+          convertToPosix(this.resolvePath(pattern)),
+          dontWant.map(convertToPosix),
+        ).then((files) =>
+          allThatIWant.concat(
+            files.map((f) => {
+              f = this.reverseResolvePath(f);
+              return { src: f, attrs: attrs };
+            }),
+          ),
+        );
+      },
+      [],
+    )
+      .then((result) => _.uniqBy(result, 'src'))
+      .then(
+        (result) => {
+          if (callback) {
+            callback(null, result);
+          }
+          return result;
+        },
+        (err) => {
+          if (callback) {
+            callback(err);
+          }
+          throw err;
+        },
+      );
   }
 
   getSrcFiles(callback) {
@@ -440,10 +531,10 @@ class Config {
     return this.getFileSet(want, dontWant, callback);
   }
 
-
   getServeFiles(callback) {
     let want = this.get('serve_files') || this.get('src_files') || '*.js';
-    let dontWant = this.get('serve_files_ignore') || this.get('src_files_ignore') || '';
+    let dontWant =
+      this.get('serve_files_ignore') || this.get('src_files_ignore') || '';
     return this.getFileSet(want, dontWant, callback);
   }
 
@@ -471,13 +562,19 @@ class Config {
         return;
       }
       if (o.options) {
-        o.options.forEach(o => {
+        o.options.forEach((o) => {
           options.push(o.name());
         });
       }
       getOptions(o.parent);
     }
-    getOptions(this.progOptions);
+    const progOpts = this.progOptions;
+    // In subcommand modes, progOptions is a plain object from optsWithGlobals() with
+    // a _commander reference pointing to the Command instance for option enumeration.
+    // In dev mode (no subcommand), progOptions is the Commander program object directly.
+    getOptions(
+      progOpts && progOpts._commander ? progOpts._commander : progOpts,
+    );
     return options;
   }
 
@@ -497,16 +594,16 @@ class Config {
       ret[key] = this.config[key];
     }
 
-    const replaceSlashes = f => ({
+    const replaceSlashes = (f) => ({
       src: f.src.replace(/\\/g, '/'),
-      attrs: f.attrs
+      attrs: f.attrs,
     });
 
     try {
       const [serveFiles, cssFiles, footerScripts] = await Promise.all([
         this.getServeFiles(),
         this.getCSSFiles(),
-        this.getFooterScripts()
+        this.getFooterScripts(),
       ]);
 
       ret.serve_files = serveFiles.map(replaceSlashes);
@@ -543,10 +640,13 @@ Config.prototype.defaults = {
   client_decycle_depth: 5,
   socket_heartbeat_timeout() {
     let browserDisconnectTimeout = this.get('browser_disconnect_timeout');
-    let defaultBrowserDisconnectTimeout = this.defaults.browser_disconnect_timeout;
+    let defaultBrowserDisconnectTimeout =
+      this.defaults.browser_disconnect_timeout;
 
-    return (browserDisconnectTimeout !== defaultBrowserDisconnectTimeout) ? browserDisconnectTimeout : 5;
-  }
+    return browserDisconnectTimeout !== defaultBrowserDisconnectTimeout
+      ? browserDisconnectTimeout
+      : 5;
+  },
 };
 
 module.exports = Config;

package/lib/file_watcher.js

@@ -1,51 +1,125 @@
+const EventEmitter = require('events').EventEmitter;
 
+const Impl = require('./file_watcher_impl');
 
-const fireworm = require('fireworm');
-const EventEmitter = require('events').EventEmitter;
+const kCompose = Symbol('FileWatcher.compose');
 
-module.exports = class FileWatcher extends EventEmitter {
-  constructor(config) {
+/**
+ * Coordinates file watching for Testem: it observes the current working directory (and any
+ * non-glob paths from config that live outside it), applies the same include / ignore rules as
+ * the rest of the app (`src_files`, `src_files_ignore`, `watch_files`, etc.), and reports when
+ * paths that matter for the test run change.
+ *
+ * Listen for {@link FileWatcher#event:fileChanged} to react to changes, and optionally for
+ * {@link FileWatcher#event:EMFILE} when the process hits open-file limits.
+ *
+ * ### Construction
+ *
+ * **Do not call `new FileWatcher(...)`.** The constructor is not part of the public API; it
+ * exists only for internal wiring and will always throw if you invoke it from outside this
+ * module. Obtain instances exclusively via {@link FileWatcher.create} with a config object that
+ * exposes `get(key)` and `isCwdMode()` (the same shape as Testem’s `Config`).
+ *
+ * ### Async vs synchronous
+ *
+ * **Return a `Promise` — use `await`, `.then()`, or `.catch()`:**
+ * {@link FileWatcher.create}, {@link FileWatcher#add}, {@link FileWatcher#close}.
+ *
+ * **Synchronous:** {@link FileWatcher#onFileChanged}, {@link FileWatcher#onEMFILE}, and
+ * inherited `EventEmitter` methods (`on`, `once`, `emit`, `removeListener`, …).
+ *
+ * @hideconstructor
+ * @fires FileWatcher#event:fileChanged
+ * @fires FileWatcher#event:EMFILE
+ */
+class FileWatcher extends EventEmitter {
+  /**
+   * Not for public use. Application code must use {@link FileWatcher.create} instead; calling
+   * `new FileWatcher` directly always throws.
+   *
+   * @private
+   * @param {*} impl Internal implementation instance.
+   * @param {symbol} token Internal composition token (not exposed).
+   */
+  constructor(impl, token) {
     super();
+    if (token !== kCompose) {
+      throw new TypeError(
+        'FileWatcher is not constructable; use FileWatcher.create(config)',
+      );
+    }
+    this._impl = impl;
+    impl.on('fileChanged', (filePath) => this.emit('fileChanged', filePath));
+    impl.on('EMFILE', () => this.emit('EMFILE'));
+  }
 
-    this.fileWatcher = fireworm('./', {
-      ignoreInitial: true,
-      skipDirEntryPatterns: []
+  /**
+   * Create a watcher, wait until the underlying engine has finished its initial setup, and
+   * return a ready-to-use `FileWatcher`. This is the **only** supported way to obtain an
+   * instance.
+   *
+   * @param {{ get: function(string): *, isCwdMode: function(): boolean }} config Testem-style
+   *   config (typically a `Config` instance): `get` reads keys such as `src_files`,
+   *   `src_files_ignore`, `watch_files`, `file`, `disable_watching`; `isCwdMode` reflects cwd
+   *   mode.
+   * @returns {Promise<FileWatcher>} Resolves with a connected watcher once startup is complete.
+   *   **Await** this promise; if the engine fails during startup, the promise rejects.
+   */
+  static async create(config) {
+    const impl = await Impl.create(config);
+    return new FileWatcher(impl, kCompose);
+  }
+
+  /**
+   * Request that a **concrete** filesystem path be watched in addition to the configured
+   * patterns (for example, a file the dev server started serving after startup). Glob or
+   * minimatch strings are not accepted here — only real paths; pattern-based includes stay in
+   * config.
+   *
+   * @param {string} file Path relative to the current working directory or absolute, as
+   *   accepted by the engine.
+   * @returns {Promise<void>} Settles when the engine has finished the add request. **Await**
+   *   this promise (or attach `.catch()`) so validation errors, engine errors, and internal
+   *   teardown on failure are observed.
+   */
+  add(file) {
+    return this._impl.add(file);
+  }
+
+  /**
+   * Tear down the watcher: close the engine, release OS watch handles, and remove listeners on
+   * this `FileWatcher`. Safe to call more than once; subsequent calls resolve promptly.
+   *
+   * @returns {Promise<void>} Resolves when shutdown is complete. **Await** if later code must
+   *   run only after handles are released.
+   */
+  close() {
+    return Promise.resolve(this._impl.close()).then(() => {
+      this.removeAllListeners();
     });
-    let onFileChanged = this.onFileChanged.bind(this);
-    this.fileWatcher.on('change', onFileChanged);
-    this.fileWatcher.on('add', onFileChanged);
-    this.fileWatcher.on('remove', onFileChanged);
-    this.fileWatcher.on('emfile', this.onEMFILE.bind(this));
-
-    let watchFiles = config.get('watch_files');
-    this.fileWatcher.clear();
-    let confFile = config.get('file');
-    if (confFile) {
-      this.fileWatcher.add(confFile);
-    }
-    if (config.isCwdMode()) {
-      this.fileWatcher.add('*.js');
-    }
-    if (watchFiles) {
-      this.fileWatcher.add(watchFiles);
-    }
-    let srcFiles = config.get('src_files') || '*.js';
-    this.fileWatcher.add(srcFiles);
-    let ignoreFiles = config.get('src_files_ignore');
-    if (ignoreFiles) {
-      this.fileWatcher.ignore(ignoreFiles);
-    }
   }
 
+  /**
+   * Manually signal that a path changed, for the same listeners as a real `fileChanged` event.
+   * Used in tests and narrow control flows; normal file edits are reported automatically by the
+   * engine.
+   *
+   * @param {string} filePath Path that should be treated as changed.
+   * @returns {void}
+   */
   onFileChanged(filePath) {
-    this.emit('fileChanged', filePath);
+    return this._impl.onFileChanged(filePath);
   }
 
+  /**
+   * Manually emit the `EMFILE` condition (too many open files) for listeners that show user
+   * guidance. The real engine also surfaces this when appropriate.
+   *
+   * @returns {void}
+   */
   onEMFILE() {
-    this.emit('EMFILE');
+    return this._impl.onEMFILE();
   }
+}
 
-  add(file) {
-    this.fileWatcher.add(file);
-  }
-};
+module.exports = FileWatcher;