refactor(@angular/build): improve error handling for unit-test builder setup

Error handling has been enhanced to provide more actionable feedback for common misconfigurations, such as an invalid `buildTarget` or a malformed test runner package.

Author: clydin

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

@@ -6,7 +6,11 @@
  * found in the LICENSE file at https://angular.dev/license
  */
 
-import type { BuilderContext, BuilderOutput } from '@angular-devkit/architect';
+import {
+  type BuilderContext,
+  type BuilderOutput,
+  targetStringFromTarget,
+} from '@angular-devkit/architect';
 import assert from 'node:assert';
 import { createVirtualModulePlugin } from '../../tools/esbuild/virtual-module-plugin';
 import { assertIsError } from '../../utils/error';
@@ -22,6 +26,101 @@ import type { Schema as UnitTestBuilderOptions } from './schema';
 
 export type { UnitTestBuilderOptions };
 
+async function loadTestRunner(runnerName: string): Promise<TestRunner> {
+  // Harden against directory traversal
+  if (!/^[a-zA-Z0-9-]+$/.test(runnerName)) {
+    throw new Error(
+      `Invalid runner name "${runnerName}". Runner names can only contain alphanumeric characters and hyphens.`,
+    );
+  }
+
+  let runnerModule;
+  try {
+    runnerModule = await import(`./runners/${runnerName}/index`);
+  } catch (e) {
+    assertIsError(e);
+    if (e.code === 'ERR_MODULE_NOT_FOUND') {
+      throw new Error(`Unknown test runner "${runnerName}".`);
+    }
+    throw new Error(
+      `Failed to load the '${runnerName}' test runner. The package may be corrupted or improperly installed.\n` +
+        `Error: ${e.message}`,
+    );
+  }
+
+  const runner = runnerModule.default;
+  if (
+    !runner ||
+    typeof runner.getBuildOptions !== 'function' ||
+    typeof runner.createExecutor !== 'function'
+  ) {
+    throw new Error(
+      `The loaded test runner '${runnerName}' does not appear to be a valid TestRunner implementation.`,
+    );
+  }
+
+  return runner;
+}
+
+function prepareBuildExtensions(
+  virtualFiles: Record<string, string> | undefined,
+  projectSourceRoot: string,
+  extensions?: ApplicationBuilderExtensions,
+): ApplicationBuilderExtensions | undefined {
+  if (!virtualFiles) {
+    return extensions;
+  }
+
+  extensions ??= {};
+  extensions.codePlugins ??= [];
+  for (const [namespace, contents] of Object.entries(virtualFiles)) {
+    extensions.codePlugins.push(
+      createVirtualModulePlugin({
+        namespace,
+        loadContent: () => {
+          return {
+            contents,
+            loader: 'js',
+            resolveDir: projectSourceRoot,
+          };
+        },
+      }),
+    );
+  }
+
+  return extensions;
+}
+
+async function* runBuildAndTest(
+  executor: import('./runners/api').TestExecutor,
+  applicationBuildOptions: ApplicationBuilderInternalOptions,
+  context: BuilderContext,
+  extensions: ApplicationBuilderExtensions | undefined,
+): AsyncIterable<BuilderOutput> {
+  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);
+  }
+}
+
 /**
  * @experimental Direct usage of this function is considered experimental.
  */
@@ -43,24 +142,8 @@ export async function* execute(
   );
 
   const normalizedOptions = await normalizeOptions(context, projectName, options);
-  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}".`);
+  const runner = await loadTestRunner(normalizedOptions.runnerName);
 
-    return;
-  }
-
-  // Create the stateful executor once
   await using executor = await runner.createExecutor(context, normalizedOptions);
 
   if (runner.isStandalone) {
@@ -73,68 +156,42 @@ export async function* execute(
   }
 
   // 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;
+  let buildTargetOptions: ApplicationBuilderInternalOptions;
+  try {
+    buildTargetOptions = (await context.validateOptions(
+      await context.getTargetOptions(normalizedOptions.buildTarget),
+      await context.getBuilderNameForTarget(normalizedOptions.buildTarget),
+    )) as unknown as ApplicationBuilderInternalOptions;
+  } catch (e) {
+    assertIsError(e);
+    context.logger.error(
+      `Could not load build target options for "${targetStringFromTarget(normalizedOptions.buildTarget)}".\n` +
+        `Please check your 'angular.json' configuration.\n` +
+        `Error: ${e.message}`,
+    );
+
+    return;
+  }
 
   // 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;
+  const finalExtensions = prepareBuildExtensions(
+    virtualFiles,
+    normalizedOptions.projectSourceRoot,
+    extensions,
+  );
 
   // Prepare and run the application build
   const applicationBuildOptions = {
-    // Base options
     ...buildTargetOptions,
-    watch,
-    tsConfig,
-    // Runner specific
     ...runnerBuildOptions,
+    watch: normalizedOptions.watch,
+    tsConfig: normalizedOptions.tsConfig,
   } 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);
-  }
+  yield* runBuildAndTest(executor, applicationBuildOptions, context, finalExtensions);
 }