fix(@angular/build): provide direct debugging support for unit test builder

When using the experimental `unit-test` builder with the `vitest` runner,
a `debug` option is now available which configures the underlying runner
to setup and use the Node Inspector to debug tests. This reduces the
complexity to support debugging unit tests via a command execution of
`ng test --debug`. This will cause the test process to initialize and
then wait for a debugger to connect prior to executing the tests.

Author: clydin

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

@@ -183,6 +183,7 @@ export async function* execute(
   // Setup vitest browser options if configured
   const { browser, errors } = setupBrowserConfiguration(
     normalizedOptions.browsers,
+    normalizedOptions.debug,
     projectSourceRoot,
   );
   if (errors?.length) {
@@ -196,6 +197,13 @@ export async function* execute(
   if (buildTargetOptions?.polyfills?.length) {
     setupFiles.push('polyfills.js');
   }
+  const debugOptions = normalizedOptions.debug
+    ? {
+        inspectBrk: true,
+        isolate: false,
+        fileParallelism: false,
+      }
+    : {};
 
   try {
     for await (const result of buildApplicationInternal(buildOptions, context, extensions)) {
@@ -226,6 +234,7 @@ export async function* execute(
             exclude: normalizedOptions.codeCoverageExclude,
             excludeAfterRemap: true,
           },
+          ...debugOptions,
         },
       });
 
@@ -259,6 +268,7 @@ function findBrowserProvider(
 
 function setupBrowserConfiguration(
   browsers: string[] | undefined,
+  debug: boolean,
   projectSourceRoot: string,
 ): { browser?: import('vitest/node').BrowserConfigOptions; errors?: string[] } {
   if (browsers === undefined) {
@@ -287,6 +297,15 @@ function setupBrowserConfiguration(
     );
   }
 
+  // Vitest current requires the playwright browser provider to use the inspect-brk option used by "debug"
+  if (debug && provider !== 'playwright') {
+    errors ??= [];
+    errors.push(
+      'Debugging browser mode tests currently requires the use of "playwright".' +
+        ' Please install this package and rerun the test command.',
+    );
+  }
+
   if (errors) {
     return { errors };
   }

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

@@ -15,6 +15,12 @@ export async function useKarmaBuilder(
   context: BuilderContext,
   unitTestOptions: NormalizedUnitTestOptions,
 ): Promise<AsyncIterable<BuilderOutput>> {
+  if (unitTestOptions.debug) {
+    context.logger.warn(
+      'The "karma" test runner does not support the "debug" option. The option will be ignored.',
+    );
+  }
+
   const buildTargetOptions = (await context.validateOptions(
     await context.getTargetOptions(unitTestOptions.buildTarget),
     await context.getBuilderNameForTarget(unitTestOptions.buildTarget),

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

@@ -52,6 +52,7 @@ export async function normalizeOptions(
     reporters,
     browsers,
     watch,
+    debug: options.debug ?? false,
     providersFile: options.providersFile && path.join(workspaceRoot, options.providersFile),
   };
 }

packages/angular/build/src/builders/unit-test/schema.json

@@ -46,6 +46,11 @@
       "type": "boolean",
       "description": "Run build when files change."
     },
+    "debug": {
+      "type": "boolean",
+      "description": "Initialize the test runner to support using the Node Inspector for test debugging.",
+      "default": false
+    },
     "codeCoverage": {
       "type": "boolean",
       "description": "Output a code coverage report.",