testem 3.19.1 → 3.20.1

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;

package/lib/file_watcher_impl.js

@@ -0,0 +1,295 @@
+/**
+ * Internal `FileWatcher` implementation (see {@link module:lib/file_watcher} for the public API).
+ *
+ * **Third-party pieces in use today:** `chokidar` (filesystem watch engine), `glob` (`hasMagic`
+ * for validating concrete `add` paths), and `minimatch` (include-pattern magic checks). Policy
+ * lists and matching live largely in {@link module:lib/utils/file_watch_glob_policy}.
+ *
+ * Nothing here assumes a single vendor forever: the engine is created only through
+ * {@link FileWatcherImpl.createWatcher} (with `chokidar` loaded lazily there), and glob/minimatch
+ * are confined to small helpers—so swapping the watcher, glob detection, or minimatch usage is
+ * meant to be localized work rather than a rewrite.
+ *
+ * @module lib/file_watcher_impl
+ */
+const path = require('path');
+const EventEmitter = require('events').EventEmitter;
+const { hasMagic } = require('glob');
+const { Minimatch } = require('minimatch');
+
+const isEmfileError = require('./utils/is_emfile_error');
+const { convertToPosix } = require('./utils/posix');
+const {
+  buildWatchGlobPolicy,
+  pathMatchesWatchTarget,
+} = require('./utils/file_watch_glob_policy');
+
+/** @private Only {@link FileWatcherImpl.create} may construct instances. */
+const kInternal = Symbol('FileWatcherImpl.internal');
+
+function includePatternHasGlobMagic(pattern) {
+  return new Minimatch(pattern, { dot: true }).hasMagic();
+}
+
+function resolvedPathIsUnderCwd(resolved) {
+  const rel = path.relative(process.cwd(), resolved);
+  return rel !== '' && !rel.startsWith('..') && !path.isAbsolute(rel);
+}
+
+/**
+ * Whether the watch engine's `all` event (add/addDir) refers to the same path as `file` /
+ * `absTarget`.
+ */
+function dynamicAddEventMatchesPath(watchedPath, file, absTarget) {
+  const absWatched = path.resolve(watchedPath);
+  const relWatched = convertToPosix(
+    path.relative(process.cwd(), absWatched),
+  );
+  const relTarget = convertToPosix(
+    path.relative(process.cwd(), absTarget),
+  );
+  return (
+    absWatched === absTarget ||
+    relWatched === relTarget ||
+    watchedPath === file
+  );
+}
+
+class FileWatcherImpl extends EventEmitter {
+  /**
+   * @param {{ get: function(string): *, isCwdMode: function(): boolean }} config
+   * @param {symbol} internalToken
+   */
+  constructor(config, internalToken) {
+    super();
+
+    if (internalToken !== kInternal) {
+      throw new TypeError(
+        'FileWatcherImpl is not constructable; use FileWatcherImpl.create(config)',
+      );
+    }
+
+    const policy = buildWatchGlobPolicy(config);
+    this._watchPolicy = policy;
+    this._explicitWatchRelPaths = new Set();
+    const opts = { ignoreInitial: true };
+    if (policy.ignorePatterns.length) {
+      opts.ignored = policy.ignorePatterns;
+    }
+
+    this.fileWatcher = FileWatcherImpl.createWatcher('.', opts);
+
+    let readySettled = false;
+    this._readyPromise = new Promise((resolve, reject) => {
+      this.fileWatcher.once('ready', () => {
+        readySettled = true;
+        resolve();
+      });
+      this.fileWatcher.once('error', (err) => {
+        if (readySettled || isEmfileError(err)) {
+          return;
+        }
+        readySettled = true;
+        reject(err);
+      });
+    });
+
+    for (let i = 0; i < policy.includePatterns.length; i++) {
+      const pattern = policy.includePatterns[i];
+      if (includePatternHasGlobMagic(pattern)) {
+        continue;
+      }
+      const resolved = path.resolve(process.cwd(), pattern);
+      if (!resolvedPathIsUnderCwd(resolved)) {
+        this.fileWatcher.add(path.normalize(pattern));
+      }
+    }
+
+    const onEngineFsEvent = this.onEngineFsEvent.bind(this);
+    this.fileWatcher.on('change', onEngineFsEvent);
+    this.fileWatcher.on('add', onEngineFsEvent);
+    this.fileWatcher.on('unlink', onEngineFsEvent);
+    this.fileWatcher.on('unlinkDir', onEngineFsEvent);
+    this.fileWatcher.on('error', (err) => {
+      if (isEmfileError(err)) {
+        this.onEMFILE();
+      }
+    });
+  }
+
+  /**
+   * @param {{ get: function(string): *, isCwdMode: function(): boolean }} config
+   * @returns {Promise<FileWatcherImpl>}
+   */
+  static async create(config) {
+    const fw = new FileWatcherImpl(config, kInternal);
+    await fw._readyPromise;
+    return fw;
+  }
+
+  onEngineFsEvent(filePath) {
+    const resolved = path.resolve(filePath);
+    const posixRel = convertToPosix(
+      path.relative(process.cwd(), resolved),
+    );
+    if (
+      pathMatchesWatchTarget(posixRel, this._watchPolicy) ||
+      this._explicitWatchRelPaths.has(posixRel)
+    ) {
+      this.onFileChanged(filePath);
+    }
+  }
+
+  onFileChanged(filePath) {
+    this.emit('fileChanged', filePath);
+  }
+
+  onEMFILE() {
+    this.emit('EMFILE');
+  }
+
+  /**
+   * @param {Error} err
+   * @returns {Promise<never>}
+   */
+  async _closeAfterFailedAdd(err) {
+    try {
+      await this.close();
+    } catch {
+      // ignore close errors; primary error is `err`
+    }
+    throw err;
+  }
+
+  /**
+   * @param {string} file
+   * @returns {Promise<void>}
+   */
+  async _validateConcreteAddPath(file) {
+    if (typeof file !== 'string') {
+      await this._closeAfterFailedAdd(
+        new TypeError('FileWatcher.add expects a string path'),
+      );
+    }
+    if (file.length === 0) {
+      await this._closeAfterFailedAdd(
+        new TypeError('FileWatcher.add expects a non-empty path'),
+      );
+    }
+    if (hasMagic(file, { magicalBraces: true })) {
+      await this._closeAfterFailedAdd(
+        new TypeError(
+          'FileWatcher.add does not accept glob patterns; pass a concrete file path: ' +
+            file,
+        ),
+      );
+    }
+  }
+
+  /**
+   * Wait for dynamic `add` on the engine to settle (`all` add/addDir, `error`, or timeout).
+   *
+   * @param {string} file
+   * @returns {Promise<void>}
+   */
+  async _awaitEngineDynamicAdd(file) {
+    const engine = this.fileWatcher;
+    const absTarget = path.resolve(process.cwd(), file);
+    let onError;
+    let onAll;
+    let timeoutId;
+
+    const cleanup = () => {
+      if (onError) {
+        engine.removeListener('error', onError);
+      }
+      if (onAll) {
+        engine.removeListener('all', onAll);
+      }
+      if (timeoutId !== undefined) {
+        clearTimeout(timeoutId);
+      }
+    };
+
+    await new Promise((resolve, reject) => {
+      let settled = false;
+
+      const finish = (err) => {
+        if (settled) {
+          return;
+        }
+        settled = true;
+        cleanup();
+        if (err) {
+          reject(err);
+        } else {
+          resolve();
+        }
+      };
+
+      onError = (err) => {
+        finish(err);
+      };
+      engine.prependOnceListener('error', onError);
+
+      onAll = (event, watchedPath) => {
+        if (event === 'add' || event === 'addDir') {
+          if (dynamicAddEventMatchesPath(watchedPath, file, absTarget)) {
+            finish();
+          }
+        }
+      };
+      engine.on('all', onAll);
+
+      timeoutId = setTimeout(() => finish(), 1000);
+
+      try {
+        engine.add(file);
+      } catch (err) {
+        finish(err);
+      }
+    });
+  }
+
+  /**
+   * @param {string} file
+   * @returns {Promise<void>}
+   */
+  async add(file) {
+    await this._validateConcreteAddPath(file);
+    const rel = convertToPosix(
+      path.relative(
+        process.cwd(),
+        path.resolve(process.cwd(), file),
+      ),
+    );
+    this._explicitWatchRelPaths.add(rel);
+    try {
+      await this._awaitEngineDynamicAdd(file);
+    } catch (err) {
+      await this._closeAfterFailedAdd(err);
+    }
+  }
+
+  /**
+   * @returns {Promise<void>}
+   */
+  close() {
+    if (this.fileWatcher) {
+      const engine = this.fileWatcher;
+      this.fileWatcher = null;
+      return Promise.resolve(engine.close()).then(() => {
+        this.removeAllListeners();
+      });
+    }
+    this.removeAllListeners();
+    return Promise.resolve();
+  }
+}
+
+/** Lazy `require` keeps chokidar off the load path until a real watcher is built (e.g. tests stub this). */
+FileWatcherImpl.createWatcher = function createWatcher(rootPath, opts) {
+  return require('chokidar').watch(rootPath, opts);
+};
+
+module.exports = FileWatcherImpl;

package/lib/launcher.js

@@ -1,16 +1,12 @@
-
-
 const log = require('./log');
-const tmp = require('tmp');
+const fs = require('fs');
 const path = require('path');
 const { fromCallback } = require('./utils/promises');
+const { registerCleanup } = require('./utils/tmp-cleanup');
 
 const template = require('./utils/strutils').template;
 const ProcessCtl = require('./process-ctl');
 
-// setup graceful cleanup: removes the created directories when an uncaught exception occurs.
-tmp.setGracefulCleanup();
-
 module.exports = class Launcher {
   constructor(name, settings, config) {
     this.name = name;
@@ -126,12 +122,11 @@ module.exports = class Launcher {
 
   setupBrowserTmpDir() {
     const userDataDir = this.config.getUserDataDir();
-    const tmpPath = path.join(userDataDir, 'testem-' + this.id);
+    const tmpPath = path.join(userDataDir, 'testem-' + this.id + '-');
 
-    this.browserTmpDirectory = tmp.dirSync({
-      template: `${tmpPath}-XXXXXX`,
-      unsafeCleanup: true
-    });
+    const dir = fs.mkdtempSync(tmpPath);
+    registerCleanup(dir);
+    this.browserTmpDirectory = dir;
   }
 
   browserTmpDir() {
@@ -139,6 +134,6 @@ module.exports = class Launcher {
       this.setupBrowserTmpDir();
     }
 
-    return this.browserTmpDirectory.name;
+    return this.browserTmpDirectory;
   }
 };