feat(@angular/build): add headless option to unit-test builder

This adds a new 'headless' option to the unit-test builder. When set to true, it forces all configured browsers to run in headless mode.

This option allows users to force headless execution in non-CI environments (where it is already the default) or to explicitly control the mode regardless of the browser name.

Informational messages are now logged when the option is redundant (e.g., all browsers are already headless), ignored (e.g., using the preview provider), or irrelevant (e.g., no browsers configured).

The 'karma' runner does not support this option and will log a warning if it is used.

Author: clydin

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

@@ -96,6 +96,7 @@ export async function normalizeOptions(
     exclude: options.exclude,
     filter,
     runnerName: runner ?? Runner.Vitest,
+    headless: options.headless,
     coverage: {
       enabled: options.coverage,
       exclude: options.coverageExclude,

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

@@ -47,6 +47,12 @@ export class KarmaExecutor implements TestExecutor {
       );
     }
 
+    if (unitTestOptions.headless !== undefined) {
+      context.logger.warn(
+        'The "karma" test runner does not support the "headless" 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/runners/vitest/browser-provider.ts

@@ -13,6 +13,7 @@ import { assertIsError } from '../../../../utils/error';
 export interface BrowserConfiguration {
   browser?: BrowserConfigOptions;
   errors?: string[];
+  messages?: string[];
 }
 
 function findBrowserProvider(
@@ -51,11 +52,18 @@ function normalizeBrowserName(browserName: string): { browser: string; headless:
 
 export async function setupBrowserConfiguration(
   browsers: string[] | undefined,
+  headless: boolean | undefined,
   debug: boolean,
   projectSourceRoot: string,
   viewport: { width: number; height: number } | undefined,
 ): Promise<BrowserConfiguration> {
   if (browsers === undefined) {
+    if (headless !== undefined) {
+      return {
+        messages: ['The "headless" option is ignored when no browsers are configured.'],
+      };
+    }
+
     return {};
   }
 
@@ -125,10 +133,30 @@ export async function setupBrowserConfiguration(
 
   const isCI = !!process.env['CI'];
   const instances = browsers.map(normalizeBrowserName);
+  const messages: string[] = [];
+
   if (providerName === 'preview') {
     instances.forEach((instance) => {
+      // Preview mode only supports headed execution
       instance.headless = false;
     });
+
+    if (headless) {
+      messages.push('The "headless" option is ignored when using the "preview" provider.');
+    }
+  } else if (headless !== undefined) {
+    if (headless) {
+      const allHeadlessByDefault = isCI || instances.every((i) => i.headless);
+      if (allHeadlessByDefault) {
+        messages.push(
+          'The "headless" option is unnecessary as all browsers are already configured to run in headless mode.',
+        );
+      }
+    }
+
+    instances.forEach((instance) => {
+      instance.headless = headless;
+    });
   } else if (isCI) {
     instances.forEach((instance) => {
       instance.headless = true;
@@ -143,5 +171,5 @@ export async function setupBrowserConfiguration(
     instances,
   } satisfies BrowserConfigOptions;
 
-  return { browser };
+  return { browser, messages };
 }

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

@@ -192,6 +192,7 @@ export class VitestExecutor implements TestExecutor {
     // Setup vitest browser options if configured
     const browserOptions = await setupBrowserConfiguration(
       browsers,
+      this.options.headless,
       debug,
       projectSourceRoot,
       browserViewport,
@@ -200,6 +201,12 @@ export class VitestExecutor implements TestExecutor {
       throw new Error(browserOptions.errors.join('\n'));
     }
 
+    if (browserOptions.messages?.length) {
+      for (const message of browserOptions.messages) {
+        this.logger.info(message);
+      }
+    }
+
     assert(
       this.buildResultFiles.size > 0,
       'buildResult must be available before initializing vitest',

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

@@ -60,6 +60,10 @@
       "type": "boolean",
       "description": "Enables watch mode, which re-runs tests when source files change. Defaults to `true` in TTY environments and `false` otherwise."
     },
+    "headless": {
+      "type": "boolean",
+      "description": "Forces all configured browsers to run in headless mode. When using the Vitest runner, this option is ignored if no browsers are configured. The Karma runner does not support this option."
+    },
     "debug": {
       "type": "boolean",
       "description": "Enables debugging mode for tests, allowing the use of the Node Inspector.",