fix(@angular/build): avoid top-level await and add zoneless option for Vitest runner

Previously, the Vitest unit-test runner used dynamic import strategies (`'dynamic'` and `'dynamic-zone'`) within the generated TestBed initialization virtual file (`createTestBedInitVirtualFile`) to load `zone.js` and `zone.js/testing`.

This logic was fundamentally flawed:
1. When Zone.js was loaded dynamically at runtime via the `'dynamic'` strategy, esbuild did not downlevel `async`/`await` because `isZonelessApp` checked the build target's `polyfills` configuration (which did not explicitly list `zone.js`). Consequently, native async/await microtasks bypassed Zone.js context tracking, breaking Zone.js at runtime.
2. If a project used a local polyfills file (e.g. `polyfills: ["src/polyfills.ts"]`), `isZonelessApp` considered the application zoneful and disabled `async-await` support in esbuild. However, esbuild cannot downlevel top-level await when async/await is downleveled, causing esbuild to reject top-level await unconditionally. Hence, the `'dynamic'` strategy never worked as intended.
3. For zoneless applications (such as `polyfills: []`), the syntactic presence of top-level `await` in the virtual file caused esbuild builds to fail when targeting older browsers or Browserslist targets that lack top-level await support, even though Zone was never present at runtime.

This commit resolves these issues by:
- Eliminating top-level `await import()` from `createTestBedInitVirtualFile` entirely.
- Inverting the polyfill strategy so that Zone.js and its testing entry-point are injected directly into `buildOptions.polyfills` before bundling.
- Introducing a new `zoneless` option for the Vitest runner to explicitly control zoneless test execution:
  - `zoneless: true`: Zone.js polyfills are excluded and not loaded.
  - `zoneless: false`: Zone.js and `zone.js/testing` are explicitly injected.
  - Omitted (`undefined`): Existing explicit polyfills are preserved. For library targets where `polyfills` is undefined, Zone.js is injected if installed, accompanied by a deprecation warning advising users to configure the `zoneless` option.

Fixes #33324

Author: alan-agius4

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

@@ -7,6 +7,7 @@
  */
 
 import { type BuilderContext, targetFromTargetString } from '@angular-devkit/architect';
+import type { logging } from '@angular-devkit/core';
 import { constants, promises as fs } from 'node:fs';
 import path from 'node:path';
 import { normalizeCacheOptions } from '../../utils/normalize-cache';
@@ -77,6 +78,7 @@ export async function normalizeOptions(
     runnerConfig,
     isolate,
     splitting = true,
+    zoneless,
   } = options;
 
   if (ui && runner !== Runner.Vitest) {
@@ -87,6 +89,10 @@ export async function normalizeOptions(
     throw new Error('The "isolate" option is only available for the "vitest" runner.');
   }
 
+  if (zoneless !== undefined && (runner ?? Runner.Vitest) !== Runner.Vitest) {
+    throw new Error('The "zoneless" option is only available for the "vitest" runner.');
+  }
+
   const [width, height] = browserViewport?.split('x').map(Number) ?? [];
 
   let tsConfig = options.tsConfig;
@@ -164,6 +170,8 @@ export async function normalizeOptions(
           ? true
           : path.resolve(workspaceRoot, runnerConfig)
         : runnerConfig,
+    zoneless,
+    logger: context.logger,
   };
 }
 

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

@@ -16,7 +16,7 @@ import { toPosixPath } from '../../../../utils/path';
 import { createProjectResolver } from '../../../../utils/resolve-project';
 import type { ApplicationBuilderInternalOptions } from '../../../application/options';
 import { OutputHashing } from '../../../application/schema';
-import { NormalizedUnitTestBuilderOptions } from '../../options';
+import type { NormalizedUnitTestBuilderOptions } from '../../options';
 import { findTests, getTestEntrypoints } from '../../test-discovery';
 import { RunnerOptions } from '../api';
 
@@ -26,14 +26,12 @@ import { RunnerOptions } from '../api';
  * @param providersFile Optional path to a file that exports default providers.
  * @param projectSourceRoot The root directory of the project source.
  * @param teardown Whether to configure TestBed to destroy after each test.
- * @param zoneTestingStrategy How zone.js should be loaded during initialization.
  * @returns The string content of the virtual initialization file.
  */
 function createTestBedInitVirtualFile(
   providersFile: string | undefined,
   projectSourceRoot: string,
   teardown: boolean,
-  zoneTestingStrategy: 'none' | 'static' | 'dynamic' | 'dynamic-zone',
   hasLocalize: boolean,
 ): string {
   let providersImport = 'const providers = [];';
@@ -44,21 +42,6 @@ function createTestBedInitVirtualFile(
     providersImport = `import providers from './${importPath}';`;
   }
 
-  let zoneTestingSnippet = '';
-  if (zoneTestingStrategy === 'static') {
-    zoneTestingSnippet = `import 'zone.js/testing';`;
-  } else if (zoneTestingStrategy === 'dynamic') {
-    zoneTestingSnippet = `if (typeof Zone !== 'undefined') {
-      // 'zone.js/testing' is used to initialize the ZoneJS testing environment.
-      // It must be imported dynamically to avoid a static dependency on 'zone.js'.
-      await import('zone.js/testing');
-    }`;
-  } else if (zoneTestingStrategy === 'dynamic-zone') {
-    zoneTestingSnippet = `
-      await import('zone.js');
-      await import('zone.js/testing');`;
-  }
-
   // The DynamicDOMTestComponentRenderer is used to avoid stale document references
   // when running Vitest in non-isolated mode with JSDOM. It looks up the
   // document dynamically on every operation instead of caching it.
@@ -72,8 +55,6 @@ function createTestBedInitVirtualFile(
     import { afterEach, beforeEach } from 'vitest';
     ${providersImport}
 
-    ${zoneTestingSnippet}
-
     // The beforeEach and afterEach hooks are registered outside the globalThis guard.
     // This ensures that the hooks are always applied, even in non-isolated browser environments.
     // Same as https://github.com/angular/angular/blob/05a03d3f975771bb59c7eefd37c01fa127ee2229/packages/core/testing/srcs/test_hooks.ts#L21-L29
@@ -108,7 +89,6 @@ function createTestBedInitVirtualFile(
     const ANGULAR_TESTBED_SETUP = Symbol.for('@angular/cli/testbed-setup');
     if (!globalThis[ANGULAR_TESTBED_SETUP]) {
       globalThis[ANGULAR_TESTBED_SETUP] = true;
-
       // The Angular TestBed needs to be initialized before any tests are run.
       // In a non-isolated environment, this setup file can be executed multiple times.
       // The guard condition above ensures that the setup is only performed once.
@@ -150,37 +130,65 @@ function adjustOutputHashing(hashing?: OutputHashing): OutputHashing {
 }
 
 /**
- * Resolves the Zone.js testing strategy by inspecting polyfills and resolving zone.js package.
+ * Injects Zone.js and Zone.js testing polyfills into the build options based on the
+ * project configuration, polyfills, and the `zoneless` option.
  *
- * @param buildOptions The partial application builder options.
+ * @param unitTestOptions The normalized unit test builder options.
+ * @param baseBuildOptions The partial application builder options.
  * @param projectSourceRoot The root directory of the project source.
- * @returns The resolved zone testing strategy ('none', 'static', 'dynamic', 'dynamic-zone').
+ * @returns An array of polyfill specifiers to use for testing.
  */
-function getZoneTestingStrategy(
-  buildOptions: Partial<ApplicationBuilderInternalOptions>,
+function injectZoneJsTestingPolyfills(
+  unitTestOptions: NormalizedUnitTestBuilderOptions,
+  baseBuildOptions: Partial<ApplicationBuilderInternalOptions>,
   projectSourceRoot: string,
-): 'none' | 'static' | 'dynamic' | 'dynamic-zone' {
-  if (buildOptions.polyfills?.includes('zone.js/testing')) {
-    return 'none';
+): string[] {
+  const { polyfills } = baseBuildOptions;
+  const { zoneless, logger } = unitTestOptions;
+
+  if (zoneless) {
+    // Tests have been marked as zoneless.
+    return polyfills ? polyfills.filter((polyfill) => !polyfill.startsWith('zone.js')) : [];
   }
 
-  if (buildOptions.polyfills?.includes('zone.js')) {
-    return 'static';
+  if (zoneless === false) {
+    // Tests have been marked as zone.js dependent.
+    const polyfillsSet = new Set(polyfills ?? []);
+    polyfillsSet.add('zone.js');
+    polyfillsSet.add('zone.js/testing');
+
+    return [...polyfillsSet];
   }
 
+  // If polyfills is defined, use it directly.
+  if (polyfills !== undefined) {
+    const polyfillsSet = new Set(polyfills);
+    if (polyfillsSet.has('zone.js/testing')) {
+      return polyfills;
+    }
+
+    if (polyfillsSet.has('zone.js')) {
+      return [...polyfills, 'zone.js/testing'];
+    }
+
+    // Explicit polyfills were provided without zone.js (e.g. zoneless application).
+    return polyfills;
+  }
+
+  // If polyfills is undefined (e.g. library build target), attempt to load zone.js if installed.
   try {
     const projectResolve = createProjectResolver(projectSourceRoot);
     projectResolve('zone.js');
 
-    // If polyfills is undefined (e.g. library build target), load zone.js dynamically.
-    // If polyfills is defined but doesn't include zone.js (e.g. zoneless application), do NOT load zone.js.
-    if (buildOptions.polyfills === undefined) {
-      return 'dynamic-zone';
-    }
+    logger?.warn(
+      'Zone.js polyfills are being automatically injected because "zone.js" was detected in the project dependencies. ' +
+        'This behavior is deprecated. If your project is zoneless, set the "zoneless" option to true in the ' +
+        'test configuration. Otherwise, set the "zoneless" option to false or explicitly add "zone.js" to the "polyfills" option.',
+    );
 
-    return 'dynamic';
+    return ['zone.js', 'zone.js/testing'];
   } catch {
-    return 'none';
+    return [];
   }
 }
 
@@ -254,9 +262,13 @@ export async function getVitestBuildOptions(
     externalDependencies.push(...baseBuildOptions.externalDependencies);
   }
 
+  // Inject the zone.js testing polyfill if Zone.js is installed.
+  const polyfills = injectZoneJsTestingPolyfills(options, baseBuildOptions, projectSourceRoot);
+
   const buildOptions: Partial<ApplicationBuilderInternalOptions> = {
     ...baseBuildOptions,
     watch,
+    polyfills,
     incrementalResults: watch,
     index: false,
     browser: undefined,
@@ -284,9 +296,6 @@ export async function getVitestBuildOptions(
     externalDependencies,
   };
 
-  // Inject the zone.js testing polyfill if Zone.js is installed.
-  const zoneTestingStrategy = getZoneTestingStrategy(buildOptions, projectSourceRoot);
-
   let hasLocalize = false;
   try {
     const projectResolve = createProjectResolver(projectSourceRoot);
@@ -298,7 +307,6 @@ export async function getVitestBuildOptions(
     providersFile,
     projectSourceRoot,
     !options.debug,
-    zoneTestingStrategy,
     hasLocalize,
   );
 

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

@@ -9,7 +9,6 @@
 import assert from 'node:assert';
 import type { TestRunner } from '../api';
 import { DependencyChecker } from '../dependency-checker';
-import { normalizeBrowserName } from './browser-provider';
 import { getVitestBuildOptions } from './build-options';
 import { VitestExecutor } from './executor';
 

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

@@ -265,6 +265,10 @@
       "description": "Specifies the path to a TypeScript file that provides an array of Angular providers for the test environment. The file must contain a default export of the provider array.",
       "minLength": 1
     },
+    "zoneless": {
+      "type": "boolean",
+      "description": "Specifies whether to execute tests in zoneless mode. When set to true, Zone.js polyfills are excluded and Zone.js is not loaded. When set to false, Zone.js and its testing support are explicitly loaded. When omitted, Zone.js is loaded based on the build target polyfills. This option is only available for the Vitest runner."
+    },
     "setupFiles": {
       "type": "array",
       "items": {

packages/angular/build/src/builders/unit-test/tests/behavior/vitest-zone-init_spec.ts

@@ -4,6 +4,8 @@ import {
   describeBuilder,
   UNIT_TEST_BUILDER_INFO,
   setupApplicationTarget,
+  expectLog,
+  expectNoLog,
 } from '../setup';
 
 describeBuilder(execute, UNIT_TEST_BUILDER_INFO, (harness) => {
@@ -68,7 +70,61 @@ describeBuilder(execute, UNIT_TEST_BUILDER_INFO, (harness) => {
       expect(result?.success).toBe(true);
     });
 
-    it('should load Zone and Zone testing support when testing a library and zone.js is installed', async () => {
+    it('should NOT load Zone when zoneless is true even if zone.js is in polyfills', async () => {
+      setupApplicationTarget(harness, {
+        polyfills: ['zone.js'],
+      });
+
+      harness.useTarget('test', {
+        ...BASE_OPTIONS,
+        zoneless: true,
+      });
+
+      harness.writeFile(
+        'src/app/app.component.spec.ts',
+        `
+        import { describe, it, expect } from 'vitest';
+
+        describe('Zoneless Override Test', () => {
+          it('should NOT have Zone defined', () => {
+            expect((globalThis as any).Zone).toBeUndefined();
+          });
+        });
+      `,
+      );
+
+      const { result } = await harness.executeOnce();
+      expect(result?.success).toBeTrue();
+    });
+
+    it('should load Zone when zoneless is false even if polyfills is empty', async () => {
+      setupApplicationTarget(harness, {
+        polyfills: [],
+      });
+
+      harness.useTarget('test', {
+        ...BASE_OPTIONS,
+        zoneless: false,
+      });
+
+      harness.writeFile(
+        'src/app/app.component.spec.ts',
+        `
+        import { describe, it, expect } from 'vitest';
+
+        describe('Zone Forced Test', () => {
+          it('should have Zone defined', () => {
+            expect((globalThis as any).Zone).toBeDefined();
+          });
+        });
+      `,
+      );
+
+      const { result } = await harness.executeOnce();
+      expect(result?.success).toBeTrue();
+    });
+
+    it('should load Zone and emit a deprecation warning when testing a library and zone.js is installed', async () => {
       harness.withBuilderTarget(
         'build',
         async () => ({ success: true }),
@@ -107,8 +163,54 @@ describeBuilder(execute, UNIT_TEST_BUILDER_INFO, (harness) => {
       `,
       );
 
-      const { result } = await harness.executeOnce();
+      const { result, logs } = await harness.executeOnce();
+      expect(result?.success).toBeTrue();
+      expectLog(logs, /Zone\.js polyfills are being automatically injected/);
+    });
+
+    it('should NOT load Zone and not emit warning when testing a library with zoneless: true', async () => {
+      harness.withBuilderTarget(
+        'build',
+        async () => ({ success: true }),
+        {
+          project: 'ng-package.json',
+        },
+        {
+          builderName: '@angular/build:ng-packagr',
+        },
+      );
+
+      await harness.writeFile(
+        'ng-package.json',
+        JSON.stringify({
+          lib: {
+            entryFile: 'src/public-api.ts',
+          },
+        }),
+      );
+
+      harness.useTarget('test', {
+        ...BASE_OPTIONS,
+        zoneless: true,
+        include: ['src/app.component.spec.ts'],
+      });
+
+      await harness.writeFile(
+        'src/app.component.spec.ts',
+        `
+        import { describe, it, expect } from 'vitest';
+
+        describe('Library Zoneless Test', () => {
+          it('should NOT have Zone defined', () => {
+            expect((globalThis as any).Zone).toBeUndefined();
+          });
+        });
+      `,
+      );
+
+      const { result, logs } = await harness.executeOnce();
       expect(result?.success).toBeTrue();
+      expectNoLog(logs, /Zone\.js polyfills are being automatically injected/);
     });
   });
 });