fix(@angular/build): avoid top-level await for Zone.js injection in Vitest runner

[alan-agius4]

PR Checklist

Please check if your PR fulfills the following requirements:

• The commit message follows our guidelines: https://github.com/angular/angular-cli/blob/main/CONTRIBUTING.md#-commit-message-guidelines
• Tests for the changes have been added (for bug fixes / features)
• Docs have been added / updated (for bug fixes / features)

PR Type

What kind of change does this PR introduce?

• Bugfix
• Feature
• Code style update (formatting, local variables)
• Refactoring (no functional changes, no api changes)
• Build related changes
• CI related changes
• Documentation content changes
• Other... Please describe:

What is the current behavior?

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.

Issue Number: Fixes #33324

What is the new behavior?

• Eliminates top-level await import() from createTestBedInitVirtualFile entirely.
• Inverts the polyfill strategy so that zone.js and zone.js/testing are injected directly into buildOptions.polyfills before bundling based on the configured polyfills option (from the test target or inherited from the build target).
• For library targets where polyfills is undefined, zone.js and zone.js/testing are injected if zone.js is installed, accompanied by a deprecation warning advising users to configure the polyfills option in their test configuration ([] for zoneless projects or ["zone.js"] for Zone.js projects).

Does this PR introduce a breaking change?

• Yes
• No

[gemini-code-assist]

Code Review

This pull request introduces a new 'zoneless' option for the Vitest unit-test runner in Angular, allowing developers to explicitly configure whether tests should run in zoneless mode. It refactors the Zone.js testing initialization logic by injecting the necessary polyfills directly into the build options and deprecates the automatic injection of Zone.js based on dependency detection. The review feedback suggests improving robustness by adding a fallback empty array when initializing the polyfills Set and updating the deprecation warning message to provide clearer guidance for library projects that lack a polyfills configuration option.

[thekhegay]

@alan-agius4
ran your branch on installed @angular/build 22.1.8, patched by hand. few polyfills shapes, default browserslist and firefox 88. before on ff88 only [zone.js] and [zone.js + local file] built, rest died on top-level await. now all build and generated module has no await. zoneless true/false work as you describe.

two cases still broken:

• ["src/polyfills.ts"] where that file does import 'zone.js'. builds now, Zone is there at runtime, but zone.js/testing is not added, so fakeAsync fails with "zone-testing.js is needed for the fakeAsync() test helper but could not be found". with polyfills: ["zone.js"] same test gives "Expected to be running in 'ProxyZone'", so there testing part is loaded. zoneless: false fixes it. looks like case 2 from your description.

• ["zone.js/testing"] alone. function returns polyfills untouched so zone.js itself never loads, test dies with ReferenceError: Zone is not defined at zone-testing.js:1989. same before and after your change.

[alan-agius4]

zone.js/testing should never be added to the application's polyfills as test utilities should not be included in app production bundles.

[thekhegay]

my bad, out of scope for this pr.
place it comes from is karma: library schematic writes polyfills: ["zone.js", "zone.js/testing"] into karma test target (@schematics/angular/library), so people migrating karma to vitest move that array over

[alan-agius4]

This PR was merged into the repository. The changes were merged into the following branches:

• main: d09f98e