test_runner: add t.after() hook

This commit adds an after() hook to the TestContext class. This
hook can be used to clean up after a test finishes.

PR-URL: nodejs#45792
Reviewed-By: Moshe Atlow <[email protected]>
Reviewed-By: Matteo Collina <[email protected]>

doc/api/test.md

@@ -1133,6 +1133,33 @@ test('top level test', async (t) => {
 });
 ```
 
+### `context.after([fn][, options])`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+* `fn` {Function|AsyncFunction} The hook function. The first argument
+  to this function is a [`TestContext`][] object. If the hook uses callbacks,
+  the callback function is passed as the second argument. **Default:** A no-op
+  function.
+* `options` {Object} Configuration options for the hook. The following
+  properties are supported:
+  * `signal` {AbortSignal} Allows aborting an in-progress hook.
+  * `timeout` {number} A number of milliseconds the hook will fail after.
+    If unspecified, subtests inherit this value from their parent.
+    **Default:** `Infinity`.
+
+This function is used to create a hook that runs after the current test
+finishes.
+
+```js
+test('top level test', async (t) => {
+  t.after((t) => t.diagnostic(`finished running ${t.name}`));
+  assert.ok('some relevant assertion here');
+});
+```
+
 ### `context.afterEach([fn][, options])`
 
 <!-- YAML

lib/internal/test_runner/test.js

@@ -136,6 +136,10 @@ class TestContext {
     return subtest.start();
   }
 
+  after(fn, options) {
+    this.#test.createHook('after', fn, options);
+  }
+
   beforeEach(fn, options) {
     this.#test.createHook('beforeEach', fn, options);
   }
@@ -545,6 +549,7 @@ class Test extends AsyncResource {
         return;
       }
 
+      await this.runHook('after', { args, ctx });
       await afterEach();
       this.pass();
     } catch (err) {

test/message/test_runner_hooks.js

@@ -90,6 +90,8 @@ describe('afterEach throws and test fails', () => {
 
 test('test hooks', async (t) => {
   const testArr = [];
+
+  t.after(common.mustCall((t) => testArr.push('after ' + t.name)));
   t.beforeEach((t) => testArr.push('beforeEach ' + t.name));
   t.afterEach((t) => testArr.push('afterEach ' + t.name));
   await t.test('1', () => testArr.push('1'));
@@ -113,26 +115,30 @@ test('test hooks', async (t) => {
 });
 
 test('t.beforeEach throws', async (t) => {
+  t.after(common.mustCall());
   t.beforeEach(() => { throw new Error('beforeEach'); });
   await t.test('1', () => {});
   await t.test('2', () => {});
 });
 
 test('t.afterEach throws', async (t) => {
+  t.after(common.mustCall());
   t.afterEach(() => { throw new Error('afterEach'); });
   await t.test('1', () => {});
   await t.test('2', () => {});
 });
 
 
 test('afterEach when test fails', async (t) => {
+  t.after(common.mustCall());
   t.afterEach(common.mustCall(2));
   await t.test('1', () => { throw new Error('test'); });
   await t.test('2', () => {});
 });
 
 test('afterEach throws and test fails', async (t) => {
-  afterEach(() => { throw new Error('afterEach'); });
+  t.after(common.mustCall());
+  t.afterEach(() => { throw new Error('afterEach'); });
   await t.test('1', () => { throw new Error('test'); });
   await t.test('2', () => {});
 });