test_runner: add before/after/each hooks

Author: MoLow

lib/internal/test_runner/harness.js

@@ -170,8 +170,19 @@ function runInParentContext(Factory) {
   return cb;
 }
 
+function hook(hook) {
+  return (fn, options) => {
+    const parent = testResources.get(executionAsyncId()) || setup(root);
+    parent.createHook(hook, fn, options);
+  };
+}
+
 module.exports = {
   test: FunctionPrototypeBind(test, root),
   describe: runInParentContext(Suite),
   it: runInParentContext(ItTest),
+  before: hook('before'),
+  after: hook('after'),
+  beforeEach: hook('beforeEach'),
+  afterEach: hook('afterEach'),
 };

lib/internal/test_runner/test.js

@@ -1,10 +1,13 @@
 'use strict';
 const {
   ArrayPrototypePush,
+  ArrayPrototypeReduce,
   ArrayPrototypeShift,
+  ArrayPrototypeSlice,
   ArrayPrototypeUnshift,
   FunctionPrototype,
   Number,
+  ObjectSeal,
   PromisePrototypeThen,
   PromiseResolve,
   ReflectApply,
@@ -20,18 +23,17 @@ const {
   codes: {
     ERR_TEST_FAILURE,
   },
-  kIsNodeError,
   AbortError,
 } = require('internal/errors');
 const { getOptionValue } = require('internal/options');
 const { TapStream } = require('internal/test_runner/tap_stream');
-const { createDeferredCallback } = require('internal/test_runner/utils');
+const { createDeferredCallback, isTetFailureError } = require('internal/test_runner/utils');
 const {
   createDeferredPromise,
   kEmptyObject,
 } = require('internal/util');
 const { isPromise } = require('internal/util/types');
-const { isUint32, validateAbortSignal } = require('internal/validators');
+const { isUint32, validateAbortSignal, validateOneOf } = require('internal/validators');
 const { setTimeout } = require('timers/promises');
 const { cpus } = require('os');
 const { bigint: hrtime } = process.hrtime;
@@ -41,6 +43,7 @@ const kParentAlreadyFinished = 'parentAlreadyFinished';
 const kSubtestsFailed = 'subtestsFailed';
 const kTestCodeFailure = 'testCodeFailure';
 const kTestTimeoutFailure = 'testTimeoutFailure';
+const kHookFailure = 'hookFailed';
 const kDefaultIndent = '    ';
 const kDefaultTimeout = null;
 const noop = FunctionPrototype;
@@ -50,6 +53,8 @@ const testOnlyFlag = !isTestRunner && getOptionValue('--test-only');
 const rootConcurrency = isTestRunner ? cpus().length : 1;
 
 const kShouldAbort = Symbol('kShouldAbort');
+const kRunHook = Symbol('kRunHook');
+const kHookNames = ObjectSeal(['before', 'after', 'beforeEach', 'afterEach']);
 
 
 function stopTest(timeout, signal) {
@@ -75,6 +80,10 @@ class TestContext {
     return this.#test.signal;
   }
 
+  get name() {
+    return this.#test.name;
+  }
+
   diagnostic(message) {
     this.#test.diagnostic(message);
   }
@@ -97,6 +106,14 @@ class TestContext {
 
     return subtest.start();
   }
+
+  beforeEach(fn, options) {
+    this.#test.createHook('beforeEach', fn, options);
+  }
+
+  afterEach(fn, options) {
+    this.#test.createHook('afterEach', fn, options);
+  }
 }
 
 class Test extends AsyncResource {
@@ -185,6 +202,12 @@ class Test extends AsyncResource {
     this.pendingSubtests = [];
     this.readySubtests = new SafeMap();
     this.subtests = [];
+    this.hooks = {
+      before: [],
+      after: [],
+      beforeEach: [],
+      afterEach: [],
+    };
     this.waitingOn = 0;
     this.finished = false;
   }
@@ -303,10 +326,19 @@ class Test extends AsyncResource {
         kCancelledByParent
       )
     );
+    this.startTime = this.startTime || this.endTime; // If a test was canceled before it was started, e.g inside a hook
     this.cancelled = true;
     this.#abortController.abort();
   }
 
+  createHook(name, fn, options) {
+    validateOneOf(name, 'hook name', kHookNames);
+    // eslint-disable-next-line no-use-before-define
+    const hook = new TestHook(fn, options);
+    ArrayPrototypePush(this.hooks[name], hook);
+    return hook;
+  }
+
   fail(err) {
     if (this.error !== null) {
       return;
@@ -370,8 +402,27 @@ class Test extends AsyncResource {
     return { ctx, args: [ctx] };
   }
 
+  async [kRunHook](hook, args) {
+    validateOneOf(hook, 'hook name', kHookNames);
+    try {
+      await ArrayPrototypeReduce(this.hooks[hook], async (prev, hook) => {
+        await prev;
+        await hook.run(args);
+        if (hook.error) {
+          throw hook.error;
+        }
+      }, PromiseResolve());
+    } catch (err) {
+      const error = new ERR_TEST_FAILURE(`failed running ${hook} hook`, kHookFailure);
+      error.cause = isTetFailureError(err) ? err.cause : err;
+      throw error;
+    }
+  }
+
   async run() {
-    this.parent.activeSubtests++;
+    if (this.parent !== null) {
+      this.parent.activeSubtests++;
+    }
     this.startTime = hrtime();
 
     if (this[kShouldAbort]()) {
@@ -380,16 +431,20 @@ class Test extends AsyncResource {
     }
 
     try {
-      const stopPromise = stopTest(this.timeout, this.signal);
       const { args, ctx } = this.getRunArgs();
-      ArrayPrototypeUnshift(args, this.fn, ctx); // Note that if it's not OK to mutate args, we need to first clone it.
+      if (this.parent?.hooks.beforeEach.length > 0) {
+        await this.parent[kRunHook]('beforeEach', { args, ctx });
+      }
+      const stopPromise = stopTest(this.timeout, this.signal);
+      const runArgs = ArrayPrototypeSlice(args);
+      ArrayPrototypeUnshift(runArgs, this.fn, ctx);
 
-      if (this.fn.length === args.length - 1) {
+      if (this.fn.length === runArgs.length - 1) {
         // This test is using legacy Node.js error first callbacks.
         const { promise, cb } = createDeferredCallback();
 
-        ArrayPrototypePush(args, cb);
-        const ret = ReflectApply(this.runInAsyncScope, this, args);
+        ArrayPrototypePush(runArgs, cb);
+        const ret = ReflectApply(this.runInAsyncScope, this, runArgs);
 
         if (isPromise(ret)) {
           this.fail(new ERR_TEST_FAILURE(
@@ -402,7 +457,7 @@ class Test extends AsyncResource {
         }
       } else {
         // This test is synchronous or using Promises.
-        const promise = ReflectApply(this.runInAsyncScope, this, args);
+        const promise = ReflectApply(this.runInAsyncScope, this, runArgs);
         await SafePromiseRace([PromiseResolve(promise), stopPromise]);
       }
 
@@ -411,9 +466,13 @@ class Test extends AsyncResource {
         return;
       }
 
+      if (this.parent?.hooks.afterEach.length > 0) {
+        await this.parent[kRunHook]('afterEach', { args, ctx });
+      }
+
       this.pass();
     } catch (err) {
-      if (err?.code === 'ERR_TEST_FAILURE' && kIsNodeError in err) {
+      if (isTetFailureError(err)) {
         this.fail(err);
       } else {
         this.fail(new ERR_TEST_FAILURE(err, kTestCodeFailure));
@@ -523,51 +582,81 @@ class Test extends AsyncResource {
   }
 }
 
+class TestHook extends Test {
+  #args;
+  constructor(fn, options) {
+    if (options === null || typeof options !== 'object') {
+      options = kEmptyObject;
+    }
+    super({ __proto__: null, fn, ...options });
+  }
+  run(args) {
+    this.#args = args;
+    return super.run();
+  }
+  getRunArgs() {
+    return this.#args;
+  }
+}
+
 class ItTest extends Test {
   constructor(opt) { super(opt); } // eslint-disable-line no-useless-constructor
   getRunArgs() {
-    return { ctx: { signal: this.signal }, args: [] };
+    return { ctx: { signal: this.signal, name: this.name }, args: [] };
   }
 }
 class Suite extends Test {
   constructor(options) {
     super(options);
 
     try {
-      const context = { signal: this.signal };
-      this.buildSuite = this.runInAsyncScope(this.fn, context, [context]);
+      const { ctx, args } = this.getRunArgs();
+      this.buildSuite = this.runInAsyncScope(this.fn, ctx, args);
     } catch (err) {
       this.fail(new ERR_TEST_FAILURE(err, kTestCodeFailure));
     }
     this.fn = () => {};
     this.buildPhaseFinished = true;
   }
 
+  getRunArgs() {
+    return { ctx: { signal: this.signal, name: this.name }, args: [] };
+  }
+
   start() {
     return this.run();
   }
 
   async run() {
     try {
       await this.buildSuite;
-    } catch (err) {
-      this.fail(new ERR_TEST_FAILURE(err, kTestCodeFailure));
-    }
-    this.parent.activeSubtests++;
-    this.startTime = hrtime();
+      this.parent.activeSubtests++;
+      this.startTime = hrtime();
 
-    if (this[kShouldAbort]()) {
-      this.subtests = [];
-      this.postRun();
-      return;
-    }
+      if (this[kShouldAbort]()) {
+        this.subtests = [];
+        this.postRun();
+        return;
+      }
+
+
+      const hookArgs = this.getRunArgs();
+      await this[kRunHook]('before', hookArgs);
+      const stopPromise = stopTest(this.timeout, this.signal);
+      const subtests = this.skipped || this.error ? [] : this.subtests;
+      const promise = SafePromiseAll(subtests, (subtests) => subtests.start());
 
-    const stopPromise = stopTest(this.timeout, this.signal);
-    const subtests = this.skipped || this.error ? [] : this.subtests;
-    const promise = SafePromiseAll(subtests, (subtests) => subtests.start());
+      await SafePromiseRace([promise, stopPromise]);
+      await this[kRunHook]('after', hookArgs);
+      this.pass();
+    } catch (err) {
+      if (isTetFailureError(err)) {
+        this.fail(err);
+      } else {
+        this.fail(new ERR_TEST_FAILURE(err, kTestCodeFailure));
+      }
+    }
 
-    await SafePromiseRace([promise, stopPromise]);
-    this.pass();
     this.postRun();
   }
 }

lib/internal/test_runner/utils.js

@@ -6,6 +6,7 @@ const {
   codes: {
     ERR_TEST_FAILURE,
   },
+  kIsNodeError,
 } = require('internal/errors');
 
 const kMultipleCallbackInvocations = 'multipleCallbackInvocations';
@@ -49,8 +50,13 @@ function createDeferredCallback() {
   return { promise, cb };
 }
 
+function isTetFailureError(err) {
+  return err?.code === 'ERR_TEST_FAILURE' && kIsNodeError in err;
+}
+
 module.exports = {
   createDeferredCallback,
   doesPathMatchFilter,
   isSupportedFileType,
+  isTetFailureError,
 };

lib/test.js

@@ -1,5 +1,5 @@
 'use strict';
-const { test, describe, it } = require('internal/test_runner/harness');
+const { test, describe, it, before, after, beforeEach, afterEach } = require('internal/test_runner/harness');
 const { emitExperimentalWarning } = require('internal/util');
 
 emitExperimentalWarning('The test runner');
@@ -8,3 +8,7 @@ module.exports = test;
 module.exports.test = test;
 module.exports.describe = describe;
 module.exports.it = it;
+module.exports.before = before;
+module.exports.after = after;
+module.exports.beforeEach = beforeEach;
+module.exports.afterEach = afterEach;

test/message/test_runner_describe_it.js

@@ -225,15 +225,15 @@ it('callback fail', (done) => {
 });
 
 it('sync t is this in test', function() {
-  assert.deepStrictEqual(this, { signal: this.signal });
+  assert.deepStrictEqual(this, { signal: this.signal, name: this.name });
 });
 
 it('async t is this in test', async function() {
-  assert.deepStrictEqual(this, { signal: this.signal });
+  assert.deepStrictEqual(this, { signal: this.signal, name: this.name });
 });
 
 it('callback t is this in test', function(done) {
-  assert.deepStrictEqual(this, { signal: this.signal });
+  assert.deepStrictEqual(this, { signal: this.signal, name: this.name });
   done();
 });