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

This commit adds an `isolate` option to the `@angular/build:unit-test` builder for the Vitest runner. By default, tests run in a non-isolated environment to match the behavior of Karma/Jasmine. This new option allows developers to easily opt-in to Vitest native isolation (running tests in separate threads or processes) without requiring a custom Vitest configuration file. The option is not supported by the Karma runner and will result in an error if used there.

Author: clydin

goldens/public-api/angular/build/index.api.md

@@ -233,6 +233,7 @@ export type UnitTestBuilderOptions = {
     filter?: string;
     headless?: boolean;
     include?: string[];
+    isolate?: boolean;
     listTests?: boolean;
     outputFile?: string;
     progress?: boolean;

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

@@ -54,12 +54,17 @@ export async function normalizeOptions(
   const buildTargetSpecifier = options.buildTarget ?? `::development`;
   const buildTarget = targetFromTargetString(buildTargetSpecifier, projectName, 'build');
 
-  const { runner, browsers, progress, filter, browserViewport, ui, runnerConfig } = options;
+  const { runner, browsers, progress, filter, browserViewport, ui, runnerConfig, isolate } =
+    options;
 
   if (ui && runner !== Runner.Vitest) {
     throw new Error('The "ui" option is only available for the "vitest" runner.');
   }
 
+  if (isolate && runner !== Runner.Vitest) {
+    throw new Error('The "isolate" option is only available for the "vitest" runner.');
+  }
+
   const [width, height] = browserViewport?.split('x').map(Number) ?? [];
 
   let tsConfig = options.tsConfig;
@@ -121,6 +126,7 @@ export async function normalizeOptions(
     watch,
     debug: options.debug ?? false,
     ui: process.env['CI'] ? false : ui,
+    isolate: isolate ?? false,
     quiet: options.quiet ?? (process.env['CI'] ? false : true),
     providersFile: options.providersFile && path.join(workspaceRoot, options.providersFile),
     setupFiles: options.setupFiles

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

@@ -378,6 +378,7 @@ export class VitestExecutor implements TestExecutor {
           projectPlugins,
           include,
           watch,
+          isolate: this.options.isolate,
         }),
       ],
     };

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

@@ -54,6 +54,7 @@ interface VitestConfigPluginOptions {
   include: string[];
   optimizeDepsInclude: string[];
   watch: boolean;
+  isolate: boolean;
 }
 
 async function findTestEnvironment(
@@ -250,8 +251,7 @@ export async function createVitestConfigPlugin(
         test: {
           setupFiles,
           globals: true,
-          // Default to `false` to align with the Karma/Jasmine experience.
-          isolate: false,
+          isolate: options.isolate,
           sequence: { setupFiles: 'list' },
         },
         optimizeDeps: {

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

@@ -73,6 +73,10 @@
       "type": "boolean",
       "description": "Enables the Vitest UI for interactive test execution. This option is only available for the Vitest runner."
     },
+    "isolate": {
+      "type": "boolean",
+      "description": "Enables isolation for test execution. When true, Vitest runs tests in separate threads or processes. This option is only available for the Vitest runner. Defaults to false to align with the Karma/Jasmine experience."
+    },
     "quiet": {
       "type": "boolean",
       "description": "Suppresses the verbose build summary and stats table on each rebuild. Defaults to `true` locally and `false` in CI environments."

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

@@ -0,0 +1,57 @@
+/**
+ * @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 { execute } from '../../index';
+import {
+  BASE_OPTIONS,
+  describeBuilder,
+  UNIT_TEST_BUILDER_INFO,
+  setupApplicationTarget,
+} from '../setup';
+
+describeBuilder(execute, UNIT_TEST_BUILDER_INFO, (harness) => {
+  describe('Option: "isolate"', () => {
+    beforeEach(async () => {
+      setupApplicationTarget(harness);
+    });
+
+    it('should fail when isolate is true and runner is karma', async () => {
+      harness.useTarget('test', {
+        ...BASE_OPTIONS,
+        runner: 'karma' as any,
+        isolate: true,
+      });
+
+      await expectAsync(harness.executeOnce()).toBeRejectedWithError(
+        /The "isolate" option is only available for the "vitest" runner/,
+      );
+    });
+
+    it('should run tests successfully when isolate is true and runner is vitest', async () => {
+      harness.useTarget('test', {
+        ...BASE_OPTIONS,
+        runner: 'vitest' as any,
+        isolate: true,
+      });
+
+      const { result } = await harness.executeOnce();
+      expect(result?.success).toBeTrue();
+    });
+
+    it('should run tests successfully when isolate is false and runner is vitest', async () => {
+      harness.useTarget('test', {
+        ...BASE_OPTIONS,
+        runner: 'vitest' as any,
+        isolate: false,
+      });
+
+      const { result } = await harness.executeOnce();
+      expect(result?.success).toBeTrue();
+    });
+  });
+});