@aria-framework/testkit 0.2.0 → 0.3.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@aria-framework/testkit",
   "description": "Aria App Framework \u2014 test infrastructure. The \u2713/\u2717 micro test-harness (createHarness, with the async-callback guard that stops a suite silently passing), assertImportsInScope (every consumer of a module has every function it calls in scope), and assertVersionSingleSource (package.json vs derived version files vs the lockfile's two copies). Dev-dependency only: nothing here belongs in a production install.",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "license": "UNLICENSED",
   "private": false,
   "publishConfig": {

package/tempDb.js

@@ -54,6 +54,44 @@ function removeAll(base) {
   }
 }
 
+/**
+ * Run a caller's close hook, and refuse to be lied to about it.
+ *
+ * AN EXIT HANDLER CANNOT AWAIT. So a `close` that returns a promise has not closed anything by the
+ * time the unlink runs, and on Windows that unlink then fails with EBUSY into a catch nobody reads.
+ * The copy is left behind and the suite still passes — which is precisely the shape of bug this
+ * whole module exists to end, arriving through the mechanism meant to prevent it.
+ *
+ * It is worse than a plain failure because an async close can APPEAR to work: `async close() {
+ * db.close(); }` runs its body up to the first await synchronously, so a driver written that way
+ * cleans up perfectly until somebody adds an await ahead of that line, or the app moves to a driver
+ * whose close is genuinely asynchronous. Then every leftover returns, silently, and the commit that
+ * introduced the regression is nowhere near the code that breaks.
+ *
+ * So: say so, loudly, on the one occasion it can still be heard.
+ */
+function closeSynchronously(close, file) {
+  if (typeof close !== 'function') return;
+  let result;
+  try {
+    result = close();
+  } catch (e) {
+    // A synchronous throw is fine — already closed, or never opened. The delete still runs.
+    return;
+  }
+  if (result && typeof result.then === 'function') {
+    // Not swallowed: this is the only moment anybody could learn about it.
+    // eslint-disable-next-line no-console
+    console.error(
+      `testkit: the close hook for ${path.basename(file)} returned a promise. An exit handler `
+      + 'cannot await, so the database is still open when the file is deleted — on Windows that '
+      + 'fails silently and the copy is left behind. Pass a SYNCHRONOUS close: '
+      + 'the driver' + String.fromCharCode(39) + 's own db.close() usually is one, even when the wrapper is not.');
+    // ...and do not let it become an unhandled rejection on the way out.
+    result.then(undefined, () => {});
+  }
+}
+
 /**
  * Copy `livePath` to a private temp file and return its path.
  *
@@ -63,6 +101,8 @@ function removeAll(base) {
  *   dir       where to put it; defaults to the OS temp directory
  *   prefix    default 'app' — apps pass their own so two projects cannot collide
  *   cleanup   default true; false leaves the copy behind for inspection after a failure
+ *   allowMissing  default false; true means an absent live database copies nothing rather
+ *             than throwing, for a test that builds its schema from migrations
  *   close     optional () => void, run before deleting. On Windows an open handle makes unlink
  *             fail with EBUSY, so without this the exit hook is a no-op for any test that does not
  *             close its database — which is most of them.
@@ -70,7 +110,17 @@ function removeAll(base) {
 function copyDatabase(o = {}) {
   const live = o.livePath;
   if (!live) throw new Error('copyDatabase({ livePath }): the database to copy is required');
-  if (!fs.existsSync(live)) throw new Error(`copyDatabase: there is no database at ${live}`);
+  // STRICT BY DEFAULT. A test that quietly ran against an empty database when it meant to use real
+  // data is its own kind of wrong, and silent is the worst way for that to happen. But a suite that
+  // BUILDS its schema from migrations is legitimately fine without one, and the hand-rolled loop
+  // this replaced tolerated it — `if (exists) copy` simply copied nothing. On a fresh clone, or a CI
+  // box that has never booted the app, strictness alone turns those tests into a module-scope crash.
+  const missing = !fs.existsSync(live);
+  if (missing && !o.allowMissing) {
+    throw new Error(
+      `copyDatabase: there is no database at ${live}. Pass allowMissing:true if this test builds `
+      + 'its own schema and does not need one.');
+  }
 
   const label = String(o.name || 'test').replace(/[^a-z0-9-]+/gi, '-');
   const copy = path.join(o.dir || os.tmpdir(),
@@ -80,9 +130,11 @@ function copyDatabase(o = {}) {
   removeAll(copy);
 
   // 2. ...then the live database and whichever sidecars it actually has.
-  for (const suffix of SUFFIXES) {
-    const src = live + suffix;
-    if (fs.existsSync(src)) fs.copyFileSync(src, copy + suffix);
+  if (!missing) {
+    for (const suffix of SUFFIXES) {
+      const src = live + suffix;
+      if (fs.existsSync(src)) fs.copyFileSync(src, copy + suffix);
+    }
   }
 
   // 3. And take it away afterwards. Best effort by nature: a process that is killed runs no exit
@@ -91,9 +143,7 @@ function copyDatabase(o = {}) {
     process.on('exit', () => {
       // CLOSE BEFORE DELETING, where the caller can. Windows refuses to unlink an open file, and
       // this handler runs with the database still open unless something closes it.
-      if (typeof o.close === 'function') {
-        try { o.close(); } catch (e) { /* already closed, or never opened */ }
-      }
+      closeSynchronously(o.close, copy);
       removeAll(copy);
     });
   }
@@ -118,9 +168,7 @@ function freshDatabase(o = {}) {
   removeAll(file);
   if (o.cleanup !== false) {
     process.on('exit', () => {
-      if (typeof o.close === 'function') {
-        try { o.close(); } catch (e) { /* already closed, or never opened */ }
-      }
+      closeSynchronously(o.close, file);
       removeAll(file);
     });
   }