refactor(@angular/build): introduce internal generic test runner API in unit-test builder

packages/angular/build/src/builders/unit-test/builder.ts

@@ -7,10 +7,17 @@
  */
 
 import type { BuilderContext, BuilderOutput } from '@angular-devkit/architect';
-import type { ApplicationBuilderExtensions } from '../application/options';
+import assert from 'node:assert';
+import { createVirtualModulePlugin } from '../../tools/esbuild/virtual-module-plugin';
+import { assertIsError } from '../../utils/error';
+import { buildApplicationInternal } from '../application';
+import type {
+  ApplicationBuilderExtensions,
+  ApplicationBuilderInternalOptions,
+} from '../application/options';
+import { ResultKind } from '../application/results';
 import { normalizeOptions } from './options';
-import { useKarmaRunner } from './runners/karma';
-import { runVitest } from './runners/vitest';
+import type { TestRunner } from './runners/api';
 import type { Schema as UnitTestBuilderOptions } from './schema';
 
 export type { UnitTestBuilderOptions };
@@ -36,17 +43,98 @@ export async function* execute(
   );
 
   const normalizedOptions = await normalizeOptions(context, projectName, options);
-  const { runnerName } = normalizedOptions;
-
-  switch (runnerName) {
-    case 'karma':
-      yield* await useKarmaRunner(context, normalizedOptions);
-      break;
-    case 'vitest':
-      yield* runVitest(normalizedOptions, context, extensions);
-      break;
-    default:
-      context.logger.error('Unknown test runner: ' + runnerName);
-      break;
+  const { runnerName, projectSourceRoot } = normalizedOptions;
+
+  // Dynamically load the requested runner
+  let runner: TestRunner;
+  try {
+    const { default: runnerModule } = await import(`./runners/${runnerName}/index`);
+    runner = runnerModule;
+  } catch (e) {
+    assertIsError(e);
+    if (e.code !== 'ERR_MODULE_NOT_FOUND') {
+      throw e;
+    }
+    context.logger.error(`Unknown test runner "${runnerName}".`);
+
+    return;
+  }
+
+  // Create the stateful executor once
+  await using executor = await runner.createExecutor(context, normalizedOptions);
+
+  if (runner.isStandalone) {
+    yield* executor.execute({
+      kind: ResultKind.Full,
+      files: {},
+    });
+
+    return;
+  }
+
+  // Get base build options from the buildTarget
+  const buildTargetOptions = (await context.validateOptions(
+    await context.getTargetOptions(normalizedOptions.buildTarget),
+    await context.getBuilderNameForTarget(normalizedOptions.buildTarget),
+  )) as unknown as ApplicationBuilderInternalOptions;
+
+  // Get runner-specific build options from the hook
+  const { buildOptions: runnerBuildOptions, virtualFiles } = await runner.getBuildOptions(
+    normalizedOptions,
+    buildTargetOptions,
+  );
+
+  if (virtualFiles) {
+    extensions ??= {};
+    extensions.codePlugins ??= [];
+    for (const [namespace, contents] of Object.entries(virtualFiles)) {
+      extensions.codePlugins.push(
+        createVirtualModulePlugin({
+          namespace,
+          loadContent: () => {
+            return {
+              contents,
+              loader: 'js',
+              resolveDir: projectSourceRoot,
+            };
+          },
+        }),
+      );
+    }
+  }
+
+  const { watch, tsConfig } = normalizedOptions;
+
+  // Prepare and run the application build
+  const applicationBuildOptions = {
+    // Base options
+    ...buildTargetOptions,
+    watch,
+    tsConfig,
+    // Runner specific
+    ...runnerBuildOptions,
+  } satisfies ApplicationBuilderInternalOptions;
+
+  for await (const buildResult of buildApplicationInternal(
+    applicationBuildOptions,
+    context,
+    extensions,
+  )) {
+    if (buildResult.kind === ResultKind.Failure) {
+      yield { success: false };
+      continue;
+    } else if (
+      buildResult.kind !== ResultKind.Full &&
+      buildResult.kind !== ResultKind.Incremental
+    ) {
+      assert.fail(
+        'A full and/or incremental build result is required from the application builder.',
+      );
+    }
+
+    assert(buildResult.files, 'Builder did not provide result files.');
+
+    // Pass the build artifacts to the executor
+    yield* executor.execute(buildResult);
   }
 }

packages/angular/build/src/builders/unit-test/runners/api.ts

@@ -0,0 +1,60 @@
+/**
+ * @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 type { BuilderContext, BuilderOutput } from '@angular-devkit/architect';
+import type { ApplicationBuilderInternalOptions } from '../../application/options';
+import type { FullResult, IncrementalResult } from '../../application/results';
+import type { NormalizedUnitTestBuilderOptions } from '../options';
+
+export interface RunnerOptions {
+  buildOptions: Partial<ApplicationBuilderInternalOptions>;
+  virtualFiles?: Record<string, string>;
+}
+
+/**
+ * Represents a stateful test execution session.
+ * An instance of this is created for each `ng test` command.
+ */
+export interface TestExecutor {
+  /**
+   * Executes tests using the artifacts from a specific build.
+   * This method can be called multiple times in watch mode.
+   *
+   * @param buildResult The output from the application builder.
+   * @returns An async iterable builder output stream.
+   */
+  execute(buildResult: FullResult | IncrementalResult): AsyncIterable<BuilderOutput>;
+
+  [Symbol.asyncDispose](): Promise<void>;
+}
+
+/**
+ * Represents the metadata and hooks for a specific test runner.
+ */
+export interface TestRunner {
+  readonly name: string;
+  readonly isStandalone?: boolean;
+
+  getBuildOptions(
+    options: NormalizedUnitTestBuilderOptions,
+    baseBuildOptions: Partial<ApplicationBuilderInternalOptions>,
+  ): RunnerOptions | Promise<RunnerOptions>;
+
+  /**
+   * Creates a stateful executor for a test session.
+   * This is called once at the start of the `ng test` command.
+   *
+   * @param context The Architect builder context.
+   * @param options The normalized unit test options.
+   * @returns A TestExecutor instance that will handle the test runs.
+   */
+  createExecutor(
+    context: BuilderContext,
+    options: NormalizedUnitTestBuilderOptions,
+  ): Promise<TestExecutor>;
+}

packages/angular/build/src/builders/unit-test/runners/karma/executor.ts

@@ -0,0 +1,76 @@
+/**
+ * @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 type { BuilderContext, BuilderOutput } from '@angular-devkit/architect';
+import type { ApplicationBuilderInternalOptions } from '../../../application/options';
+import type { KarmaBuilderOptions } from '../../../karma';
+import { NormalizedUnitTestBuilderOptions } from '../../options';
+import type { TestExecutor } from '../api';
+
+export class KarmaExecutor implements TestExecutor {
+  constructor(
+    private context: BuilderContext,
+    private options: NormalizedUnitTestBuilderOptions,
+  ) {}
+
+  async *execute(): AsyncIterable<BuilderOutput> {
+    const { context, options: unitTestOptions } = this;
+
+    if (unitTestOptions.debug) {
+      context.logger.warn(
+        'The "karma" test runner does not support the "debug" option. The option will be ignored.',
+      );
+    }
+
+    if (unitTestOptions.setupFiles.length) {
+      context.logger.warn(
+        'The "karma" test runner does not support the "setupFiles" option. The option will be ignored.',
+      );
+    }
+
+    const buildTargetOptions = (await context.validateOptions(
+      await context.getTargetOptions(unitTestOptions.buildTarget),
+      await context.getBuilderNameForTarget(unitTestOptions.buildTarget),
+    )) as unknown as ApplicationBuilderInternalOptions;
+
+    const karmaOptions: KarmaBuilderOptions = {
+      tsConfig: unitTestOptions.tsConfig,
+      polyfills: buildTargetOptions.polyfills,
+      assets: buildTargetOptions.assets,
+      scripts: buildTargetOptions.scripts,
+      styles: buildTargetOptions.styles,
+      inlineStyleLanguage: buildTargetOptions.inlineStyleLanguage,
+      stylePreprocessorOptions: buildTargetOptions.stylePreprocessorOptions,
+      externalDependencies: buildTargetOptions.externalDependencies,
+      loader: buildTargetOptions.loader,
+      define: buildTargetOptions.define,
+      include: unitTestOptions.include,
+      exclude: unitTestOptions.exclude,
+      sourceMap: buildTargetOptions.sourceMap,
+      progress: buildTargetOptions.progress,
+      watch: unitTestOptions.watch,
+      poll: buildTargetOptions.poll,
+      preserveSymlinks: buildTargetOptions.preserveSymlinks,
+      browsers: unitTestOptions.browsers?.join(','),
+      codeCoverage: !!unitTestOptions.codeCoverage,
+      codeCoverageExclude: unitTestOptions.codeCoverage?.exclude,
+      fileReplacements: buildTargetOptions.fileReplacements,
+      reporters: unitTestOptions.reporters,
+      webWorkerTsConfig: buildTargetOptions.webWorkerTsConfig,
+      aot: buildTargetOptions.aot,
+    };
+
+    const { execute } = await import('../../../karma');
+
+    yield* execute(karmaOptions, context);
+  }
+
+  async [Symbol.asyncDispose](): Promise<void> {
+    // The Karma builder handles its own teardown
+  }
+}

packages/angular/build/src/builders/unit-test/runners/karma/index.ts

@@ -6,4 +6,25 @@
  * found in the LICENSE file at https://angular.dev/license
  */
 
-export { useKarmaRunner } from './runner';
+import type { TestRunner } from '../api';
+import { KarmaExecutor } from './executor';
+
+/**
+ * A declarative definition of the Karma test runner.
+ */
+const KarmaTestRunner: TestRunner = {
+  name: 'karma',
+  isStandalone: true,
+
+  getBuildOptions() {
+    return {
+      buildOptions: {},
+    };
+  },
+
+  async createExecutor(context, options) {
+    return new KarmaExecutor(context, options);
+  },
+};
+
+export default KarmaTestRunner;