feat(@angular-devkit/build-angular): support karma with esbuild

Adds a new "builderMode" setting for Karma that can be used to switch
between webpack ("browser") and esbuild ("application"). It supports a
third value "detect" that will use the same bundler that's also used for
development builds.

The detect mode is modelled after the logic used for the dev-server builder.

This initial implementation doesn't properly support `--watch` mode or code
coverage.

Author: jkrems

goldens/public-api/angular_devkit/build_angular/index.api.md

@@ -213,6 +213,7 @@ export interface FileReplacement {
 export interface KarmaBuilderOptions {
     assets?: AssetPattern_2[];
     browsers?: Browsers;
+    builderMode?: BuilderMode;
     codeCoverage?: boolean;
     codeCoverageExclude?: string[];
     exclude?: string[];

packages/angular_devkit/build_angular/src/builders/karma/application_builder.ts

@@ -0,0 +1,299 @@
+/**
+ * @license
+ * Copyright Google LLC All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.dev/license
+ */
+
+import { BuildOutputFileType } from '@angular/build';
+import {
+  ResultFile,
+  ResultKind,
+  buildApplicationInternal,
+  emitFilesToDisk,
+  purgeStaleBuildCache,
+} from '@angular/build/private';
+import { BuilderContext, BuilderOutput } from '@angular-devkit/architect';
+import { randomUUID } from 'crypto';
+import * as fs from 'fs/promises';
+import type { Config, ConfigOptions, InlinePluginDef } from 'karma';
+import * as path from 'path';
+import { Observable, catchError, defaultIfEmpty, from, of, switchMap } from 'rxjs';
+import { Configuration } from 'webpack';
+import { ExecutionTransformer } from '../../transforms';
+import { readTsconfig } from '../../utils/read-tsconfig';
+import { OutputHashing } from '../browser-esbuild/schema';
+import { findTests } from './find-tests';
+import { Schema as KarmaBuilderOptions } from './schema';
+
+class ApplicationBuildError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'ApplicationBuildError';
+  }
+}
+
+export function execute(
+  options: KarmaBuilderOptions,
+  context: BuilderContext,
+  karmaOptions: ConfigOptions,
+  transforms: {
+    webpackConfiguration?: ExecutionTransformer<Configuration>;
+    // The karma options transform cannot be async without a refactor of the builder implementation
+    karmaOptions?: (options: ConfigOptions) => ConfigOptions;
+  } = {},
+): Observable<BuilderOutput> {
+  return from(initializeApplication(options, context, karmaOptions, transforms)).pipe(
+    switchMap(
+      ([karma, karmaConfig]) =>
+        new Observable<BuilderOutput>((subscriber) => {
+          // Complete the observable once the Karma server returns.
+          const karmaServer = new karma.Server(karmaConfig as Config, (exitCode) => {
+            subscriber.next({ success: exitCode === 0 });
+            subscriber.complete();
+          });
+
+          const karmaStart = karmaServer.start();
+
+          // Cleanup, signal Karma to exit.
+          return () => {
+            void karmaStart.then(() => karmaServer.stop());
+          };
+        }),
+    ),
+    catchError((err) => {
+      if (err instanceof ApplicationBuildError) {
+        return of({ success: false, message: err.message });
+      }
+
+      throw err;
+    }),
+    defaultIfEmpty({ success: false }),
+  );
+}
+
+async function getProjectSourceRoot(context: BuilderContext): Promise<string> {
+  // We have already validated that the project name is set before calling this function.
+  const projectName = context.target?.project;
+  if (!projectName) {
+    return context.workspaceRoot;
+  }
+
+  const projectMetadata = await context.getProjectMetadata(projectName);
+  const sourceRoot = (projectMetadata.sourceRoot ?? projectMetadata.root ?? '') as string;
+
+  return path.join(context.workspaceRoot, sourceRoot);
+}
+
+async function collectEntrypoints(
+  options: KarmaBuilderOptions,
+  context: BuilderContext,
+): Promise<[Set<string>, string[]]> {
+  const projectSourceRoot = await getProjectSourceRoot(context);
+
+  // Glob for files to test.
+  const testFiles = await findTests(
+    options.include ?? [],
+    options.exclude ?? [],
+    context.workspaceRoot,
+    projectSourceRoot,
+  );
+
+  const entryPoints = new Set([
+    ...testFiles,
+    '@angular-devkit/build-angular/src/builders/karma/init_test_bed.js',
+  ]);
+  // Extract `zone.js/testing` to a separate entry point because it needs to be loaded after Jasmine.
+  const [polyfills, hasZoneTesting] = extractZoneTesting(options.polyfills);
+  if (hasZoneTesting) {
+    entryPoints.add('zone.js/testing');
+  }
+
+  const tsConfigPath = path.resolve(context.workspaceRoot, options.tsConfig);
+  const tsConfig = await readTsconfig(tsConfigPath);
+
+  const localizePackageInitEntryPoint = '@angular/localize/init';
+  const hasLocalizeType = tsConfig.options.types?.some(
+    (t) => t === '@angular/localize' || t === localizePackageInitEntryPoint,
+  );
+
+  if (hasLocalizeType) {
+    polyfills.push(localizePackageInitEntryPoint);
+  }
+
+  return [entryPoints, polyfills];
+}
+
+async function initializeApplication(
+  options: KarmaBuilderOptions,
+  context: BuilderContext,
+  karmaOptions: ConfigOptions,
+  transforms: {
+    webpackConfiguration?: ExecutionTransformer<Configuration>;
+    karmaOptions?: (options: ConfigOptions) => ConfigOptions;
+  } = {},
+): Promise<[typeof import('karma'), Config & ConfigOptions]> {
+  if (transforms.webpackConfiguration) {
+    context.logger.warn(
+      `This build is using the application builder but transforms.webpackConfiguration was provided. The transform will be ignored.`,
+    );
+  }
+
+  const testDir = path.join(context.workspaceRoot, 'dist/test-out', randomUUID());
+
+  const [karma, [entryPoints, polyfills]] = await Promise.all([
+    import('karma'),
+    collectEntrypoints(options, context),
+    fs.rm(testDir, { recursive: true, force: true }),
+    // Purge old build disk cache:
+    await purgeStaleBuildCache(context),
+  ]);
+
+  const outputPath = testDir;
+
+  // Build tests with `application` builder, using test files as entry points.
+  const buildOutput = await first(
+    buildApplicationInternal(
+      {
+        entryPoints,
+        tsConfig: options.tsConfig,
+        outputPath,
+        aot: false,
+        index: false,
+        outputHashing: OutputHashing.None,
+        optimization: false,
+        sourceMap: {
+          scripts: true,
+          styles: true,
+          vendor: true,
+        },
+        styles: options.styles,
+        polyfills,
+        webWorkerTsConfig: options.webWorkerTsConfig,
+      },
+      context,
+    ),
+  );
+  if (buildOutput.kind === ResultKind.Failure) {
+    throw new ApplicationBuildError('Build failed');
+  } else if (buildOutput.kind !== ResultKind.Full) {
+    throw new ApplicationBuildError(
+      'A full build result is required from the application builder.',
+    );
+  }
+
+  // Write test files
+  await writeTestFiles(buildOutput.files, testDir);
+
+  karmaOptions.files ??= [];
+  karmaOptions.files.push(
+    // Serve polyfills first.
+    { pattern: `${testDir}/polyfills.js`, type: 'module' },
+    // Allow loading of chunk-* files but don't include them all on load.
+    { pattern: `${testDir}/chunk-*.js`, type: 'module', included: false },
+    // Allow loading of worker-* files but don't include them all on load.
+    { pattern: `${testDir}/worker-*.js`, type: 'module', included: false },
+    // `zone.js/testing`, served but not included on page load.
+    { pattern: `${testDir}/testing.js`, type: 'module', included: false },
+    // Serve remaining JS on page load, these are the test entrypoints.
+    { pattern: `${testDir}/*.js`, type: 'module' },
+  );
+
+  if (options.styles?.length) {
+    // Serve CSS outputs on page load, these are the global styles.
+    karmaOptions.files.push({ pattern: `${testDir}/*.css`, type: 'css' });
+  }
+
+  const parsedKarmaConfig: Config & ConfigOptions = await karma.config.parseConfig(
+    options.karmaConfig && path.resolve(context.workspaceRoot, options.karmaConfig),
+    transforms.karmaOptions ? transforms.karmaOptions(karmaOptions) : karmaOptions,
+    { promiseConfig: true, throwErrors: true },
+  );
+
+  // Remove the webpack plugin/framework:
+  // Alternative would be to make the Karma plugin "smart" but that's a tall order
+  // with managing unneeded imports etc..
+  const pluginLengthBefore = (parsedKarmaConfig.plugins ?? []).length;
+  parsedKarmaConfig.plugins = (parsedKarmaConfig.plugins ?? []).filter(
+    (plugin: string | InlinePluginDef) => {
+      if (typeof plugin === 'string') {
+        return plugin !== 'framework:@angular-devkit/build-angular';
+      }
+
+      return !plugin['framework:@angular-devkit/build-angular'];
+    },
+  );
+  parsedKarmaConfig.frameworks = parsedKarmaConfig.frameworks?.filter(
+    (framework: string) => framework !== '@angular-devkit/build-angular',
+  );
+  const pluginLengthAfter = (parsedKarmaConfig.plugins ?? []).length;
+  if (pluginLengthBefore !== pluginLengthAfter) {
+    context.logger.warn(
+      `Ignoring framework "@angular-devkit/build-angular" from karma config file because it's not compatible with the application builder.`,
+    );
+  }
+
+  // When using code-coverage, auto-add karma-coverage.
+  // This was done as part of the karma plugin for webpack.
+  if (
+    options.codeCoverage &&
+    !parsedKarmaConfig.reporters?.some((r: string) => r === 'coverage' || r === 'coverage-istanbul')
+  ) {
+    parsedKarmaConfig.reporters = (parsedKarmaConfig.reporters ?? []).concat(['coverage']);
+  }
+
+  return [karma, parsedKarmaConfig];
+}
+
+export async function writeTestFiles(files: Record<string, ResultFile>, testDir: string) {
+  const directoryExists = new Set<string>();
+  // Writes the test related output files to disk and ensures the containing directories are present
+  await emitFilesToDisk(Object.entries(files), async ([filePath, file]) => {
+    if (file.type !== BuildOutputFileType.Browser && file.type !== BuildOutputFileType.Media) {
+      return;
+    }
+
+    const fullFilePath = path.join(testDir, filePath);
+
+    // Ensure output subdirectories exist
+    const fileBasePath = path.dirname(fullFilePath);
+    if (fileBasePath && !directoryExists.has(fileBasePath)) {
+      await fs.mkdir(fileBasePath, { recursive: true });
+      directoryExists.add(fileBasePath);
+    }
+
+    if (file.origin === 'memory') {
+      // Write file contents
+      await fs.writeFile(fullFilePath, file.contents);
+    } else {
+      // Copy file contents
+      await fs.copyFile(file.inputPath, fullFilePath, fs.constants.COPYFILE_FICLONE);
+    }
+  });
+}
+
+function extractZoneTesting(
+  polyfills: readonly string[] | string | undefined,
+): [polyfills: string[], hasZoneTesting: boolean] {
+  if (typeof polyfills === 'string') {
+    polyfills = [polyfills];
+  }
+  polyfills ??= [];
+
+  const polyfillsWithoutZoneTesting = polyfills.filter(
+    (polyfill) => polyfill !== 'zone.js/testing',
+  );
+  const hasZoneTesting = polyfills.length !== polyfillsWithoutZoneTesting.length;
+
+  return [polyfillsWithoutZoneTesting, hasZoneTesting];
+}
+
+/** Returns the first item yielded by the given generator and cancels the execution. */
+async function first<T>(generator: AsyncIterable<T>): Promise<T> {
+  for await (const value of generator) {
+    return value;
+  }
+
+  throw new Error('Expected generator to emit at least once.');
+}