refactor: configure Zone.js for Jest tests

This configures polyfills to set up the environment before executing Jest tests. We need to do three things:
1. Set the global `jest` symbol. Jest executing in ESM does not provide the `jest` global and users are expected to import from `@jest/globals` or `import.meta.jest`. Zone.js is not compatible with this yet, so we need to manually define the `jest` global for Zone to read it.
2. Run user polyfills, (typically including `zone.js` and `zone.js/testing`). Zone reads the `jest` global to recognize the environment it is in and patch the relevant functions to load fake async properly. Users can override this part if they are building a Zoneless application or have custom polyfills for other browser functionality.
3. Initalize `TestBed`. This configures the `TestBed` environment so users don't have to manually configure it for each test file.

Ordering is very important for these operations, which complicates the implementation somewhat. `zone.js/testing` does not include an import on `zone.js`, meaning there was no guarnatee the bundler would sort their executions in the correct order. Similarly, `zone.js` does not import anything from Jest, so it is not trivial to inject the `globalThis.jest = import.meta.jest;` line before Zone loads. Even setting polyfills to `[jestGlobal, 'zone.js, 'zone.js/testing', initTestBed]` doesn't work because code splitting rearranges the order of operations in an incompatible way. Instead, these are implemented as distinct entry points in `browser-esbuild` with Jest's `--setupFilesAfterEnv` option executing them in the correct order.

Ideally, we could drop the global initialization altogether once Zone.js knows to look for `import.meta.jest` in an ESM context. Also we might be able to reduce down to a single polyfills entry point if `zone.js/testing` had an import on `zone.js` to apply correct ordering.

Author: dgp1130

packages/angular_devkit/build_angular/BUILD.bazel

@@ -96,6 +96,7 @@ ts_library(
             "builders.json",
             "src/**/schema.json",
             "src/**/*.js",
+            "src/**/*.mjs",
             "src/**/*.html",
         ],
     ),

packages/angular_devkit/build_angular/src/builders/jest/index.ts

@@ -56,10 +56,13 @@ export default createBuilder(
 
     // Build all the test files.
     const testFiles = await findTestFiles(options, context.workspaceRoot);
+    const jestGlobal = path.join(__dirname, 'jest-global.mjs');
+    const initTestBed = path.join(__dirname, 'init-test-bed.mjs');
     const buildResult = await build(context, {
-      entryPoints: testFiles,
+      // Build all the test files and also the `jest-global` and `init-test-bed` scripts.
+      entryPoints: new Set([...testFiles, jestGlobal, initTestBed]),
       tsConfig: options.tsConfig,
-      polyfills: options.polyfills,
+      polyfills: options.polyfills ?? ['zone.js', 'zone.js/testing'],
       outputPath: testOut,
       aot: false,
       index: null,
@@ -83,21 +86,32 @@ export default createBuilder(
       '--experimental-vm-modules',
       jest,
 
-      `--rootDir=${testOut}`,
+      `--rootDir="${testOut}"`,
       '--testEnvironment=jsdom',
 
       // TODO(dgp1130): Enable cache once we have a mechanism for properly clearing / disabling it.
       '--no-cache',
 
       // Run basically all files in the output directory, any excluded files were already dropped by the build.
-      `--testMatch=${path.join('<rootDir>', '**', '*.mjs')}`,
-
-      // Load polyfills before each test, and don't run them directly as a test.
-      `--setupFilesAfterEnv=${path.join('<rootDir>', 'polyfills.mjs')}`,
-      `--testPathIgnorePatterns=${path.join('<rootDir>', 'polyfills\\.mjs')}`,
+      `--testMatch="<rootDir>/**/*.mjs"`,
+
+      // Load polyfills and initialize the environment before executing each test file.
+      // IMPORTANT: Order matters here.
+      // First, we execute `jest-global.mjs` to initialize the `jest` global variable.
+      // Second, we execute user polyfills, including `zone.js` and `zone.js/testing`. This is dependent on the Jest global so it can patch
+      // the environment for fake async to work correctly.
+      // Third, we initialize `TestBed`. This is dependent on fake async being set up correctly beforehand.
+      `--setupFilesAfterEnv="<rootDir>/jest-global.mjs"`,
+      ...(options.polyfills ? [`--setupFilesAfterEnv="<rootDir>/polyfills.mjs"`] : []),
+      `--setupFilesAfterEnv="<rootDir>/init-test-bed.mjs"`,
+
+      // Don't run any infrastructure files as tests, they are manually loaded where needed.
+      `--testPathIgnorePatterns="<rootDir>/jest-global\\.mjs"`,
+      ...(options.polyfills ? [`--testPathIgnorePatterns="<rootDir>/polyfills\\.mjs"`] : []),
+      `--testPathIgnorePatterns="<rootDir>/init-test-bed\\.mjs"`,
 
       // Skip shared chunks, as they are not entry points to tests.
-      `--testPathIgnorePatterns=${path.join('<rootDir>', 'chunk-.*\\.mjs')}`,
+      `--testPathIgnorePatterns="<rootDir>/chunk-.*\\.mjs"`,
 
       // Optionally enable color.
       ...(colors.enabled ? ['--colors'] : []),

packages/angular_devkit/build_angular/src/builders/jest/init-test-bed.mjs

@@ -0,0 +1,18 @@
+/**
+ * @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.io/license
+ */
+
+// TODO(dgp1130): These imports likely don't resolve in stricter package environments like `pnpm`, since they are resolved relative to
+// `@angular-devkit/build-angular` rather than the user's workspace. Should look into virtual modules to support those use cases.
+
+import { getTestBed } from '@angular/core/testing';
+import { BrowserDynamicTestingModule, platformBrowserDynamicTesting } from '@angular/platform-browser-dynamic/testing';
+
+getTestBed().initTestEnvironment(BrowserDynamicTestingModule, platformBrowserDynamicTesting(), {
+  errorOnUnknownElements: true,
+  errorOnUnknownProperties: true,
+});

packages/angular_devkit/build_angular/src/builders/jest/jest-global.mjs

@@ -0,0 +1,19 @@
+/**
+ * @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.io/license
+ */
+
+/**
+ * @fileoverview Zone.js requires the `jest` global to be initialized in order to know that it must patch the environment to support Jest
+ * execution. When running ESM code, Jest does _not_ inject the global `jest` symbol, so Zone.js would not normally know it is running
+ * within Jest as users are supposed to import from `@jest/globals` or use `import.meta.jest`. Zone.js is not currently aware of this, so we
+ * manually set this global to get Zone.js to run correctly.
+ * 
+ * TODO(dgp1130): Update Zone.js to directly support Jest ESM executions so we can drop this.
+ */
+
+// eslint-disable-next-line no-undef
+globalThis.jest = import.meta.jest;