fix(@angular/build): support extra test setup files with unit-test vitest runner

When using the experimental unit-test builder with Vitest, a new `setupFiles`
option is now available. This option is similar to the Vitest option in
that it allows for setup and configuration prior to each test. The `setupFiles`
are executed after any application polyfills as well as after the TestBed
initialization. If custom TestBed initialization is needed (this is not typical),
The TestBed environment can first be reset in a setupFile and then initialized
as needed. Note that resetting the TestBed environment in this way will
cause the `providersFile` to no longer add any providers to the tests and
any custom providers would need to be manually added during initialization.

Author: clydin

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

@@ -228,6 +228,7 @@ export type UnitTestBuilderOptions = {
     providersFile?: string;
     reporters?: string[];
     runner: Runner;
+    setupFiles?: string[];
     tsConfig: string;
     watch?: boolean;
 };

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

@@ -197,9 +197,11 @@ export async function* execute(
   }
 
   // Add setup file entries for TestBed initialization and project polyfills
-  const setupFiles = ['init-testbed.js'];
+  const setupFiles = ['init-testbed.js', ...normalizedOptions.setupFiles];
   if (buildTargetOptions?.polyfills?.length) {
-    setupFiles.push('polyfills.js');
+    // Placed first as polyfills may be required by the Testbed initialization
+    // or other project provided setup files (e.g., zone.js, ECMAScript polyfills).
+    setupFiles.unshift('polyfills.js');
   }
   const debugOptions = normalizedOptions.debug
     ? {

packages/angular/build/src/builders/unit-test/karma-bridge.ts

@@ -21,6 +21,12 @@ export async function useKarmaBuilder(
     );
   }
 
+  if (unitTestOptions.setupFiles.length) {
+    context.logger.warn(
+      'The "karma" test runner does not support the "setupFiles" option. The option will be ignored.',
+    );
+  }
+
   const buildTargetOptions = (await context.validateOptions(
     await context.getTargetOptions(unitTestOptions.buildTarget),
     await context.getBuilderNameForTarget(unitTestOptions.buildTarget),

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

@@ -62,6 +62,9 @@ export async function normalizeOptions(
     watch: options.watch ?? isTTY(),
     debug: options.debug ?? false,
     providersFile: options.providersFile && path.join(workspaceRoot, options.providersFile),
+    setupFiles: options.setupFiles
+      ? options.setupFiles.map((setupFile) => path.join(workspaceRoot, setupFile))
+      : [],
   };
 }
 

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

@@ -76,7 +76,14 @@
             "type": "array",
             "minItems": 1,
             "maxItems": 2,
-            "items": [{ "$ref": "#/definitions/coverage-reporters" }, { "type": "object" }]
+            "items": [
+              {
+                "$ref": "#/definitions/coverage-reporters"
+              },
+              {
+                "type": "object"
+              }
+            ]
           }
         ]
       }
@@ -92,6 +99,13 @@
       "type": "string",
       "description": "TypeScript file that exports an array of Angular providers to use during test execution. The array must be a default export.",
       "minLength": 1
+    },
+    "setupFiles": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "description": "A list of global setup and configuration files that are included before the test files. The application's polyfills are always included before these files. The Angular Testbed is also initialized prior to the execution of these files."
     }
   },
   "additionalProperties": false,