refactor(@angular/build): improve Vitest configuration merging

This commit refactors the Vitest configuration handling within the unit test builder to more reliably merge the CLI-generated configuration with a user's `vitest-base.config.ts` file.

The new implementation uses Vitest's `mergeConfig` utility to create a layered configuration, ensuring that essential CLI settings (such as test entry points and in-memory file providers) are preserved while still allowing users to customize other options. This prevents user configurations from inadvertently overriding critical builder settings, leading to a more stable and predictable testing experience.

Author: clydin

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

@@ -226,14 +226,15 @@ export class VitestExecutor implements TestExecutor {
           watch: null,
         },
         plugins: [
-          createVitestConfigPlugin({
+          await createVitestConfigPlugin({
             browser: browserOptions.browser,
             coverage,
             projectName,
             projectSourceRoot: this.options.projectSourceRoot,
             optimizeDepsInclude: this.externalMetadata.explicitBrowser,
             reporters,
             setupFiles: testSetupFiles,
+            hasRunnerConfig: !!externalConfigPath,
             projectPlugins,
             include: [...this.testFileToEntryPoint.keys()].filter(
               // Filter internal entries

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

@@ -43,6 +43,7 @@ interface VitestConfigPluginOptions {
   projectPlugins: Exclude<UserWorkspaceConfig['plugins'], undefined>;
   include: string[];
   optimizeDepsInclude: string[];
+  hasRunnerConfig: boolean;
 }
 
 async function findTestEnvironment(
@@ -58,7 +59,9 @@ async function findTestEnvironment(
   }
 }
 
-export function createVitestConfigPlugin(options: VitestConfigPluginOptions): VitestPlugins[0] {
+export async function createVitestConfigPlugin(
+  options: VitestConfigPluginOptions,
+): Promise<VitestPlugins[0]> {
   const {
     include,
     browser,
@@ -69,6 +72,8 @@ export function createVitestConfigPlugin(options: VitestConfigPluginOptions): Vi
     projectSourceRoot,
   } = options;
 
+  const { mergeConfig } = await import('vitest/config');
+
   return {
     name: 'angular:vitest-configuration',
     async config(config) {
@@ -90,17 +95,6 @@ export function createVitestConfigPlugin(options: VitestConfigPluginOptions): Vi
         delete testConfig.include;
       }
 
-      // The user's setup files should be appended to the CLI's setup files.
-      const combinedSetupFiles = [...setupFiles];
-      if (testConfig?.setupFiles) {
-        if (typeof testConfig.setupFiles === 'string') {
-          combinedSetupFiles.push(testConfig.setupFiles);
-        } else if (Array.isArray(testConfig.setupFiles)) {
-          combinedSetupFiles.push(...testConfig.setupFiles);
-        }
-        delete testConfig.setupFiles;
-      }
-
       // Merge user-defined plugins from the Vitest config with the CLI's internal plugins.
       if (config.plugins) {
         const userPlugins = config.plugins.filter(
@@ -115,38 +109,48 @@ export function createVitestConfigPlugin(options: VitestConfigPluginOptions): Vi
         if (userPlugins.length > 0) {
           projectPlugins.push(...userPlugins);
         }
+        delete config.plugins;
       }
 
       const projectResolver = createRequire(projectSourceRoot + '/').resolve;
 
-      const projectConfig: UserWorkspaceConfig = {
+      const projectDefaults: UserWorkspaceConfig = {
+        test: {
+          setupFiles,
+          globals: true,
+          // Default to `false` to align with the Karma/Jasmine experience.
+          isolate: false,
+        },
+        optimizeDeps: {
+          noDiscovery: true,
+          include: options.optimizeDepsInclude,
+        },
+      };
+
+      const projectOverrides: UserWorkspaceConfig = {
         test: {
-          ...testConfig,
           name: projectName,
-          setupFiles: combinedSetupFiles,
           include,
-          globals: testConfig?.globals ?? true,
-          // Default to `false` to align with the Karma/Jasmine experience.
-          isolate: testConfig?.isolate ?? false,
+          // CLI provider browser options override, if present
           ...(browser ? { browser } : {}),
           // If the user has not specified an environment, use a smart default.
           ...(!testConfig?.environment
             ? { environment: await findTestEnvironment(projectResolver) }
             : {}),
         },
-        optimizeDeps: {
-          noDiscovery: true,
-          include: options.optimizeDepsInclude,
-        },
         plugins: projectPlugins,
       };
 
+      const projectBase = mergeConfig(projectDefaults, config);
+      const projectConfig = mergeConfig(projectBase, projectOverrides);
+      // The environments field should not be propagated into the project config
+      delete projectConfig['environments'];
+
       return {
         test: {
           coverage: await generateCoverageOption(options.coverage, projectName),
           // eslint-disable-next-line @typescript-eslint/no-explicit-any
           ...(reporters ? ({ reporters } as any) : {}),
-          ...(browser ? { browser } : {}),
           projects: [projectConfig],
         },
       };

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

@@ -16,53 +16,33 @@ import {
 } from '../setup';
 
 describeBuilder(execute, UNIT_TEST_BUILDER_INFO, (harness) => {
-  xdescribe('Option: "browsers"', () => {
+  describe('Option: "browsers"', () => {
     beforeEach(async () => {
       setupApplicationTarget(harness);
     });
 
-    it('should use jsdom when browsers is not provided', async () => {
+    it('should use DOM emulation when browsers is not provided', async () => {
       harness.useTarget('test', {
         ...BASE_OPTIONS,
         browsers: undefined,
       });
 
-      const { result, logs } = await harness.executeOnce();
+      const { result } = await harness.executeOnce();
       expect(result?.success).toBeTrue();
-      expectLog(logs, 'Using jsdom in Node.js for test execution.');
     });
 
-    it('should fail when browsers is empty', async () => {
-      harness.useTarget('test', {
-        ...BASE_OPTIONS,
-        browsers: [],
-      });
-
-      await expectAsync(harness.executeOnce()).toBeRejectedWithError(
-        /must NOT have fewer than 1 items/,
-      );
-    });
-
-    it('should launch a browser when provided', async () => {
+    it('should fail when a browser is requested but no provider is installed', async () => {
       harness.useTarget('test', {
         ...BASE_OPTIONS,
         browsers: ['chrome'],
       });
 
       const { result, logs } = await harness.executeOnce();
-      expect(result?.success).toBeTrue();
-      expectLog(logs, /Starting browser "chrome"/);
-    });
-
-    it('should launch a browser in headless mode when specified', async () => {
-      harness.useTarget('test', {
-        ...BASE_OPTIONS,
-        browsers: ['chromeheadless'],
-      });
-
-      const { result, logs } = await harness.executeOnce();
-      expect(result?.success).toBeTrue();
-      expectLog(logs, /Starting browser "chrome" in headless mode/);
+      expect(result?.success).toBeFalse();
+      expectLog(
+        logs,
+        `The "browsers" option requires either "@vitest/browser-playwright", "@vitest/browser-webdriverio", or "@vitest/browser-preview" to be installed`,
+      );
     });
   });
 });

tests/legacy-cli/e2e/tests/vitest/browser-webdriverio.ts

@@ -0,0 +1,32 @@
+import assert from 'node:assert/strict';
+import { applyVitestBuilder } from '../../utils/vitest';
+import { ng } from '../../utils/process';
+import { installPackage } from '../../utils/packages';
+import { writeFile } from '../../utils/fs';
+
+export default async function (): Promise<void> {
+  await applyVitestBuilder();
+  await installPackage('webdriverio');
+  await installPackage('@vitest/browser-webdriverio');
+
+  await ng('generate', 'component', 'my-comp');
+
+  await writeFile(
+    'src/setup1.ts',
+    `
+    import { getTestBed } from '@angular/core/testing';
+
+    getTestBed().configureTestingModule({});
+  `,
+  );
+
+  const { stdout } = await ng(
+    'test',
+    '--browsers',
+    'chromeHeadless',
+    '--setup-files',
+    'src/setup1.ts',
+  );
+
+  assert.match(stdout, /2 passed/, 'Expected 2 tests to pass.');
+}