@angular/build 20.1.0-rc.0 → 20.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@angular/build",
-  "version": "20.1.0-rc.0",
+  "version": "20.1.0",
   "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.2001.0-rc.0",
+    "@angular-devkit/architect": "0.2001.0",
     "@babel/core": "7.27.7",
     "@babel/helper-annotate-as-pure": "7.27.3",
     "@babel/helper-split-export-declaration": "7.24.7",
@@ -53,17 +53,17 @@
     "lmdb": "3.4.1"
   },
   "peerDependencies": {
-    "@angular/core": "^20.0.0 || ^20.1.0-next.0",
-    "@angular/compiler": "^20.0.0 || ^20.1.0-next.0",
-    "@angular/compiler-cli": "^20.0.0 || ^20.1.0-next.0",
-    "@angular/localize": "^20.0.0 || ^20.1.0-next.0",
-    "@angular/platform-browser": "^20.0.0 || ^20.1.0-next.0",
-    "@angular/platform-server": "^20.0.0 || ^20.1.0-next.0",
-    "@angular/service-worker": "^20.0.0 || ^20.1.0-next.0",
-    "@angular/ssr": "^20.1.0-rc.0",
+    "@angular/core": "^20.0.0",
+    "@angular/compiler": "^20.0.0",
+    "@angular/compiler-cli": "^20.0.0",
+    "@angular/localize": "^20.0.0",
+    "@angular/platform-browser": "^20.0.0",
+    "@angular/platform-server": "^20.0.0",
+    "@angular/service-worker": "^20.0.0",
+    "@angular/ssr": "^20.1.0",
     "karma": "^6.4.0",
     "less": "^4.2.0",
-    "ng-packagr": "^20.0.0 || ^20.1.0-next.0",
+    "ng-packagr": "^20.0.0",
     "postcss": "^8.4.0",
     "tailwindcss": "^2.0.0 || ^3.0.0 || ^4.0.0",
     "tslib": "^2.3.0",

package/src/builders/karma/application_builder.d.ts

@@ -6,10 +6,8 @@
  * found in the LICENSE file at https://angular.dev/license
  */
 import type { BuilderContext, BuilderOutput } from '@angular-devkit/architect';
-import type { ConfigOptions } from 'karma';
 import { ResultFile } from '../application/results';
 import { Schema as KarmaBuilderOptions } from './schema';
-export declare function execute(options: KarmaBuilderOptions, context: BuilderContext, karmaOptions: ConfigOptions, transforms?: {
-    karmaOptions?: (options: ConfigOptions) => ConfigOptions;
-}): AsyncIterable<BuilderOutput>;
+import type { KarmaBuilderTransformsOptions } from './index';
+export declare function execute(options: KarmaBuilderOptions, context: BuilderContext, transforms?: KarmaBuilderTransformsOptions): AsyncIterable<BuilderOutput>;
 export declare function writeTestFiles(files: Record<string, ResultFile>, testDir: string): Promise<void>;

package/src/builders/karma/application_builder.js

@@ -39,13 +39,16 @@ var __importStar = (this && this.__importStar) || (function () {
         return result;
     };
 })();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.execute = execute;
 exports.writeTestFiles = writeTestFiles;
 const node_crypto_1 = require("node:crypto");
 const fs = __importStar(require("node:fs/promises"));
 const node_module_1 = require("node:module");
-const path = __importStar(require("node:path"));
+const node_path_1 = __importDefault(require("node:path"));
 const tinyglobby_1 = require("tinyglobby");
 const bundler_context_1 = require("../../tools/esbuild/bundler-context");
 const utils_1 = require("../../tools/esbuild/utils");
@@ -55,6 +58,7 @@ const index_1 = require("../application/index");
 const results_1 = require("../application/results");
 const schema_1 = require("../application/schema");
 const find_tests_1 = require("./find-tests");
+const options_1 = require("./options");
 const localResolve = (0, node_module_1.createRequire)(__filename).resolve;
 const isWindows = process.platform === 'win32';
 class ApplicationBuildError extends Error {
@@ -79,20 +83,23 @@ class AngularAssetsMiddleware {
         // The latest build files will use the platform path separator.
         let pathname = url.pathname.slice(1);
         if (isWindows) {
-            pathname = pathname.replaceAll(path.posix.sep, path.win32.sep);
+            pathname = pathname.replaceAll(node_path_1.default.posix.sep, node_path_1.default.win32.sep);
         }
         const file = this.latestBuildFiles.files[pathname];
         if (!file) {
             next();
             return;
         }
+        // Implementation of serverFile can be found here:
+        // https://github.com/karma-runner/karma/blob/84f85e7016efc2266fa6b3465f494a3fa151c85c/lib/middleware/common.js#L10
         switch (file.origin) {
             case 'disk':
                 this.serveFile(file.inputPath, undefined, res, undefined, undefined, /* doNotCache */ true);
                 break;
             case 'memory':
                 // Include pathname to help with Content-Type headers.
-                this.serveFile(`/unused/${url.pathname}`, undefined, res, undefined, file.contents, true);
+                this.serveFile(`/unused/${url.pathname}`, undefined, res, undefined, file.contents, 
+                /* doNotCache */ false);
                 break;
         }
     }
@@ -228,13 +235,15 @@ function injectKarmaReporter(buildOptions, buildIterator, karmaConfig, controlle
         ],
     });
 }
-function execute(options, context, karmaOptions, transforms = {}) {
+function execute(options, context, transforms) {
+    const normalizedOptions = (0, options_1.normalizeOptions)(context, options);
+    const karmaOptions = getBaseKarmaOptions(normalizedOptions, context);
     let karmaServer;
     return new ReadableStream({
         async start(controller) {
             let init;
             try {
-                init = await initializeApplication(options, context, karmaOptions, transforms);
+                init = await initializeApplication(normalizedOptions, context, karmaOptions, transforms);
             }
             catch (err) {
                 if (err instanceof ApplicationBuildError) {
@@ -272,13 +281,7 @@ async function getProjectSourceRoot(context) {
     const { projectSourceRoot } = (0, project_metadata_1.getProjectRootPaths)(context.workspaceRoot, projectMetadata);
     return projectSourceRoot;
 }
-function normalizePolyfills(polyfills) {
-    if (typeof polyfills === 'string') {
-        polyfills = [polyfills];
-    }
-    else if (!polyfills) {
-        polyfills = [];
-    }
+function normalizePolyfills(polyfills = []) {
     const jasmineGlobalEntryPoint = localResolve('./polyfills/jasmine_global.js');
     const jasmineGlobalCleanupEntrypoint = localResolve('./polyfills/jasmine_global_cleanup.js');
     const sourcemapEntrypoint = localResolve('./polyfills/init_sourcemaps.js');
@@ -293,12 +296,12 @@ function normalizePolyfills(polyfills) {
 }
 async function collectEntrypoints(options, context, projectSourceRoot) {
     // Glob for files to test.
-    const testFiles = await (0, find_tests_1.findTests)(options.include ?? [], options.exclude ?? [], context.workspaceRoot, projectSourceRoot);
+    const testFiles = await (0, find_tests_1.findTests)(options.include, options.exclude, context.workspaceRoot, projectSourceRoot);
     return (0, find_tests_1.getTestEntrypoints)(testFiles, { projectSourceRoot, workspaceRoot: context.workspaceRoot });
 }
 // eslint-disable-next-line max-lines-per-function
-async function initializeApplication(options, context, karmaOptions, transforms = {}) {
-    const outputPath = path.join(context.workspaceRoot, 'dist/test-out', (0, node_crypto_1.randomUUID)());
+async function initializeApplication(options, context, karmaOptions, transforms) {
+    const outputPath = node_path_1.default.join(context.workspaceRoot, 'dist/test-out', (0, node_crypto_1.randomUUID)());
     const projectSourceRoot = await getProjectSourceRoot(context);
     const [karma, entryPoints] = await Promise.all([
         Promise.resolve().then(() => __importStar(require('karma'))),
@@ -329,19 +332,13 @@ async function initializeApplication(options, context, karmaOptions, transforms
         index: false,
         outputHashing: schema_1.OutputHashing.None,
         optimization: false,
-        sourceMap: options.codeCoverage
-            ? {
-                scripts: true,
-                styles: true,
-                vendor: true,
-            }
-            : options.sourceMap,
+        sourceMap: options.sourceMap,
         instrumentForCoverage,
         styles: options.styles,
         scripts: options.scripts,
         polyfills,
         webWorkerTsConfig: options.webWorkerTsConfig,
-        watch: options.watch ?? !karmaOptions.singleRun,
+        watch: options.watch,
         stylePreprocessorOptions: options.stylePreprocessorOptions,
         inlineStyleLanguage: options.inlineStyleLanguage,
         fileReplacements: options.fileReplacements,
@@ -410,6 +407,7 @@ async function initializeApplication(options, context, karmaOptions, transforms
             scriptsFiles.push({
                 pattern: `${outputPath}/${outputName}`,
                 watched: false,
+                included: typeof scriptEntry === 'string' ? true : scriptEntry.inject !== false,
                 type: 'js',
             });
         }
@@ -436,7 +434,7 @@ async function initializeApplication(options, context, karmaOptions, transforms
         // Serve CSS outputs on page load, these are the global styles.
         karmaOptions.files.push({ pattern: `*.css`, type: 'css', watched: false });
     }
-    const parsedKarmaConfig = await karma.config.parseConfig(options.karmaConfig && path.resolve(context.workspaceRoot, options.karmaConfig), transforms.karmaOptions ? transforms.karmaOptions(karmaOptions) : karmaOptions, { promiseConfig: true, throwErrors: true });
+    const parsedKarmaConfig = await karma.config.parseConfig(options.karmaConfig, transforms?.karmaOptions ? await transforms.karmaOptions(karmaOptions) : karmaOptions, { promiseConfig: true, throwErrors: true });
     // Check for jsdom which does not support executing ESM scripts.
     // If present, remove jsdom and issue a warning.
     const updatedBrowsers = parsedKarmaConfig.browsers?.filter((browser) => browser !== 'jsdom');
@@ -480,8 +478,8 @@ async function initializeApplication(options, context, karmaOptions, transforms
                 junitReporterOptions.outputDir = context.workspaceRoot;
             }
             else if (typeof junitReporterOptions.outputDir === 'string' &&
-                !path.isAbsolute(junitReporterOptions.outputDir)) {
-                junitReporterOptions.outputDir = path.join(context.workspaceRoot, junitReporterOptions.outputDir);
+                !node_path_1.default.isAbsolute(junitReporterOptions.outputDir)) {
+                junitReporterOptions.outputDir = node_path_1.default.join(context.workspaceRoot, junitReporterOptions.outputDir);
             }
         }
         else {
@@ -511,9 +509,9 @@ async function writeTestFiles(files, testDir) {
         if (file.type !== bundler_context_1.BuildOutputFileType.Browser && file.type !== bundler_context_1.BuildOutputFileType.Media) {
             return;
         }
-        const fullFilePath = path.join(testDir, filePath);
+        const fullFilePath = node_path_1.default.join(testDir, filePath);
         // Ensure output subdirectories exist
-        const fileBasePath = path.dirname(fullFilePath);
+        const fileBasePath = node_path_1.default.dirname(fullFilePath);
         if (fileBasePath && !directoryExists.has(fileBasePath)) {
             await fs.mkdir(fileBasePath, { recursive: true });
             directoryExists.add(fileBasePath);
@@ -554,7 +552,71 @@ function getInstrumentationExcludedPaths(root, excludedPaths) {
     const excluded = new Set();
     for (const excludeGlob of excludedPaths) {
         const excludePath = excludeGlob[0] === '/' ? excludeGlob.slice(1) : excludeGlob;
-        (0, tinyglobby_1.globSync)(excludePath, { cwd: root }).forEach((p) => excluded.add(path.join(root, p)));
+        (0, tinyglobby_1.globSync)(excludePath, { cwd: root }).forEach((p) => excluded.add(node_path_1.default.join(root, p)));
     }
     return excluded;
 }
+function getBaseKarmaOptions(options, context) {
+    // Determine project name from builder context target
+    const projectName = context.target?.project;
+    if (!projectName) {
+        throw new Error(`The 'karma' builder requires a target to be specified.`);
+    }
+    const karmaOptions = options.karmaConfig
+        ? {}
+        : getBuiltInKarmaConfig(context.workspaceRoot, projectName);
+    const singleRun = !options.watch;
+    karmaOptions.singleRun = singleRun;
+    // Workaround https://github.com/angular/angular-cli/issues/28271, by clearing context by default
+    // for single run executions. Not clearing context for multi-run (watched) builds allows the
+    // Jasmine Spec Runner to be visible in the browser after test execution.
+    karmaOptions.client ??= {};
+    karmaOptions.client.clearContext ??= singleRun;
+    // Convert browsers from a string to an array
+    if (options.browsers) {
+        karmaOptions.browsers = options.browsers;
+    }
+    if (options.reporters) {
+        karmaOptions.reporters = options.reporters;
+    }
+    return karmaOptions;
+}
+function getBuiltInKarmaConfig(workspaceRoot, projectName) {
+    let coverageFolderName = projectName.charAt(0) === '@' ? projectName.slice(1) : projectName;
+    coverageFolderName = coverageFolderName.toLowerCase();
+    const workspaceRootRequire = (0, node_module_1.createRequire)(workspaceRoot + '/');
+    // Any changes to the config here need to be synced to: packages/schematics/angular/config/files/karma.conf.js.template
+    return {
+        basePath: '',
+        frameworks: ['jasmine'],
+        plugins: [
+            'karma-jasmine',
+            'karma-chrome-launcher',
+            'karma-jasmine-html-reporter',
+            'karma-coverage',
+        ].map((p) => workspaceRootRequire(p)),
+        jasmineHtmlReporter: {
+            suppressAll: true, // removes the duplicated traces
+        },
+        coverageReporter: {
+            dir: node_path_1.default.join(workspaceRoot, 'coverage', coverageFolderName),
+            subdir: '.',
+            reporters: [{ type: 'html' }, { type: 'text-summary' }],
+        },
+        reporters: ['progress', 'kjhtml'],
+        browsers: ['Chrome'],
+        customLaunchers: {
+            // Chrome configured to run in a bazel sandbox.
+            // Disable the use of the gpu and `/dev/shm` because it causes Chrome to
+            // crash on some environments.
+            // See:
+            //   https://github.com/puppeteer/puppeteer/blob/v1.0.0/docs/troubleshooting.md#tips
+            //   https://stackoverflow.com/questions/50642308/webdriverexception-unknown-error-devtoolsactiveport-file-doesnt-exist-while-t
+            ChromeHeadlessNoSandbox: {
+                base: 'ChromeHeadless',
+                flags: ['--no-sandbox', '--headless', '--disable-gpu', '--disable-dev-shm-usage'],
+            },
+        },
+        restartOnFileChange: true,
+    };
+}

package/src/builders/karma/index.d.ts

@@ -8,16 +8,13 @@
 import { type Builder, type BuilderContext, type BuilderOutput } from '@angular-devkit/architect';
 import type { ConfigOptions } from 'karma';
 import type { Schema as KarmaBuilderOptions } from './schema';
-export type KarmaConfigOptions = ConfigOptions & {
-    buildWebpack?: unknown;
-    configFile?: string;
-};
+export interface KarmaBuilderTransformsOptions {
+    karmaOptions?: (options: ConfigOptions) => ConfigOptions | Promise<ConfigOptions>;
+}
 /**
  * @experimental Direct usage of this function is considered experimental.
  */
-export declare function execute(options: KarmaBuilderOptions, context: BuilderContext, transforms?: {
-    karmaOptions?: (options: KarmaConfigOptions) => KarmaConfigOptions;
-}): AsyncIterable<BuilderOutput>;
+export declare function execute(options: KarmaBuilderOptions, context: BuilderContext, transforms?: KarmaBuilderTransformsOptions): AsyncIterable<BuilderOutput>;
 export type { KarmaBuilderOptions };
 declare const builder: Builder<KarmaBuilderOptions>;
 export default builder;

package/src/builders/karma/index.js

@@ -39,101 +39,15 @@ var __importStar = (this && this.__importStar) || (function () {
         return result;
     };
 })();
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.execute = execute;
 const architect_1 = require("@angular-devkit/architect");
-const node_module_1 = require("node:module");
-const node_path_1 = __importDefault(require("node:path"));
 /**
  * @experimental Direct usage of this function is considered experimental.
  */
-async function* execute(options, context, transforms = {}) {
+async function* execute(options, context, transforms) {
     const { execute } = await Promise.resolve().then(() => __importStar(require('./application_builder')));
-    const karmaOptions = getBaseKarmaOptions(options, context);
-    yield* execute(options, context, karmaOptions, transforms);
-}
-function getBaseKarmaOptions(options, context) {
-    let singleRun;
-    if (options.watch !== undefined) {
-        singleRun = !options.watch;
-    }
-    // Determine project name from builder context target
-    const projectName = context.target?.project;
-    if (!projectName) {
-        throw new Error(`The 'karma' builder requires a target to be specified.`);
-    }
-    const karmaOptions = options.karmaConfig
-        ? {}
-        : getBuiltInKarmaConfig(context.workspaceRoot, projectName);
-    karmaOptions.singleRun = singleRun;
-    // Workaround https://github.com/angular/angular-cli/issues/28271, by clearing context by default
-    // for single run executions. Not clearing context for multi-run (watched) builds allows the
-    // Jasmine Spec Runner to be visible in the browser after test execution.
-    karmaOptions.client ??= {};
-    karmaOptions.client.clearContext ??= singleRun ?? false; // `singleRun` defaults to `false` per Karma docs.
-    // Convert browsers from a string to an array
-    if (typeof options.browsers === 'string' && options.browsers) {
-        karmaOptions.browsers = options.browsers.split(',').map((browser) => browser.trim());
-    }
-    else if (options.browsers === false) {
-        karmaOptions.browsers = [];
-    }
-    if (options.reporters) {
-        // Split along commas to make it more natural, and remove empty strings.
-        const reporters = options.reporters
-            .reduce((acc, curr) => acc.concat(curr.split(',')), [])
-            .filter((x) => !!x);
-        if (reporters.length > 0) {
-            karmaOptions.reporters = reporters;
-        }
-    }
-    return karmaOptions;
-}
-function getBuiltInKarmaConfig(workspaceRoot, projectName) {
-    let coverageFolderName = projectName.charAt(0) === '@' ? projectName.slice(1) : projectName;
-    coverageFolderName = coverageFolderName.toLowerCase();
-    const workspaceRootRequire = (0, node_module_1.createRequire)(workspaceRoot + '/');
-    // Any changes to the config here need to be synced to: packages/schematics/angular/config/files/karma.conf.js.template
-    return {
-        basePath: '',
-        rootUrl: '/',
-        frameworks: ['jasmine'],
-        plugins: [
-            'karma-jasmine',
-            'karma-chrome-launcher',
-            'karma-jasmine-html-reporter',
-            'karma-coverage',
-        ].map((p) => workspaceRootRequire(p)),
-        proxies: {
-            '/': '/base/',
-        },
-        jasmineHtmlReporter: {
-            suppressAll: true, // removes the duplicated traces
-        },
-        coverageReporter: {
-            dir: node_path_1.default.join(workspaceRoot, 'coverage', coverageFolderName),
-            subdir: '.',
-            reporters: [{ type: 'html' }, { type: 'text-summary' }],
-        },
-        reporters: ['progress', 'kjhtml'],
-        browsers: ['Chrome'],
-        customLaunchers: {
-            // Chrome configured to run in a bazel sandbox.
-            // Disable the use of the gpu and `/dev/shm` because it causes Chrome to
-            // crash on some environments.
-            // See:
-            //   https://github.com/puppeteer/puppeteer/blob/v1.0.0/docs/troubleshooting.md#tips
-            //   https://stackoverflow.com/questions/50642308/webdriverexception-unknown-error-devtoolsactiveport-file-doesnt-exist-while-t
-            ChromeHeadlessNoSandbox: {
-                base: 'ChromeHeadless',
-                flags: ['--no-sandbox', '--headless', '--disable-gpu', '--disable-dev-shm-usage'],
-            },
-        },
-        restartOnFileChange: true,
-    };
+    yield* execute(options, context, transforms);
 }
 const builder = (0, architect_1.createBuilder)(execute);
 exports.default = builder;

package/src/builders/karma/options.d.ts

@@ -0,0 +1,42 @@
+/**
+ * @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 { Schema as KarmaBuilderOptions } from './schema';
+export type NormalizedKarmaBuilderOptions = ReturnType<typeof normalizeOptions>;
+export declare function normalizeOptions(context: BuilderContext, options: KarmaBuilderOptions): {
+    sourceMap: import("./schema").SourceMapUnion | undefined;
+    karmaConfig: string | undefined;
+    reporters: string[] | undefined;
+    browsers: string[] | undefined;
+    watch: boolean;
+    include: string[];
+    exclude: string[];
+    aot?: boolean;
+    assets?: import("./schema").AssetPattern[];
+    codeCoverage?: boolean;
+    codeCoverageExclude?: string[];
+    define?: {
+        [key: string]: string;
+    };
+    externalDependencies?: string[];
+    fileReplacements?: import("./schema").FileReplacement[];
+    inlineStyleLanguage?: import("./schema").InlineStyleLanguage;
+    loader?: {
+        [key: string]: any;
+    };
+    main?: string;
+    poll?: number;
+    polyfills?: string[];
+    preserveSymlinks?: boolean;
+    progress?: boolean;
+    scripts?: import("./schema").ScriptElement[];
+    stylePreprocessorOptions?: import("./schema").StylePreprocessorOptions;
+    styles?: import("./schema").StyleElement[];
+    tsConfig: string;
+    webWorkerTsConfig?: string;
+};

package/src/builders/karma/options.js

@@ -0,0 +1,43 @@
+"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.normalizeOptions = normalizeOptions;
+const node_path_1 = require("node:path");
+function normalizeOptions(context, options) {
+    const { sourceMap, karmaConfig, browsers, watch = true, include = [], exclude = [], reporters = [], ...rest } = options;
+    let normalizedBrowsers;
+    if (typeof options.browsers === 'string' && options.browsers) {
+        normalizedBrowsers = options.browsers.split(',').map((browser) => browser.trim());
+    }
+    else if (options.browsers === false) {
+        normalizedBrowsers = [];
+    }
+    // Split along commas to make it more natural, and remove empty strings.
+    const normalizedReporters = reporters
+        .reduce((acc, curr) => acc.concat(curr.split(',')), [])
+        .filter((x) => !!x);
+    // Sourcemaps are always needed when code coverage is enabled.
+    const normalizedSourceMap = options.codeCoverage
+        ? {
+            scripts: true,
+            styles: true,
+            vendor: true,
+        }
+        : sourceMap;
+    return {
+        ...rest,
+        sourceMap: normalizedSourceMap,
+        karmaConfig: karmaConfig ? (0, node_path_1.resolve)(context.workspaceRoot, karmaConfig) : undefined,
+        reporters: normalizedReporters.length ? normalizedReporters : undefined,
+        browsers: normalizedBrowsers,
+        watch,
+        include,
+        exclude,
+    };
+}

package/src/builders/karma/schema.d.ts

@@ -120,7 +120,7 @@ export type Schema = {
      */
     tsConfig: string;
     /**
-     * Run build when files change.
+     * Re-run tests when source files change.
      */
     watch?: boolean;
     /**

package/src/builders/karma/schema.json

@@ -229,7 +229,8 @@
     },
     "watch": {
       "type": "boolean",
-      "description": "Run build when files change."
+      "description": "Re-run tests when source files change.",
+      "default": true
     },
     "poll": {
       "type": "number",

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

@@ -7,9 +7,9 @@
  */
 import type { BuilderContext, BuilderOutput } from '@angular-devkit/architect';
 import type { ApplicationBuilderExtensions } from '../application/options';
-import type { Schema as UnitTestOptions } from './schema';
-export type { UnitTestOptions };
+import type { Schema as UnitTestBuilderOptions } from './schema';
+export type { UnitTestBuilderOptions };
 /**
  * @experimental Direct usage of this function is considered experimental.
  */
-export declare function execute(options: UnitTestOptions, context: BuilderContext, extensions?: ApplicationBuilderExtensions): AsyncIterable<BuilderOutput>;
+export declare function execute(options: UnitTestBuilderOptions, context: BuilderContext, extensions?: ApplicationBuilderExtensions): AsyncIterable<BuilderOutput>;

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

@@ -94,7 +94,11 @@ async function* execute(options, context, extensions = {}) {
         optimization: false,
         tsConfig: normalizedOptions.tsConfig,
         entryPoints,
-        externalDependencies: ['vitest', ...(buildTargetOptions.externalDependencies ?? [])],
+        externalDependencies: [
+            'vitest',
+            '@vitest/browser/context',
+            ...(buildTargetOptions.externalDependencies ?? []),
+        ],
     };
     extensions ??= {};
     extensions.codePlugins ??= [];
@@ -144,9 +148,11 @@ async function* execute(options, context, extensions = {}) {
         return { success: false };
     }
     // 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
         ? {

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

@@ -6,7 +6,7 @@
  * 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>;
+import { type UnitTestBuilderOptions, execute } from './builder';
+export { type UnitTestBuilderOptions, execute };
+declare const builder: Builder<UnitTestBuilderOptions>;
 export default builder;

package/src/builders/unit-test/karma-bridge.d.ts

@@ -6,5 +6,5 @@
  * found in the LICENSE file at https://angular.dev/license
  */
 import type { BuilderContext, BuilderOutput } from '@angular-devkit/architect';
-import { type NormalizedUnitTestOptions } from './options';
-export declare function useKarmaBuilder(context: BuilderContext, unitTestOptions: NormalizedUnitTestOptions): Promise<AsyncIterable<BuilderOutput>>;
+import { type NormalizedUnitTestBuilderOptions } from './options';
+export declare function useKarmaBuilder(context: BuilderContext, unitTestOptions: NormalizedUnitTestBuilderOptions): Promise<AsyncIterable<BuilderOutput>>;

package/src/builders/unit-test/karma-bridge.js

@@ -46,6 +46,9 @@ async function useKarmaBuilder(context, unitTestOptions) {
     if (unitTestOptions.debug) {
         context.logger.warn('The "karma" test runner does not support the "debug" option. The option will be ignored.');
     }
+    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)));
     buildTargetOptions.polyfills = (0, options_1.injectTestingPolyfills)(buildTargetOptions.polyfills);
     const options = {

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

@@ -6,9 +6,9 @@
  * 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<{
+import type { Schema as UnitTestBuilderOptions } from './schema';
+export type NormalizedUnitTestBuilderOptions = Awaited<ReturnType<typeof normalizeOptions>>;
+export declare function normalizeOptions(context: BuilderContext, projectName: string, options: UnitTestBuilderOptions): Promise<{
     workspaceRoot: string;
     projectRoot: string;
     projectSourceRoot: string;
@@ -27,5 +27,6 @@ export declare function normalizeOptions(context: BuilderContext, projectName: s
     watch: boolean;
     debug: boolean;
     providersFile: string | undefined;
+    setupFiles: string[];
 }>;
 export declare function injectTestingPolyfills(polyfills?: string[]): string[];

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

@@ -54,6 +54,9 @@ async function normalizeOptions(context, projectName, options) {
         watch: options.watch ?? (0, tty_1.isTTY)(),
         debug: options.debug ?? false,
         providersFile: options.providersFile && node_path_1.default.join(workspaceRoot, options.providersFile),
+        setupFiles: options.setupFiles
+            ? options.setupFiles.map((setupFile) => node_path_1.default.join(workspaceRoot, setupFile))
+            : [],
     };
 }
 function injectTestingPolyfills(polyfills = []) {

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

@@ -55,12 +55,19 @@ export type Schema = {
      * The name of the test runner to use for test execution.
      */
     runner: Runner;
+    /**
+     * 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.
+     */
+    setupFiles?: string[];
     /**
      * The name of the TypeScript configuration file.
      */
     tsConfig: string;
     /**
-     * Run build when files change.
+     * Re-run tests when source files change. Defaults to `true` in TTY environments and `false`
+     * otherwise.
      */
     watch?: boolean;
 };

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

@@ -44,7 +44,7 @@
     },
     "watch": {
       "type": "boolean",
-      "description": "Run build when files change."
+      "description": "Re-run tests when source files change. Defaults to `true` in TTY environments and `false` otherwise."
     },
     "debug": {
       "type": "boolean",
@@ -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,

package/src/index.d.ts

@@ -12,3 +12,5 @@ export type { BuildOutputAsset } from './tools/esbuild/bundler-execution-result'
 export { executeDevServerBuilder, type DevServerBuilderOptions, type DevServerBuilderOutput, } from './builders/dev-server';
 export { execute as executeExtractI18nBuilder, type ExtractI18nBuilderOptions, } from './builders/extract-i18n';
 export { execute as executeNgPackagrBuilder, type NgPackagrBuilderOptions, } from './builders/ng-packagr';
+export { execute as executeUnitTestBuilder, type UnitTestBuilderOptions, } from './builders/unit-test';
+export { execute as executeKarmaBuilder, type KarmaBuilderOptions } from './builders/karma';

package/src/index.js

@@ -7,7 +7,7 @@
  * found in the LICENSE file at https://angular.dev/license
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.executeNgPackagrBuilder = exports.executeExtractI18nBuilder = exports.executeDevServerBuilder = exports.BuildOutputFileType = exports.buildApplication = void 0;
+exports.executeKarmaBuilder = exports.executeUnitTestBuilder = exports.executeNgPackagrBuilder = exports.executeExtractI18nBuilder = exports.executeDevServerBuilder = exports.BuildOutputFileType = exports.buildApplication = void 0;
 var application_1 = require("./builders/application");
 Object.defineProperty(exports, "buildApplication", { enumerable: true, get: function () { return application_1.buildApplication; } });
 var bundler_context_1 = require("./tools/esbuild/bundler-context");
@@ -18,3 +18,7 @@ var extract_i18n_1 = require("./builders/extract-i18n");
 Object.defineProperty(exports, "executeExtractI18nBuilder", { enumerable: true, get: function () { return extract_i18n_1.execute; } });
 var ng_packagr_1 = require("./builders/ng-packagr");
 Object.defineProperty(exports, "executeNgPackagrBuilder", { enumerable: true, get: function () { return ng_packagr_1.execute; } });
+var unit_test_1 = require("./builders/unit-test");
+Object.defineProperty(exports, "executeUnitTestBuilder", { enumerable: true, get: function () { return unit_test_1.execute; } });
+var karma_1 = require("./builders/karma");
+Object.defineProperty(exports, "executeKarmaBuilder", { enumerable: true, get: function () { return karma_1.execute; } });

package/src/private.d.ts

@@ -11,7 +11,6 @@ export { buildApplicationInternal } from './builders/application';
 export type { ApplicationBuilderInternalOptions } from './builders/application/options';
 export { type Result, type ResultFile, ResultKind } from './builders/application/results';
 export { serveWithVite } from './builders/dev-server/vite-server';
-export { execute as executeKarmaInternal } from './builders/karma/application_builder';
 export * from './tools/babel/plugins';
 export type { ExternalResultMetadata } from './tools/esbuild/bundler-execution-result';
 export { emitFilesToDisk } from './tools/esbuild/utils';

package/src/private.js

@@ -21,7 +21,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.loadPostcssConfiguration = exports.generateSearchDirectories = exports.findTailwindConfiguration = exports.getTestEntrypoints = exports.findTests = exports.assertCompatibleAngularVersion = exports.getSupportedBrowsers = exports.generateBuildStatsTable = exports.augmentAppWithServiceWorker = exports.purgeStaleBuildCache = exports.createTranslationLoader = exports.loadProxyConfiguration = exports.InlineCriticalCssProcessor = exports.IndexHtmlGenerator = exports.loadTranslations = exports.createI18nOptions = exports.deleteOutputDir = exports.checkPort = exports.JavaScriptTransformer = exports.createJitResourceTransformer = exports.SourceFileCache = exports.SassWorkerImplementation = exports.transformSupportedBrowsersToTargets = exports.emitFilesToDisk = exports.executeKarmaInternal = exports.serveWithVite = exports.ResultKind = exports.buildApplicationInternal = void 0;
+exports.loadPostcssConfiguration = exports.generateSearchDirectories = exports.findTailwindConfiguration = exports.getTestEntrypoints = exports.findTests = exports.assertCompatibleAngularVersion = exports.getSupportedBrowsers = exports.generateBuildStatsTable = exports.augmentAppWithServiceWorker = exports.purgeStaleBuildCache = exports.createTranslationLoader = exports.loadProxyConfiguration = exports.InlineCriticalCssProcessor = exports.IndexHtmlGenerator = exports.loadTranslations = exports.createI18nOptions = exports.deleteOutputDir = exports.checkPort = exports.JavaScriptTransformer = exports.createJitResourceTransformer = exports.SourceFileCache = exports.SassWorkerImplementation = exports.transformSupportedBrowsersToTargets = exports.emitFilesToDisk = exports.serveWithVite = exports.ResultKind = exports.buildApplicationInternal = void 0;
 exports.createCompilerPlugin = createCompilerPlugin;
 /**
  * @fileoverview
@@ -39,8 +39,6 @@ var results_1 = require("./builders/application/results");
 Object.defineProperty(exports, "ResultKind", { enumerable: true, get: function () { return results_1.ResultKind; } });
 var vite_server_1 = require("./builders/dev-server/vite-server");
 Object.defineProperty(exports, "serveWithVite", { enumerable: true, get: function () { return vite_server_1.serveWithVite; } });
-var application_builder_1 = require("./builders/karma/application_builder");
-Object.defineProperty(exports, "executeKarmaInternal", { enumerable: true, get: function () { return application_builder_1.execute; } });
 // Tools
 __exportStar(require("./tools/babel/plugins"), exports);
 var utils_1 = require("./tools/esbuild/utils");

package/src/tools/esbuild/angular/diagnostics.js

@@ -55,9 +55,12 @@ function convertTypeScriptDiagnosticInfo(typescript, info, textPrefix) {
 function convertTypeScriptDiagnostic(typescript, diagnostic) {
     let codePrefix = 'TS';
     let code = `${diagnostic.code}`;
-    if (diagnostic.source === 'ngtsc') {
+    // Custom ngtsc diagnostics are prefixed with -99 which isn't a valid TypeScript diagnostic code.
+    // Strip it and mark the diagnostic as coming from Angular. Note that we can't rely on
+    // `diagnostic.source`, because it isn't always produced. This is identical to:
+    // https://github.com/angular/angular/blob/main/packages/compiler-cli/src/ngtsc/diagnostics/src/util.ts
+    if (code.startsWith('-99')) {
         codePrefix = 'NG';
-        // Remove `-99` Angular prefix from diagnostic code
         code = code.slice(3);
     }
     const message = convertTypeScriptDiagnosticInfo(typescript, diagnostic, `${codePrefix}${code}: `);

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.1.0-rc.0';
+const VERSION = '20.1.0';
 function hasCacheMetadata(value) {
     return (!!value &&
         typeof value === 'object' &&

package/src/utils/version.js

@@ -28,7 +28,7 @@ function assertCompatibleAngularVersion(projectRoot) {
             'This likely indicates a corrupted local installation. Please try reinstalling your packages.');
         process.exit(2);
     }
-    const supportedAngularSemver = '^20.0.0 || ^20.1.0-next.0';
+    const supportedAngularSemver = '^20.0.0';
     if (angularPkgJson['version'] === '0.0.0' || supportedAngularSemver.startsWith('0.0.0')) {
         // Internal CLI and FW testing version.
         return;