feat(@angular/build): add experimental vitest unit-testing support

When using the application build system via the `@angular/build` package
(default for new projects starting in v20), a new experimental unit-test
builder is available that initially uses vitest. This experimental system
is intended to provide support for investigation of future unit testing
efforts within the Angular CLI. As this is experimental, no SemVer guarantees
are provided, the API and behavior may change, and there may be unexpected
behavior. Available test runners may be added or removed as well.

The setup is somewhat different than the previous unit-testing builders.
It uses a similar mechanism to that of the `dev-server` and requires a
`buildTarget` option. This allows the code building aspects of the unit-
testing process to leverage pre-existing option values that are already
defined for development. If differing option values are required for testing,
an additional build target configuration specifically for testing can be
used.

The current vitest support has multiple caveats including but not limited to:

* No watch support
* `jsdom` based testing only (`jsdom` must be installed in the project)
* Custom vitest configuration is not supported

An example configuration that would replace the `test` target for a project
is as follows:
```
"test": {
    "builder": "@angular/build:unit-test",
    "options": {
        "tsConfig": "tsconfig.spec.json",
        "buildTarget": "::development",
        "runner": "vitest"
    }
}
```

Author: clydin

modules/testing/builder/BUILD.bazel

@@ -20,6 +20,7 @@ ts_project(
         # Needed at runtime by some builder tests relying on SSR being
         # resolvable in the test project.
         ":node_modules/@angular/ssr",
+        ":node_modules/vitest",
     ] + glob(["projects/**/*"]),
     deps = [
         ":node_modules/@angular-devkit/architect",

modules/testing/builder/package.json

@@ -4,6 +4,7 @@
     "@angular-devkit/architect": "workspace:*",
     "@angular/ssr": "workspace:*",
     "@angular-devkit/build-angular": "workspace:*",
-    "rxjs": "7.8.2"
+    "rxjs": "7.8.2",
+    "vitest": "3.1.1"
   }
 }

packages/angular/build/BUILD.bazel

@@ -36,6 +36,11 @@ ts_json_schema(
     src = "src/builders/ng-packagr/schema.json",
 )
 
+ts_json_schema(
+    name = "unit_test_schema",
+    src = "src/builders/unit-test/schema.json",
+)
+
 copy_to_bin(
     name = "schemas",
     srcs = glob(["**/schema.json"]),
@@ -79,6 +84,7 @@ ts_project(
         "//packages/angular/build:src/builders/extract-i18n/schema.ts",
         "//packages/angular/build:src/builders/karma/schema.ts",
         "//packages/angular/build:src/builders/ng-packagr/schema.ts",
+        "//packages/angular/build:src/builders/unit-test/schema.ts",
     ],
     data = RUNTIME_ASSETS,
     deps = [
@@ -109,6 +115,7 @@ ts_project(
         ":node_modules/source-map-support",
         ":node_modules/tinyglobby",
         ":node_modules/vite",
+        ":node_modules/vitest",
         ":node_modules/watchpack",
         "//:node_modules/@angular/common",
         "//:node_modules/@angular/compiler",
@@ -252,6 +259,36 @@ ts_project(
     ],
 )
 
+ts_project(
+    name = "unit-test_integration_test_lib",
+    testonly = True,
+    srcs = glob(include = ["src/builders/unit-test/tests/**/*.ts"]),
+    deps = [
+        ":build",
+        "//packages/angular/build/private",
+        "//modules/testing/builder",
+        ":node_modules/@angular-devkit/architect",
+        ":node_modules/@angular-devkit/core",
+        "//:node_modules/@types/node",
+
+        # unit test specific test deps
+        ":node_modules/vitest",
+        ":node_modules/jsdom",
+
+        # Base dependencies for the hello-world-app.
+        "//:node_modules/@angular/common",
+        "//:node_modules/@angular/compiler",
+        "//:node_modules/@angular/compiler-cli",
+        "//:node_modules/@angular/core",
+        "//:node_modules/@angular/platform-browser",
+        "//:node_modules/@angular/router",
+        ":node_modules/rxjs",
+        "//:node_modules/tslib",
+        "//:node_modules/typescript",
+        "//:node_modules/zone.js",
+    ],
+)
+
 jasmine_test(
     name = "application_integration_tests",
     size = "large",
@@ -281,6 +318,13 @@ jasmine_test(
     shard_count = 10,
 )
 
+jasmine_test(
+    name = "unit-test_integration_tests",
+    size = "large",
+    data = [":unit-test_integration_test_lib"],
+    shard_count = 10,
+)
+
 genrule(
     name = "license",
     srcs = ["//:LICENSE"],

packages/angular/build/builders.json

@@ -24,6 +24,11 @@
       "implementation": "./src/builders/ng-packagr/index",
       "schema": "./src/builders/ng-packagr/schema.json",
       "description": "Build a library with ng-packagr."
+    },
+    "unit-test": {
+      "implementation": "./src/builders/unit-test",
+      "schema": "./src/builders/unit-test/schema.json",
+      "description": "[EXPERIMENTAL] Run application unit tests."
     }
   }
 }

packages/angular/build/package.json

@@ -51,10 +51,12 @@
   "devDependencies": {
     "@angular/ssr": "workspace:*",
     "@angular-devkit/core": "workspace:*",
+    "jsdom": "26.1.0",
     "less": "4.3.0",
     "ng-packagr": "20.0.0-next.8",
     "postcss": "8.5.3",
-    "rxjs": "7.8.2"
+    "rxjs": "7.8.2",
+    "vitest": "3.1.2"
   },
   "peerDependencies": {
     "@angular/core": "0.0.0-ANGULAR-FW-PEER-DEP",
@@ -71,7 +73,8 @@
     "postcss": "^8.4.0",
     "tailwindcss": "^2.0.0 || ^3.0.0 || ^4.0.0",
     "tslib": "^2.3.0",
-    "typescript": ">=5.8 <5.9"
+    "typescript": ">=5.8 <5.9",
+    "vitest": "^3.1.1"
   },
   "peerDependenciesMeta": {
     "@angular/core": {
@@ -106,6 +109,9 @@
     },
     "tailwindcss": {
       "optional": true
+    },
+    "vitest": {
+      "optional": true
     }
   }
 }

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

@@ -0,0 +1,171 @@
+/**
+ * @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 type { BuilderContext, BuilderOutput } from '@angular-devkit/architect';
+import assert from 'node:assert';
+import { randomUUID } from 'node:crypto';
+import path from 'node:path';
+import { createVirtualModulePlugin } from '../../tools/esbuild/virtual-module-plugin';
+import { loadEsmModule } from '../../utils/load-esm';
+import { buildApplicationInternal } from '../application';
+import type {
+  ApplicationBuilderExtensions,
+  ApplicationBuilderInternalOptions,
+} from '../application/options';
+import { ResultKind } from '../application/results';
+import { OutputHashing } from '../application/schema';
+import { writeTestFiles } from '../karma/application_builder';
+import { findTests, getTestEntrypoints } from '../karma/find-tests';
+import { normalizeOptions } from './options';
+import type { Schema as UnitTestOptions } from './schema';
+
+export type { UnitTestOptions };
+
+/**
+ * @experimental Direct usage of this function is considered experimental.
+ */
+export async function* execute(
+  options: UnitTestOptions,
+  context: BuilderContext,
+  extensions: ApplicationBuilderExtensions = {},
+): AsyncIterable<BuilderOutput> {
+  // Determine project name from builder context target
+  const projectName = context.target?.project;
+  if (!projectName) {
+    context.logger.error(
+      `The "${context.builder.builderName}" builder requires a target to be specified.`,
+    );
+
+    return;
+  }
+
+  context.logger.warn(
+    `NOTE: The "${context.builder.builderName}" builder is currently EXPERIMENTAL and not ready for production use.`,
+  );
+
+  const normalizedOptions = await normalizeOptions(context, projectName, options);
+  const { projectSourceRoot, workspaceRoot, runnerName } = normalizedOptions;
+
+  if (runnerName !== 'vitest') {
+    context.logger.error('Unknown test runner: ' + runnerName);
+
+    return;
+  }
+
+  // Find test files
+  const testFiles = await findTests(
+    normalizedOptions.include,
+    normalizedOptions.exclude,
+    workspaceRoot,
+    projectSourceRoot,
+  );
+
+  if (testFiles.length === 0) {
+    context.logger.error('No tests found.');
+
+    return { success: false };
+  }
+
+  const entryPoints = getTestEntrypoints(testFiles, { projectSourceRoot, workspaceRoot });
+  entryPoints.set('init-testbed', 'angular:test-bed-init');
+
+  const { startVitest } = await loadEsmModule<typeof import('vitest/node')>('vitest/node');
+
+  // Setup test file build options based on application build target options
+  const buildTargetOptions = (await context.validateOptions(
+    await context.getTargetOptions(normalizedOptions.buildTarget),
+    await context.getBuilderNameForTarget(normalizedOptions.buildTarget),
+  )) as unknown as ApplicationBuilderInternalOptions;
+
+  if (buildTargetOptions.polyfills?.includes('zone.js')) {
+    buildTargetOptions.polyfills.push('zone.js/testing');
+  }
+
+  const outputPath = path.join(context.workspaceRoot, 'dist/test-out', randomUUID());
+  const buildOptions: ApplicationBuilderInternalOptions = {
+    ...buildTargetOptions,
+    watch: normalizedOptions.watch,
+    outputPath,
+    index: false,
+    browser: undefined,
+    server: undefined,
+    localize: false,
+    budgets: [],
+    serviceWorker: false,
+    appShell: false,
+    ssr: false,
+    prerender: false,
+    sourceMap: { scripts: true, vendor: false, styles: false },
+    outputHashing: OutputHashing.None,
+    optimization: false,
+    tsConfig: normalizedOptions.tsConfig,
+    entryPoints,
+    externalDependencies: ['vitest', ...(buildTargetOptions.externalDependencies ?? [])],
+  };
+  extensions ??= {};
+  extensions.codePlugins ??= [];
+  const virtualTestBedInit = createVirtualModulePlugin({
+    namespace: 'angular:test-bed-init',
+    loadContent: async () => {
+      const contents: string[] = [
+        // Initialize the Angular testing environment
+        `import { getTestBed } from '@angular/core/testing';`,
+        `import { BrowserTestingModule, platformBrowserTesting } from '@angular/platform-browser/testing';`,
+        `getTestBed().initTestEnvironment(BrowserTestingModule, platformBrowserTesting(), {`,
+        `  errorOnUnknownElements: true,`,
+        `  errorOnUnknownProperties: true,`,
+        '});',
+      ];
+
+      return {
+        contents: contents.join('\n'),
+        loader: 'js',
+        resolveDir: projectSourceRoot,
+      };
+    },
+  });
+  extensions.codePlugins.unshift(virtualTestBedInit);
+
+  let instance: import('vitest/node').Vitest | undefined;
+
+  for await (const result of buildApplicationInternal(buildOptions, context, extensions)) {
+    if (result.kind === ResultKind.Failure) {
+      continue;
+    } else if (result.kind !== ResultKind.Full) {
+      assert.fail('A full build result is required from the application builder.');
+    }
+
+    assert(result.files, 'Builder did not provide result files.');
+
+    await writeTestFiles(result.files, outputPath);
+
+    const setupFiles = ['init-testbed.js'];
+    if (buildTargetOptions?.polyfills?.length) {
+      setupFiles.push('polyfills.js');
+    }
+
+    instance ??= await startVitest('test', undefined /* cliFilters */, undefined /* options */, {
+      test: {
+        root: outputPath,
+        setupFiles,
+        environment: 'jsdom',
+        watch: normalizedOptions.watch,
+        coverage: {
+          enabled: normalizedOptions.codeCoverage,
+          exclude: normalizedOptions.codeCoverageExclude,
+          excludeAfterRemap: true,
+        },
+      },
+    });
+
+    // Check if all the tests pass to calculate the result
+    const testModules = instance.state.getTestModules();
+
+    yield { success: testModules.every((testModule) => testModule.ok()) };
+  }
+}

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

@@ -0,0 +1,16 @@
+/**
+ * @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 { type Builder, createBuilder } from '@angular-devkit/architect';
+import { type UnitTestOptions, execute } from './builder';
+
+export { type UnitTestOptions, execute };
+
+const builder: Builder<UnitTestOptions> = createBuilder(execute);
+
+export default builder;