fix(@angular/build): add upfront dependency validation for unit-test runners

Previously, missing peer dependencies for test runners (e.g., `jsdom`, `karma-coverage`, `playwright`) were only discovered late in the execution process, often leading to cryptic errors. When multiple packages were missing, this resulted in a frustrating cycle of running the command, installing a package, and repeating.

This change introduces a comprehensive, upfront dependency validation system:

- A `validateDependencies` hook is added to the `TestRunner` interface, allowing each runner to declare its own requirements.
- A `DependencyChecker` class now collects all missing dependencies and reports them to the user in a single, clean error message without a stack trace.
- Both the Karma and Vitest runners implement this hook to check for all required packages based on the user's configuration (including browser launchers, coverage packages, and the JSDOM environment).

Author: clydin

modules/testing/builder/BUILD.bazel

@@ -20,6 +20,7 @@ ts_project(
         # Needed at runtime by some builder tests relying on SSR being
         # resolvable in the test project.
         ":node_modules/@angular/ssr",
+        ":node_modules/jsdom",
         ":node_modules/vitest",
         ":node_modules/@vitest/coverage-v8",
     ] + glob(["projects/**/*"]),

modules/testing/builder/package.json

@@ -5,6 +5,7 @@
     "@angular/ssr": "workspace:*",
     "@angular-devkit/build-angular": "workspace:*",
     "@vitest/coverage-v8": "3.2.4",
+    "jsdom": "27.0.0",
     "rxjs": "7.8.2",
     "vitest": "3.2.4"
   }

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

@@ -22,6 +22,7 @@ import type {
 import { ResultKind } from '../application/results';
 import { normalizeOptions } from './options';
 import type { TestRunner } from './runners/api';
+import { MissingDependenciesError } from './runners/dependency-checker';
 import type { Schema as UnitTestBuilderOptions } from './schema';
 
 export type { UnitTestBuilderOptions };
@@ -166,11 +167,16 @@ export async function* execute(
   try {
     normalizedOptions = await normalizeOptions(context, projectName, options);
     runner = await loadTestRunner(normalizedOptions.runnerName);
+    await runner.validateDependencies?.(normalizedOptions);
   } catch (e) {
     assertIsError(e);
-    context.logger.error(
-      `An exception occurred during initialization of the test runner:\n${e.stack ?? e.message}`,
-    );
+    if (e instanceof MissingDependenciesError) {
+      context.logger.error(e.message);
+    } else {
+      context.logger.error(
+        `An exception occurred during initialization of the test runner:\n${e.stack ?? e.message}`,
+      );
+    }
     yield { success: false };
 
     return;

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

@@ -58,6 +58,8 @@ export interface TestRunner {
   readonly name: string;
   readonly isStandalone?: boolean;
 
+  validateDependencies?(options: NormalizedUnitTestBuilderOptions): void | Promise<void>;
+
   getBuildOptions(
     options: NormalizedUnitTestBuilderOptions,
     baseBuildOptions: Partial<ApplicationBuilderInternalOptions>,

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

@@ -0,0 +1,89 @@
+/**
+ * @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 { createRequire } from 'node:module';
+
+/**
+ * A custom error class to represent missing dependency errors.
+ * This is used to avoid printing a stack trace for this expected error.
+ */
+export class MissingDependenciesError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'MissingDependenciesError';
+  }
+}
+
+type Resolver = (packageName: string) => string;
+
+export class DependencyChecker {
+  private readonly resolver: Resolver;
+  private readonly missingDependencies = new Set<string>();
+
+  constructor(projectSourceRoot: string) {
+    this.resolver = createRequire(projectSourceRoot + '/').resolve;
+  }
+
+  /**
+   * Checks if a package is installed.
+   * @param packageName The name of the package to check.
+   * @returns True if the package is found, false otherwise.
+   */
+  private isInstalled(packageName: string): boolean {
+    try {
+      this.resolver(packageName);
+
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * Verifies that a package is installed and adds it to a list of missing
+   * dependencies if it is not.
+   * @param packageName The name of the package to check.
+   */
+  check(packageName: string): void {
+    if (!this.isInstalled(packageName)) {
+      this.missingDependencies.add(packageName);
+    }
+  }
+
+  /**
+   * Verifies that at least one of a list of packages is installed. If none are
+   * installed, a custom error message is added to the list of errors.
+   * @param packageNames An array of package names to check.
+   * @param customErrorMessage The error message to use if none of the packages are found.
+   */
+  checkAny(packageNames: string[], customErrorMessage: string): void {
+    if (packageNames.every((name) => !this.isInstalled(name))) {
+      // This is a custom error, so we add it directly.
+      // Using a Set avoids duplicate custom messages.
+      this.missingDependencies.add(customErrorMessage);
+    }
+  }
+
+  /**
+   * Throws a `MissingDependenciesError` if any dependencies were found to be missing.
+   * The error message is a formatted list of all missing packages.
+   */
+  report(): void {
+    if (this.missingDependencies.size === 0) {
+      return;
+    }
+
+    let message = 'The following packages are required but were not found:\n';
+    for (const name of this.missingDependencies) {
+      message += `  - ${name}\n`;
+    }
+    message += 'Please install the missing packages and rerun the test command.';
+
+    throw new MissingDependenciesError(message);
+  }
+}

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

@@ -7,6 +7,7 @@
  */
 
 import type { TestRunner } from '../api';
+import { DependencyChecker } from '../dependency-checker';
 import { KarmaExecutor } from './executor';
 
 /**
@@ -16,6 +17,26 @@ const KarmaTestRunner: TestRunner = {
   name: 'karma',
   isStandalone: true,
 
+  validateDependencies(options) {
+    const checker = new DependencyChecker(options.projectSourceRoot);
+    checker.check('karma');
+    checker.check('karma-jasmine');
+
+    // Check for browser launchers
+    if (options.browsers?.length) {
+      for (const browser of options.browsers) {
+        const launcherName = `karma-${browser.toLowerCase().split('headless')[0]}-launcher`;
+        checker.check(launcherName);
+      }
+    }
+
+    if (options.codeCoverage) {
+      checker.check('karma-coverage');
+    }
+
+    checker.report();
+  },
+
   getBuildOptions() {
     return {
       buildOptions: {},

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

@@ -8,6 +8,7 @@
 
 import assert from 'node:assert';
 import type { TestRunner } from '../api';
+import { DependencyChecker } from '../dependency-checker';
 import { getVitestBuildOptions } from './build-options';
 import { VitestExecutor } from './executor';
 
@@ -17,6 +18,28 @@ import { VitestExecutor } from './executor';
 const VitestTestRunner: TestRunner = {
   name: 'vitest',
 
+  validateDependencies(options) {
+    const checker = new DependencyChecker(options.projectSourceRoot);
+    checker.check('vitest');
+
+    if (options.browsers?.length) {
+      checker.check('@vitest/browser');
+      checker.checkAny(
+        ['playwright', 'webdriverio'],
+        'The "browsers" option requires either "playwright" or "webdriverio" to be installed.',
+      );
+    } else {
+      // JSDOM is used when no browsers are specified
+      checker.check('jsdom');
+    }
+
+    if (options.codeCoverage) {
+      checker.check('@vitest/coverage-v8');
+    }
+
+    checker.report();
+  },
+
   getBuildOptions(options, baseBuildOptions) {
     return getVitestBuildOptions(options, baseBuildOptions);
   },