[heft-node-test-plugin] Introduce heft-node-test-plugin

heft-plugins/heft-node-test-plugin/README.md

@@ -0,0 +1,12 @@
+# @rushstack/heft-node-test-plugin
+
+This is a Heft plugin for using the Node.js test runner.
+
+## Links
+
+- [CHANGELOG.md](
+  https://github.com/microsoft/rushstack/blob/main/heft-plugins/heft-node-test-plugin/CHANGELOG.md) - Find
+  out what's new in the latest version
+- [@rushstack/heft](https://www.npmjs.com/package/@rushstack/heft) - Heft is a config-driven toolchain that invokes popular tools such as TypeScript, ESLint, Jest, Webpack, and API Extractor.
+
+Heft is part of the [Rush Stack](https://rushstack.io/) family of projects.

heft-plugins/heft-node-test-plugin/config/api-extractor.json

@@ -0,0 +1,16 @@
+{
+  "$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
+
+  "mainEntryPointFilePath": "<projectFolder>/lib/index.d.ts",
+  "apiReport": {
+    "enabled": true,
+    "reportFolder": "../../../common/reviews/api"
+  },
+  "docModel": {
+    "enabled": false
+  },
+  "dtsRollup": {
+    "enabled": true,
+    "betaTrimmedFilePath": "<projectFolder>/dist/<unscopedPackageName>.d.ts"
+  }
+}

heft-plugins/heft-node-test-plugin/config/rig.json

@@ -0,0 +1,7 @@
+{
+  // The "rig.json" file directs tools to look for their config files in an external package.
+  // Documentation for this system: https://www.npmjs.com/package/@rushstack/rig-package
+  "$schema": "https://developer.microsoft.com/json-schemas/rig-package/rig.schema.json",
+
+  "rigPackageName": "@rushstack/heft-node-rig"
+}

heft-plugins/heft-node-test-plugin/heft-plugin.json

@@ -0,0 +1,20 @@
+{
+  "$schema": "https://developer.microsoft.com/json-schemas/heft/v0/heft-plugin.schema.json",
+
+  "taskPlugins": [
+    {
+      "pluginName": "node-test-plugin",
+      "entryPoint": "./lib/NodeTestPlugin",
+      "optionsSchema": "./lib/schemas/node-test.schema.json",
+
+      "parameterScope": "node-test",
+      "parameters": [
+        {
+          "longName": "--update-snapshots",
+          "parameterKind": "flag",
+          "description": "Update test snapshots instead of comparing against them."
+        }
+      ]
+    }
+  ]
+}

heft-plugins/heft-node-test-plugin/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@rushstack/heft-node-test-plugin",
+  "version": "0.0.0",
+  "description": "Heft plugin for running Node.js tests with snapshot support",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/microsoft/rushstack.git",
+    "directory": "heft-plugins/heft-node-test-plugin"
+  },
+  "homepage": "https://rushstack.io/pages/heft/overview/",
+  "main": "lib/index.js",
+  "types": "dist/heft-node-test-plugin.d.ts",
+  "license": "MIT",
+  "scripts": {
+    "build": "heft build --clean",
+    "_phase:build": "heft run --only build -- --clean",
+    "_phase:test": "heft run --only test -- --clean"
+  },
+  "peerDependencies": {
+    "@rushstack/heft": "^0.75.0"
+  },
+  "dependencies": {
+    "@rushstack/node-core-library": "5.17.0"
+  },
+  "devDependencies": {
+    "@rushstack/heft": "1.1.1",
+    "@rushstack/heft-node-rig": "2.10.2",
+    "@types/node": "24.0.12"
+  }
+}

heft-plugins/heft-node-test-plugin/src/NodeTestPlugin.ts

@@ -0,0 +1,157 @@
+// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
+// See LICENSE in the project root for license information.
+
+import child_process from 'node:child_process';
+import path from 'node:path';
+import { FileSystem, JsonFile } from '@rushstack/node-core-library';
+import type {
+  HeftConfiguration,
+  IHeftTaskPlugin,
+  IHeftTaskRunHookOptions,
+  IHeftTaskSession
+} from '@rushstack/heft';
+
+/** @alpha */
+export interface INodeTestPluginOptions {
+  testPattern?: string | undefined;
+}
+
+interface INodeTestConfiguration {
+  testPattern?: string;
+}
+
+const PLUGIN_NAME: 'node-test-plugin' = 'node-test-plugin';
+const UPDATE_SNAPSHOTS_PARAMETER_LONG_NAME: '--update-snapshots' = '--update-snapshots';
+const DEFAULT_TEST_PATTERN: string = 'test/**/*.test.mjs';
+const CONFIG_FILE_NAME: string = 'node-test.json';
+
+/**
+ * @internal
+ */
+export default class NodeTestPlugin implements IHeftTaskPlugin<INodeTestPluginOptions> {
+  private _updateSnapshots: boolean = false;
+
+  public apply(
+    taskSession: IHeftTaskSession,
+    heftConfiguration: HeftConfiguration,
+    options: INodeTestPluginOptions = {}
+  ): void {
+    this._updateSnapshots = taskSession.parameters.getFlagParameter(
+      UPDATE_SNAPSHOTS_PARAMETER_LONG_NAME
+    ).value;
+
+    taskSession.hooks.run.tapPromise(PLUGIN_NAME, async (runOptions: IHeftTaskRunHookOptions) => {
+      await this._runNodeTestAsync(taskSession, heftConfiguration, options, runOptions.abortSignal);
+    });
+  }
+
+  private async _loadConfigurationAsync(
+    heftConfiguration: HeftConfiguration,
+    options: INodeTestPluginOptions
+  ): Promise<INodeTestConfiguration> {
+    // Try to load configuration from config/node-test.json
+    const configPath: string = path.join(
+      heftConfiguration.buildFolderPath,
+      'config',
+      CONFIG_FILE_NAME
+    );
+
+    let config: INodeTestConfiguration = {};
+    if (await FileSystem.existsAsync(configPath)) {
+      config = await JsonFile.loadAsync(configPath);
+    }
+
+    // Options passed via heft.json take precedence
+    if (options.testPattern) {
+      config.testPattern = options.testPattern;
+    }
+
+    return config;
+  }
+
+  private async _runNodeTestAsync(
+    taskSession: IHeftTaskSession,
+    heftConfiguration: HeftConfiguration,
+    options: INodeTestPluginOptions,
+    abortSignal: AbortSignal
+  ): Promise<void> {
+    const config: INodeTestConfiguration = await this._loadConfigurationAsync(
+      heftConfiguration,
+      options
+    );
+
+    const testPattern: string = config.testPattern || DEFAULT_TEST_PATTERN;
+
+    taskSession.logger.terminal.writeLine(`Running Node.js tests with pattern: ${testPattern}`);
+
+    if (this._updateSnapshots) {
+      taskSession.logger.terminal.writeLine('Updating snapshots...');
+    }
+
+    await this._executeNodeTest(
+      heftConfiguration.buildFolderPath,
+      testPattern,
+      this._updateSnapshots,
+      abortSignal,
+      taskSession
+    );
+  }
+
+  private async _executeNodeTest(
+    buildFolderPath: string,
+    testPattern: string,
+    updateSnapshots: boolean,
+    abortSignal: AbortSignal,
+    taskSession: IHeftTaskSession
+  ): Promise<void> {
+    return new Promise<void>((resolve, reject) => {
+      // Build the node test runner arguments
+      const args: string[] = ['--test', '--test-reporter', 'spec'];
+
+      if (updateSnapshots) {
+        args.push('--test-update-snapshots');
+      }
+
+      // Add the test pattern
+      args.push(testPattern);
+
+      taskSession.logger.terminal.writeDebugLine(`Executing: node ${args.join(' ')}`);
+
+      const child = child_process.spawn('node', args, {
+        stdio: ['inherit', 'inherit', 'inherit'],
+        cwd: buildFolderPath,
+        env: process.env
+      });
+
+      // Handle abort signal
+      const abortHandler = (): void => {
+        child.kill('SIGTERM');
+      };
+
+      if (abortSignal.aborted) {
+        child.kill('SIGTERM');
+        reject(new Error('Operation aborted'));
+        return;
+      }
+
+      abortSignal.addEventListener('abort', abortHandler);
+
+      child.on('error', (error) => {
+        abortSignal.removeEventListener('abort', abortHandler);
+        reject(new Error(`Failed to spawn Node.js test process: ${error.message}`));
+      });
+
+      child.on('exit', (code, signal) => {
+        abortSignal.removeEventListener('abort', abortHandler);
+        if (signal === 'SIGTERM' && abortSignal.aborted) {
+          reject(new Error('Operation aborted'));
+        } else if (code === 0) {
+          taskSession.logger.terminal.writeLine('Tests completed successfully.');
+          resolve();
+        } else {
+          reject(new Error(`Node.js test process exited with code ${code}`));
+        }
+      });
+    });
+  }
+}

heft-plugins/heft-node-test-plugin/src/index.ts

@@ -0,0 +1,5 @@
+// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
+// See LICENSE in the project root for license information.
+
+export { default as NodeTestPlugin } from './NodeTestPlugin';
+export type { INodeTestPluginOptions } from './NodeTestPlugin';

heft-plugins/heft-node-test-plugin/src/schemas/node-test.schema.json

@@ -0,0 +1,20 @@
+{
+  "$schema": "http://json-schema.org/draft-04/schema#",
+  "title": "Node Test Plugin Configuration",
+  "description": "Defines options for Node.js test runner plugin execution.",
+  "type": "object",
+
+  "additionalProperties": false,
+
+  "properties": {
+    "$schema": {
+      "description": "Part of the JSON Schema standard, this optional keyword declares the URL of the schema that the file conforms to. Editors may download the schema and use it to perform syntax highlighting.",
+      "type": "string"
+    },
+
+    "testPattern": {
+      "description": "A glob pattern for test files to run. Default is \"test/**/*.test.mjs\".",
+      "type": "string"
+    }
+  }
+}

heft-plugins/heft-node-test-plugin/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "extends": "./node_modules/@rushstack/heft-node-rig/profiles/default/tsconfig-base.json",
+  "compilerOptions": {
+    "skipLibCheck": true,
+    "resolveJsonModule": true,
+    "types": ["node"]
+  }
+}