refactor: add Jest test execution to Jest builder

This runs Jest on the outputs of the built test files and reports the results of the test execution. It depends on `jest` and `jest-environment-jsdom` as optional peer deps validated in the builder, so there isn't a strict dependency on Jest for applications which don't use it.

Jest exports a `runJest()` function, however it can't be used directly because we need to opt-in to `--experimental-vm-modules` in ordre to run Jest on native ESM JavaScript as produced by `browser-esbuild`. This means we need a Node subprocess in order to add this flag, because the `ng` command cannot add a Node flag to its own current execution. This unfortunately means we can't just `import * as jest from 'jest';` or even `require.resolve('jest')` because that returns the library entry point exporting `runJest()`, rather than a script which actually runs Jest on load. Fortunately, Jest exports it's `node_modules/.bin/jest` entry point from its `package.json` under `jest/bin/jest`, so we `require.resolve()` _that_ to get the path to the correct file.

Executing Jest is fairly straightforward, running on the output of the `browser-esbuild` execution with outputs streamed to the console. We opted to use JSDom over Domino in order to align with the existing Jest ecosystem.

Author: dgp1130

packages/angular_devkit/build_angular/package.json

@@ -78,6 +78,8 @@
     "@angular/localize": "^16.0.0-next.0",
     "@angular/platform-server": "^16.0.0-next.0",
     "@angular/service-worker": "^16.0.0-next.0",
+    "jest": "^29.5.0",
+    "jest-environment-jsdom": "^29.5.0",
     "karma": "^6.3.0",
     "ng-packagr": "^16.0.0-next.1",
     "protractor": "^7.0.0",
@@ -94,6 +96,12 @@
     "@angular/service-worker": {
       "optional": true
     },
+    "jest": {
+      "optional": true
+    },
+    "jest-environment-jsdom": {
+      "optional": true
+    },
     "karma": {
       "optional": true
     },

packages/angular_devkit/build_angular/src/builders/jest/index.ts

@@ -7,13 +7,19 @@
  */
 
 import { BuilderContext, BuilderOutput, createBuilder } from '@angular-devkit/architect';
+import { execFile as execFileCb } from 'child_process';
+import * as path from 'path';
+import { promisify } from 'util';
+import { colors } from '../../utils/color';
 import { buildEsbuildBrowserInternal } from '../browser-esbuild';
 import { BrowserEsbuildOptions } from '../browser-esbuild/options';
 import { OutputHashing } from '../browser-esbuild/schema';
 import { normalizeOptions } from './options';
 import { Schema as JestBuilderSchema } from './schema';
 import { findTestFiles } from './test-files';
 
+const execFile = promisify(execFileCb);
+
 /** Main execution function for the Jest builder. */
 export default createBuilder(
   async (schema: JestBuilderSchema, context: BuilderContext): Promise<BuilderOutput> => {
@@ -22,11 +28,35 @@ export default createBuilder(
     );
 
     const options = normalizeOptions(schema);
-    const testFiles = await findTestFiles(options, context.workspaceRoot);
     const testOut = 'dist/test-out'; // TODO(dgp1130): Hide in temp directory.
 
+    // Verify Jest installation and get the path to it's binary.
+    // We need to `node_modules/.bin/jest`, but there is no means to resolve that directly. Fortunately Jest's `package.json` exports the
+    // same file at `bin/jest`, so we can just resolve that instead.
+    const jest = resolveModule('jest/bin/jest');
+    if (!jest) {
+      return {
+        success: false,
+        // TODO(dgp1130): Display a more accurate message for non-NPM users.
+        error:
+          'Jest is not installed, most likely you need to run `npm install jest --save-dev` in your project.',
+      };
+    }
+
+    // Verify that JSDom is installed in the project.
+    const environment = resolveModule('jest-environment-jsdom');
+    if (!environment) {
+      return {
+        success: false,
+        // TODO(dgp1130): Display a more accurate message for non-NPM users.
+        error:
+          '`jest-environment-jsdom` is not installed. Install it with `npm install jest-environment-jsdom --save-dev`.',
+      };
+    }
+
     // Build all the test files.
-    return await build(context, {
+    const testFiles = await findTestFiles(options, context.workspaceRoot);
+    const buildResult = await build(context, {
       entryPoints: testFiles,
       tsConfig: options.tsConfig,
       polyfills: options.polyfills,
@@ -44,6 +74,53 @@ export default createBuilder(
         vendor: false,
       },
     });
+    if (!buildResult.success) {
+      return buildResult;
+    }
+
+    // Execute Jest on the built output directory.
+    const jestProc = execFile('node', [
+      '--experimental-vm-modules',
+      jest,
+
+      `--rootDir=${testOut}`,
+      '--testEnvironment=jsdom',
+
+      // TODO(dgp1130): Enable cache once we have a mechanism for properly clearing / disabling it.
+      '--no-cache',
+
+      // Run basically all files in the output directory, any excluded files were already dropped by the build.
+      `--testMatch=${path.join('<rootDir>', '**', '*.mjs')}`,
+
+      // Load polyfills before each test, and don't run them directly as a test.
+      `--setupFilesAfterEnv=${path.join('<rootDir>', 'polyfills.mjs')}`,
+      `--testPathIgnorePatterns=${path.join('<rootDir>', 'polyfills\\.mjs')}`,
+
+      // Skip shared chunks, as they are not entry points to tests.
+      `--testPathIgnorePatterns=${path.join('<rootDir>', 'chunk-.*\\.mjs')}`,
+
+      // Optionally enable color.
+      ...(colors.enabled ? ['--colors'] : []),
+    ]);
+
+    // Stream test output to the terminal.
+    jestProc.child.stdout?.on('data', (chunk) => {
+      context.logger.info(chunk);
+    });
+    jestProc.child.stderr?.on('data', (chunk) => {
+      // Write to stderr directly instead of `context.logger.error(chunk)` because the logger will overwrite Jest's coloring information.
+      process.stderr.write(chunk);
+    });
+
+    try {
+      await jestProc;
+    } catch (error) {
+      // No need to propagate error message, already piped to terminal output.
+      // TODO(dgp1130): Handle process spawning failures.
+      return { success: false };
+    }
+
+    return { success: true };
   },
 );
 
@@ -64,3 +141,12 @@ async function build(
     };
   }
 }
+
+/** Safely resolves the given Node module string. */
+function resolveModule(module: string): string | undefined {
+  try {
+    return require.resolve(module);
+  } catch {
+    return undefined;
+  }
+}

packages/angular_devkit/build_angular/src/builders/jest/schema.json

@@ -10,7 +10,7 @@
         "type": "string"
       },
       "default": ["**/*.spec.ts"],
-      "description": "Globs of files to include, relative to project root. \nThere are 2 special cases:\n - when a path to directory is provided, all spec files ending \".spec.@(ts|tsx)\" will be included\n - when a path to a file is provided, and a matching spec file exists it will be included instead."
+      "description": "Globs of files to include, relative to project root."
     },
     "exclude": {
       "type": "array",