@angular/build 20.0.0-next.7 → 20.0.0-next.8

package/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."
     }
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@angular/build",
-  "version": "20.0.0-next.7",
+  "version": "20.0.0-next.8",
   "description": "Official build system for Angular",
   "keywords": [
     "Angular CLI",
@@ -23,7 +23,7 @@
   "builders": "builders.json",
   "dependencies": {
     "@ampproject/remapping": "2.3.0",
-    "@angular-devkit/architect": "0.2000.0-next.7",
+    "@angular-devkit/architect": "0.2000.0-next.8",
     "@babel/core": "7.26.10",
     "@babel/helper-annotate-as-pure": "7.25.9",
     "@babel/helper-split-export-declaration": "7.24.7",
@@ -60,14 +60,15 @@
     "@angular/platform-browser": "^20.0.0 || ^20.0.0-next.0",
     "@angular/platform-server": "^20.0.0 || ^20.0.0-next.0",
     "@angular/service-worker": "^20.0.0 || ^20.0.0-next.0",
-    "@angular/ssr": "^20.0.0-next.7",
+    "@angular/ssr": "^20.0.0-next.8",
     "karma": "^6.4.0",
     "less": "^4.2.0",
     "ng-packagr": "^20.0.0 || ^20.0.0-next.0",
     "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": {
@@ -102,6 +103,9 @@
     },
     "tailwindcss": {
       "optional": true
+    },
+    "vitest": {
+      "optional": true
     }
   },
   "repository": {

package/src/builders/unit-test/builder.d.ts

@@ -0,0 +1,15 @@
+/**
+ * @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 type { ApplicationBuilderExtensions } from '../application/options';
+import type { Schema as UnitTestOptions } from './schema';
+export type { UnitTestOptions };
+/**
+ * @experimental Direct usage of this function is considered experimental.
+ */
+export declare function execute(options: UnitTestOptions, context: BuilderContext, extensions?: ApplicationBuilderExtensions): AsyncIterable<BuilderOutput>;

package/src/builders/unit-test/builder.js

@@ -0,0 +1,130 @@
+"use strict";
+/**
+ * @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
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.execute = execute;
+const node_assert_1 = __importDefault(require("node:assert"));
+const node_crypto_1 = require("node:crypto");
+const node_path_1 = __importDefault(require("node:path"));
+const virtual_module_plugin_1 = require("../../tools/esbuild/virtual-module-plugin");
+const load_esm_1 = require("../../utils/load-esm");
+const application_1 = require("../application");
+const results_1 = require("../application/results");
+const schema_1 = require("../application/schema");
+const application_builder_1 = require("../karma/application_builder");
+const find_tests_1 = require("../karma/find-tests");
+const options_1 = require("./options");
+/**
+ * @experimental Direct usage of this function is considered experimental.
+ */
+async function* execute(options, context, extensions = {}) {
+    // 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 (0, options_1.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 (0, find_tests_1.findTests)(normalizedOptions.include, normalizedOptions.exclude, workspaceRoot, projectSourceRoot);
+    if (testFiles.length === 0) {
+        context.logger.error('No tests found.');
+        return { success: false };
+    }
+    const entryPoints = (0, find_tests_1.getTestEntrypoints)(testFiles, { projectSourceRoot, workspaceRoot });
+    entryPoints.set('init-testbed', 'angular:test-bed-init');
+    const { startVitest } = await (0, load_esm_1.loadEsmModule)('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)));
+    if (buildTargetOptions.polyfills?.includes('zone.js')) {
+        buildTargetOptions.polyfills.push('zone.js/testing');
+    }
+    const outputPath = node_path_1.default.join(context.workspaceRoot, 'dist/test-out', (0, node_crypto_1.randomUUID)());
+    const buildOptions = {
+        ...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: schema_1.OutputHashing.None,
+        optimization: false,
+        tsConfig: normalizedOptions.tsConfig,
+        entryPoints,
+        externalDependencies: ['vitest', ...(buildTargetOptions.externalDependencies ?? [])],
+    };
+    extensions ??= {};
+    extensions.codePlugins ??= [];
+    const virtualTestBedInit = (0, virtual_module_plugin_1.createVirtualModulePlugin)({
+        namespace: 'angular:test-bed-init',
+        loadContent: async () => {
+            const contents = [
+                // 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;
+    for await (const result of (0, application_1.buildApplicationInternal)(buildOptions, context, extensions)) {
+        if (result.kind === results_1.ResultKind.Failure) {
+            continue;
+        }
+        else if (result.kind !== results_1.ResultKind.Full) {
+            node_assert_1.default.fail('A full build result is required from the application builder.');
+        }
+        (0, node_assert_1.default)(result.files, 'Builder did not provide result files.');
+        await (0, application_builder_1.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()) };
+    }
+}

package/src/builders/unit-test/index.d.ts

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

package/src/builders/unit-test/index.js

@@ -0,0 +1,15 @@
+"use strict";
+/**
+ * @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
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.execute = void 0;
+const architect_1 = require("@angular-devkit/architect");
+const builder_1 = require("./builder");
+Object.defineProperty(exports, "execute", { enumerable: true, get: function () { return builder_1.execute; } });
+const builder = (0, architect_1.createBuilder)(builder_1.execute);
+exports.default = builder;

package/src/builders/unit-test/options.d.ts

@@ -0,0 +1,25 @@
+/**
+ * @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 } from '@angular-devkit/architect';
+import type { Schema as UnitTestOptions } from './schema';
+export type NormalizedUnitTestOptions = Awaited<ReturnType<typeof normalizeOptions>>;
+export declare function normalizeOptions(context: BuilderContext, projectName: string, options: UnitTestOptions): Promise<{
+    workspaceRoot: string;
+    projectRoot: string;
+    projectSourceRoot: string;
+    cacheOptions: import("../../utils/normalize-cache").NormalizedCachedOptions;
+    buildTarget: import("@angular-devkit/architect").Target;
+    include: string[];
+    exclude: string[];
+    runnerName: import("./schema").Runner;
+    codeCoverage: boolean | undefined;
+    codeCoverageExclude: string[] | undefined;
+    tsConfig: string;
+    reporters: string[] | undefined;
+    watch: boolean;
+}>;

package/src/builders/unit-test/options.js

@@ -0,0 +1,61 @@
+"use strict";
+/**
+ * @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
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeOptions = normalizeOptions;
+const architect_1 = require("@angular-devkit/architect");
+const node_path_1 = __importDefault(require("node:path"));
+const normalize_cache_1 = require("../../utils/normalize-cache");
+async function normalizeOptions(context, projectName, options) {
+    // Setup base paths based on workspace root and project information
+    const workspaceRoot = context.workspaceRoot;
+    const projectMetadata = await context.getProjectMetadata(projectName);
+    const projectRoot = normalizeDirectoryPath(node_path_1.default.join(workspaceRoot, projectMetadata.root ?? ''));
+    const projectSourceRoot = normalizeDirectoryPath(node_path_1.default.join(workspaceRoot, projectMetadata.sourceRoot ?? 'src'));
+    // Gather persistent caching option and provide a project specific cache location
+    const cacheOptions = (0, normalize_cache_1.normalizeCacheOptions)(projectMetadata, workspaceRoot);
+    cacheOptions.path = node_path_1.default.join(cacheOptions.path, projectName);
+    // Target specifier defaults to the current project's build target using a development configuration
+    const buildTargetSpecifier = options.buildTarget ?? `::development`;
+    const buildTarget = (0, architect_1.targetFromTargetString)(buildTargetSpecifier, projectName, 'build');
+    const { codeCoverage, codeCoverageExclude, tsConfig, runner, reporters } = options;
+    return {
+        // Project/workspace information
+        workspaceRoot,
+        projectRoot,
+        projectSourceRoot,
+        cacheOptions,
+        // Target/configuration specified options
+        buildTarget,
+        include: options.include ?? ['**/*.spec.ts'],
+        exclude: options.exclude ?? [],
+        runnerName: runner,
+        codeCoverage,
+        codeCoverageExclude,
+        tsConfig,
+        reporters,
+        // TODO: Implement watch support
+        watch: false,
+    };
+}
+/**
+ * Normalize a directory path string.
+ * Currently only removes a trailing slash if present.
+ * @param path A path string.
+ * @returns A normalized path string.
+ */
+function normalizeDirectoryPath(path) {
+    const last = path[path.length - 1];
+    if (last === '/' || last === '\\') {
+        return path.slice(0, -1);
+    }
+    return path;
+}

package/src/builders/unit-test/schema.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Unit testing options for Angular applications.
+ */
+export type Schema = {
+    /**
+     * A build builder target to serve in the format of `project:target[:configuration]`. You
+     * can also pass in more than one configuration name as a comma-separated list. Example:
+     * `project:target:production,staging`.
+     */
+    buildTarget: string;
+    /**
+     * Output a code coverage report.
+     */
+    codeCoverage?: boolean;
+    /**
+     * Globs to exclude from code coverage.
+     */
+    codeCoverageExclude?: string[];
+    /**
+     * Globs of files to exclude, relative to the project root.
+     */
+    exclude?: string[];
+    /**
+     * Globs of files to include, relative to project root.
+     * There are 2 special cases:
+     * - when a path to directory is provided, all spec files ending ".spec.@(ts|tsx)" will be
+     * included
+     * - when a path to a file is provided, and a matching spec file exists it will be included
+     * instead.
+     */
+    include?: string[];
+    /**
+     * Test runner reporters to use. Directly passed to the test runner.
+     */
+    reporters?: string[];
+    /**
+     * The name of the test runner to use for test execution.
+     */
+    runner: Runner;
+    /**
+     * The name of the TypeScript configuration file.
+     */
+    tsConfig: string;
+    /**
+     * Run build when files change.
+     */
+    watch?: boolean;
+};
+/**
+ * The name of the test runner to use for test execution.
+ */
+export declare enum Runner {
+    Vitest = "vitest"
+}

package/src/builders/unit-test/schema.js

@@ -0,0 +1,12 @@
+"use strict";
+// THIS FILE IS AUTOMATICALLY GENERATED. TO UPDATE THIS FILE YOU NEED TO CHANGE THE
+// CORRESPONDING JSON SCHEMA FILE, THEN RUN devkit-admin build (or bazel build ...).
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Runner = void 0;
+/**
+ * The name of the test runner to use for test execution.
+ */
+var Runner;
+(function (Runner) {
+    Runner["Vitest"] = "vitest";
+})(Runner || (exports.Runner = Runner = {}));

package/src/builders/unit-test/schema.json

@@ -0,0 +1,64 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema",
+  "title": "Unit testing",
+  "description": "Unit testing options for Angular applications.",
+  "type": "object",
+  "properties": {
+    "buildTarget": {
+      "type": "string",
+      "description": "A build builder target to serve in the format of `project:target[:configuration]`. You can also pass in more than one configuration name as a comma-separated list. Example: `project:target:production,staging`.",
+      "pattern": "^[^:\\s]*:[^:\\s]*(:[^\\s]+)?$"
+    },
+    "tsConfig": {
+      "type": "string",
+      "description": "The name of the TypeScript configuration file."
+    },
+    "runner": {
+      "type": "string",
+      "description": "The name of the test runner to use for test execution.",
+      "enum": ["vitest"]
+    },
+    "include": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "default": ["**/*.spec.ts"],
+      "description": "Globs of files to include, relative to project root. \nThere are 2 special cases:\n - when a path to directory is provided, all spec files ending \".spec.@(ts|tsx)\" will be included\n - when a path to a file is provided, and a matching spec file exists it will be included instead."
+    },
+    "exclude": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "default": [],
+      "description": "Globs of files to exclude, relative to the project root."
+    },
+    "watch": {
+      "type": "boolean",
+      "description": "Run build when files change."
+    },
+    "codeCoverage": {
+      "type": "boolean",
+      "description": "Output a code coverage report.",
+      "default": false
+    },
+    "codeCoverageExclude": {
+      "type": "array",
+      "description": "Globs to exclude from code coverage.",
+      "items": {
+        "type": "string"
+      },
+      "default": []
+    },
+    "reporters": {
+      "type": "array",
+      "description": "Test runner reporters to use. Directly passed to the test runner.",
+      "items": {
+        "type": "string"
+      }
+    }
+  },
+  "additionalProperties": false,
+  "required": ["buildTarget", "tsConfig", "runner"]
+}

package/src/utils/normalize-cache.js

@@ -10,7 +10,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.normalizeCacheOptions = normalizeCacheOptions;
 const node_path_1 = require("node:path");
 /** Version placeholder is replaced during the build process with actual package version */
-const VERSION = '20.0.0-next.7';
+const VERSION = '20.0.0-next.8';
 function hasCacheMetadata(value) {
     return (!!value &&
         typeof value === 'object' &&