@angular/build 21.0.0-next.3 → 21.0.0-next.5

package/src/builders/unit-test/runners/vitest/executor.js

@@ -12,14 +12,13 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.VitestExecutor = void 0;
 const node_assert_1 = __importDefault(require("node:assert"));
-const promises_1 = require("node:fs/promises");
 const node_path_1 = __importDefault(require("node:path"));
 const error_1 = require("../../../../utils/error");
 const load_esm_1 = require("../../../../utils/load-esm");
 const path_1 = require("../../../../utils/path");
 const results_1 = require("../../../application/results");
-const test_discovery_1 = require("../../test-discovery");
 const browser_provider_1 = require("./browser-provider");
+const plugins_1 = require("./plugins");
 class VitestExecutor {
     vitest;
     projectName;
@@ -31,9 +30,15 @@ class VitestExecutor {
     // Example: `Map<'/path/to/src/app.spec.ts', 'spec-src-app-spec'>`
     testFileToEntryPoint = new Map();
     entryPointToTestFile = new Map();
-    constructor(projectName, options) {
+    constructor(projectName, options, testEntryPointMappings) {
         this.projectName = projectName;
         this.options = options;
+        if (testEntryPointMappings) {
+            for (const [entryPoint, testFile] of testEntryPointMappings) {
+                this.testFileToEntryPoint.set(testFile, entryPoint);
+                this.entryPointToTestFile.set(entryPoint + '.js', testFile);
+            }
+        }
     }
     async *execute(buildResult) {
         if (buildResult.kind === results_1.ResultKind.Full) {
@@ -50,24 +55,6 @@ class VitestExecutor {
                 this.buildResultFiles.set(path, file);
             }
         }
-        // The `getTestEntrypoints` function is used here to create the same mapping
-        // that was used in `build-options.ts` to generate the build entry points.
-        // This is a deliberate duplication to avoid a larger refactoring of the
-        // builder's core interfaces to pass the entry points from the build setup
-        // phase to the execution phase.
-        if (this.testFileToEntryPoint.size === 0) {
-            const { include, exclude = [], workspaceRoot, projectSourceRoot } = this.options;
-            const testFiles = await (0, test_discovery_1.findTests)(include, exclude, workspaceRoot, projectSourceRoot);
-            const entryPoints = (0, test_discovery_1.getTestEntrypoints)(testFiles, {
-                projectSourceRoot,
-                workspaceRoot,
-                removeTestExtension: true,
-            });
-            for (const [entryPoint, testFile] of entryPoints) {
-                this.testFileToEntryPoint.set(testFile, entryPoint);
-                this.entryPointToTestFile.set(entryPoint + '.js', testFile);
-            }
-        }
         // Initialize Vitest if not already present.
         this.vitest ??= await this.initializeVitest();
         const vitest = this.vitest;
@@ -113,118 +100,8 @@ class VitestExecutor {
         }
         return testSetupFiles;
     }
-    createVitestPlugins(testSetupFiles, browserOptions) {
-        const { workspaceRoot } = this.options;
-        return [
-            {
-                name: 'angular:project-init',
-                // Type is incorrect. This allows a Promise<void>.
-                // eslint-disable-next-line @typescript-eslint/no-misused-promises
-                configureVitest: async (context) => {
-                    // Create a subproject that can be configured with plugins for browser mode.
-                    // Plugins defined directly in the vite overrides will not be present in the
-                    // browser specific Vite instance.
-                    await context.injectTestProjects({
-                        test: {
-                            name: this.projectName,
-                            root: workspaceRoot,
-                            globals: true,
-                            setupFiles: testSetupFiles,
-                            // Use `jsdom` if no browsers are explicitly configured.
-                            // `node` is effectively no "environment" and the default.
-                            environment: browserOptions.browser ? 'node' : 'jsdom',
-                            browser: browserOptions.browser,
-                            include: this.options.include,
-                            ...(this.options.exclude ? { exclude: this.options.exclude } : {}),
-                        },
-                        plugins: [
-                            {
-                                name: 'angular:test-in-memory-provider',
-                                enforce: 'pre',
-                                resolveId: (id, importer) => {
-                                    if (importer && (id[0] === '.' || id[0] === '/')) {
-                                        let fullPath;
-                                        if (this.testFileToEntryPoint.has(importer)) {
-                                            fullPath = (0, path_1.toPosixPath)(node_path_1.default.join(this.options.workspaceRoot, id));
-                                        }
-                                        else {
-                                            fullPath = (0, path_1.toPosixPath)(node_path_1.default.join(node_path_1.default.dirname(importer), id));
-                                        }
-                                        const relativePath = node_path_1.default.relative(this.options.workspaceRoot, fullPath);
-                                        if (this.buildResultFiles.has((0, path_1.toPosixPath)(relativePath))) {
-                                            return fullPath;
-                                        }
-                                    }
-                                    if (this.testFileToEntryPoint.has(id)) {
-                                        return id;
-                                    }
-                                    (0, node_assert_1.default)(this.buildResultFiles.size > 0, 'buildResult must be available for resolving.');
-                                    const relativePath = node_path_1.default.relative(this.options.workspaceRoot, id);
-                                    if (this.buildResultFiles.has((0, path_1.toPosixPath)(relativePath))) {
-                                        return id;
-                                    }
-                                },
-                                load: async (id) => {
-                                    (0, node_assert_1.default)(this.buildResultFiles.size > 0, 'buildResult must be available for in-memory loading.');
-                                    // Attempt to load as a source test file.
-                                    const entryPoint = this.testFileToEntryPoint.get(id);
-                                    let outputPath;
-                                    if (entryPoint) {
-                                        outputPath = entryPoint + '.js';
-                                        // To support coverage exclusion of the actual test file, the virtual
-                                        // test entry point only references the built and bundled intermediate file.
-                                        return {
-                                            code: `import "./${outputPath}";`,
-                                        };
-                                    }
-                                    else {
-                                        // Attempt to load as a built artifact.
-                                        const relativePath = node_path_1.default.relative(this.options.workspaceRoot, id);
-                                        outputPath = (0, path_1.toPosixPath)(relativePath);
-                                    }
-                                    const outputFile = this.buildResultFiles.get(outputPath);
-                                    if (outputFile) {
-                                        const sourceMapPath = outputPath + '.map';
-                                        const sourceMapFile = this.buildResultFiles.get(sourceMapPath);
-                                        const code = outputFile.origin === 'memory'
-                                            ? Buffer.from(outputFile.contents).toString('utf-8')
-                                            : await (0, promises_1.readFile)(outputFile.inputPath, 'utf-8');
-                                        const map = sourceMapFile
-                                            ? sourceMapFile.origin === 'memory'
-                                                ? Buffer.from(sourceMapFile.contents).toString('utf-8')
-                                                : await (0, promises_1.readFile)(sourceMapFile.inputPath, 'utf-8')
-                                            : undefined;
-                                        return {
-                                            code,
-                                            map: map ? JSON.parse(map) : undefined,
-                                        };
-                                    }
-                                },
-                            },
-                            {
-                                name: 'angular:html-index',
-                                transformIndexHtml: () => {
-                                    // Add all global stylesheets
-                                    if (this.buildResultFiles.has('styles.css')) {
-                                        return [
-                                            {
-                                                tag: 'link',
-                                                attrs: { href: 'styles.css', rel: 'stylesheet' },
-                                                injectTo: 'head',
-                                            },
-                                        ];
-                                    }
-                                    return [];
-                                },
-                            },
-                        ],
-                    });
-                },
-            },
-        ];
-    }
     async initializeVitest() {
-        const { codeCoverage, reporters, workspaceRoot, browsers, debug, watch } = this.options;
+        const { codeCoverage, reporters, outputFile, workspaceRoot, browsers, debug, watch } = this.options;
         let vitestNodeModule;
         try {
             vitestNodeModule = await (0, load_esm_1.loadEsmModule)('vitest/node');
@@ -244,7 +121,15 @@ class VitestExecutor {
         }
         (0, node_assert_1.default)(this.buildResultFiles.size > 0, 'buildResult must be available before initializing vitest');
         const testSetupFiles = this.prepareSetupFiles();
-        const plugins = this.createVitestPlugins(testSetupFiles, browserOptions);
+        const plugins = (0, plugins_1.createVitestPlugins)(this.options, testSetupFiles, browserOptions, {
+            workspaceRoot,
+            projectSourceRoot: this.options.projectSourceRoot,
+            projectName: this.projectName,
+            include: this.options.include,
+            exclude: this.options.exclude,
+            buildResultFiles: this.buildResultFiles,
+            testFileToEntryPoint: this.testFileToEntryPoint,
+        });
         const debugOptions = debug
             ? {
                 inspectBrk: true,
@@ -259,9 +144,11 @@ class VitestExecutor {
             project: ['base', this.projectName],
             name: 'base',
             include: [],
+            testNamePattern: this.options.filter,
             reporters: reporters ?? ['default'],
+            outputFile,
             watch,
-            coverage: generateCoverageOption(codeCoverage),
+            coverage: generateCoverageOption(codeCoverage, this.projectName),
             ...debugOptions,
         }, {
             server: {
@@ -274,7 +161,7 @@ class VitestExecutor {
     }
 }
 exports.VitestExecutor = VitestExecutor;
-function generateCoverageOption(codeCoverage) {
+function generateCoverageOption(codeCoverage, projectName) {
     if (!codeCoverage) {
         return {
             enabled: false,
@@ -283,6 +170,7 @@ function generateCoverageOption(codeCoverage) {
     return {
         enabled: true,
         excludeAfterRemap: true,
+        reportsDirectory: (0, path_1.toPosixPath)(node_path_1.default.join('coverage', projectName)),
         // Special handling for `exclude`/`reporters` due to an undefined value causing upstream failures
         ...(codeCoverage.exclude ? { exclude: codeCoverage.exclude } : {}),
         ...(codeCoverage.reporters

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

@@ -11,6 +11,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 const node_assert_1 = __importDefault(require("node:assert"));
+const dependency_checker_1 = require("../dependency-checker");
 const build_options_1 = require("./build-options");
 const executor_1 = require("./executor");
 /**
@@ -18,13 +19,29 @@ const executor_1 = require("./executor");
  */
 const VitestTestRunner = {
     name: 'vitest',
+    validateDependencies(options) {
+        const checker = new dependency_checker_1.DependencyChecker(options.projectSourceRoot);
+        checker.check('vitest');
+        if (options.browsers?.length) {
+            checker.check('@vitest/browser');
+            checker.checkAny(['playwright', 'webdriverio'], 'The "browsers" option requires either "playwright" or "webdriverio" to be installed.');
+        }
+        else {
+            // JSDOM is used when no browsers are specified
+            checker.check('jsdom');
+        }
+        if (options.codeCoverage) {
+            checker.check('@vitest/coverage-v8');
+        }
+        checker.report();
+    },
     getBuildOptions(options, baseBuildOptions) {
         return (0, build_options_1.getVitestBuildOptions)(options, baseBuildOptions);
     },
-    async createExecutor(context, options) {
+    async createExecutor(context, options, testEntryPointMappings) {
         const projectName = context.target?.project;
         (0, node_assert_1.default)(projectName, 'The builder requires a target.');
-        return new executor_1.VitestExecutor(projectName, options);
+        return new executor_1.VitestExecutor(projectName, options, testEntryPointMappings);
     },
 };
 exports.default = VitestTestRunner;

package/src/builders/unit-test/runners/vitest/plugins.d.ts

@@ -0,0 +1,23 @@
+/**
+ * @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 { VitestPlugin } from 'vitest/node';
+import type { ResultFile } from '../../../application/results';
+import type { NormalizedUnitTestBuilderOptions } from '../../options';
+import type { BrowserConfiguration } from './browser-provider';
+type VitestPlugins = Awaited<ReturnType<typeof VitestPlugin>>;
+interface PluginOptions {
+    workspaceRoot: string;
+    projectSourceRoot: string;
+    projectName: string;
+    include?: string[];
+    exclude?: string[];
+    buildResultFiles: ReadonlyMap<string, ResultFile>;
+    testFileToEntryPoint: ReadonlyMap<string, string>;
+}
+export declare function createVitestPlugins(options: NormalizedUnitTestBuilderOptions, testSetupFiles: string[], browserOptions: BrowserConfiguration, pluginOptions: PluginOptions): VitestPlugins;
+export {};

package/src/builders/unit-test/runners/vitest/plugins.js

@@ -0,0 +1,131 @@
+"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.createVitestPlugins = createVitestPlugins;
+const node_assert_1 = __importDefault(require("node:assert"));
+const promises_1 = require("node:fs/promises");
+const node_path_1 = __importDefault(require("node:path"));
+const assets_middleware_1 = require("../../../../tools/vite/middlewares/assets-middleware");
+const path_1 = require("../../../../utils/path");
+function createVitestPlugins(options, testSetupFiles, browserOptions, pluginOptions) {
+    const { workspaceRoot, projectName, buildResultFiles, testFileToEntryPoint } = pluginOptions;
+    return [
+        {
+            name: 'angular:project-init',
+            // Type is incorrect. This allows a Promise<void>.
+            // eslint-disable-next-line @typescript-eslint/no-misused-promises
+            configureVitest: async (context) => {
+                // Create a subproject that can be configured with plugins for browser mode.
+                // Plugins defined directly in the vite overrides will not be present in the
+                // browser specific Vite instance.
+                await context.injectTestProjects({
+                    test: {
+                        name: projectName,
+                        root: workspaceRoot,
+                        globals: true,
+                        setupFiles: testSetupFiles,
+                        // Use `jsdom` if no browsers are explicitly configured.
+                        // `node` is effectively no "environment" and the default.
+                        environment: browserOptions.browser ? 'node' : 'jsdom',
+                        browser: browserOptions.browser,
+                        include: options.include,
+                        ...(options.exclude ? { exclude: options.exclude } : {}),
+                    },
+                    plugins: [
+                        {
+                            name: 'angular:test-in-memory-provider',
+                            enforce: 'pre',
+                            resolveId: (id, importer) => {
+                                if (importer && (id[0] === '.' || id[0] === '/')) {
+                                    let fullPath;
+                                    if (testFileToEntryPoint.has(importer)) {
+                                        fullPath = (0, path_1.toPosixPath)(node_path_1.default.join(workspaceRoot, id));
+                                    }
+                                    else {
+                                        fullPath = (0, path_1.toPosixPath)(node_path_1.default.join(node_path_1.default.dirname(importer), id));
+                                    }
+                                    const relativePath = node_path_1.default.relative(workspaceRoot, fullPath);
+                                    if (buildResultFiles.has((0, path_1.toPosixPath)(relativePath))) {
+                                        return fullPath;
+                                    }
+                                }
+                                if (testFileToEntryPoint.has(id)) {
+                                    return id;
+                                }
+                                (0, node_assert_1.default)(buildResultFiles.size > 0, 'buildResult must be available for resolving.');
+                                const relativePath = node_path_1.default.relative(workspaceRoot, id);
+                                if (buildResultFiles.has((0, path_1.toPosixPath)(relativePath))) {
+                                    return id;
+                                }
+                            },
+                            load: async (id) => {
+                                (0, node_assert_1.default)(buildResultFiles.size > 0, 'buildResult must be available for in-memory loading.');
+                                // Attempt to load as a source test file.
+                                const entryPoint = testFileToEntryPoint.get(id);
+                                let outputPath;
+                                if (entryPoint) {
+                                    outputPath = entryPoint + '.js';
+                                    // To support coverage exclusion of the actual test file, the virtual
+                                    // test entry point only references the built and bundled intermediate file.
+                                    return {
+                                        code: `import "./${outputPath}";`,
+                                    };
+                                }
+                                else {
+                                    // Attempt to load as a built artifact.
+                                    const relativePath = node_path_1.default.relative(workspaceRoot, id);
+                                    outputPath = (0, path_1.toPosixPath)(relativePath);
+                                }
+                                const outputFile = buildResultFiles.get(outputPath);
+                                if (outputFile) {
+                                    const sourceMapPath = outputPath + '.map';
+                                    const sourceMapFile = buildResultFiles.get(sourceMapPath);
+                                    const code = outputFile.origin === 'memory'
+                                        ? Buffer.from(outputFile.contents).toString('utf-8')
+                                        : await (0, promises_1.readFile)(outputFile.inputPath, 'utf-8');
+                                    const map = sourceMapFile
+                                        ? sourceMapFile.origin === 'memory'
+                                            ? Buffer.from(sourceMapFile.contents).toString('utf-8')
+                                            : await (0, promises_1.readFile)(sourceMapFile.inputPath, 'utf-8')
+                                        : undefined;
+                                    return {
+                                        code,
+                                        map: map ? JSON.parse(map) : undefined,
+                                    };
+                                }
+                            },
+                            configureServer: (server) => {
+                                server.middlewares.use((0, assets_middleware_1.createBuildAssetsMiddleware)(server.config.base, buildResultFiles));
+                            },
+                        },
+                        {
+                            name: 'angular:html-index',
+                            transformIndexHtml: () => {
+                                // Add all global stylesheets
+                                if (buildResultFiles.has('styles.css')) {
+                                    return [
+                                        {
+                                            tag: 'link',
+                                            attrs: { href: 'styles.css', rel: 'stylesheet' },
+                                            injectTo: 'head',
+                                        },
+                                    ];
+                                }
+                                return [];
+                            },
+                        },
+                    ],
+                });
+            },
+        },
+    ];
+}

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

@@ -3,76 +3,101 @@
  */
 export type Schema = {
     /**
-     * A list of browsers to use for test execution. If undefined, jsdom on Node.js will be used
-     * instead of a browser. For Vitest and Karma, browser names ending with 'Headless' (e.g.,
-     * 'ChromeHeadless') will enable headless mode for that browser.
+     * Specifies the browsers to use for test execution. When not specified, tests are run in a
+     * Node.js environment using jsdom. For both Vitest and Karma, browser names ending with
+     * 'Headless' (e.g., 'ChromeHeadless') will enable headless mode.
      */
     browsers?: string[];
     /**
-     * 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`.
+     * Specifies the build target to use for the unit test build in the format
+     * `project:target[:configuration]`. You can also pass a comma-separated list of
+     * configurations. Example: `project:target:production,staging`.
      */
     buildTarget: string;
     /**
-     * Output a code coverage report.
+     * Enables code coverage reporting for tests.
      */
     codeCoverage?: boolean;
     /**
-     * Globs to exclude from code coverage.
+     * Specifies glob patterns of files to exclude from the code coverage report.
      */
     codeCoverageExclude?: string[];
     /**
-     * Reporters to use for code coverage results.
+     * Specifies the reporters to use for code coverage results. Each reporter can be a string
+     * representing its name, or a tuple containing the name and an options object. Built-in
+     * reporters include 'html', 'lcov', 'lcovonly', 'text', 'text-summary', 'cobertura',
+     * 'json', and 'json-summary'.
      */
     codeCoverageReporters?: SchemaCodeCoverageReporter[];
     /**
-     * Initialize the test runner to support using the Node Inspector for test debugging.
+     * Enables debugging mode for tests, allowing the use of the Node Inspector.
      */
     debug?: boolean;
     /**
-     * Globs of files to exclude, relative to the project root.
+     * Dumps build output files to the `.angular/cache` directory for debugging purposes.
+     */
+    dumpVirtualFiles?: boolean;
+    /**
+     * Specifies glob patterns of files to exclude from testing, 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.
+     * Specifies a regular expression pattern to match against test suite and test names. Only
+     * tests with a name matching the pattern will be executed. For example, `^App` will run
+     * only tests in suites beginning with 'App'.
+     */
+    filter?: string;
+    /**
+     * Specifies glob patterns of files to include for testing, relative to the project root.
+     * This option also has special handling for directory paths (includes all `.spec.ts` files
+     * within) and file paths (includes the corresponding `.spec` file if one exists).
      */
     include?: string[];
     /**
-     * Log progress to the console while building. Defaults to the build target's progress value.
+     * Lists all discovered test files and exits the process without building or executing the
+     * tests.
+     */
+    listTests?: boolean;
+    /**
+     * Specifies a file path for the test report, applying only to the first reporter. To
+     * configure output files for multiple reporters, use the tuple format `['reporter-name', {
+     * outputFile: '...' }]` within the `reporters` option. When not provided, output is written
+     * to the console.
+     */
+    outputFile?: string;
+    /**
+     * Shows build progress information in the console. Defaults to the `progress` setting of
+     * the specified `buildTarget`.
      */
     progress?: boolean;
     /**
-     * TypeScript file that exports an array of Angular providers to use during test execution.
-     * The array must be a default export.
+     * Specifies the path to a TypeScript file that provides an array of Angular providers for
+     * the test environment. The file must contain a default export of the provider array.
      */
     providersFile?: string;
     /**
-     * Test runner reporters to use. Directly passed to the test runner.
+     * Specifies the reporters to use during test execution. Each reporter can be a string
+     * representing its name, or a tuple containing the name and an options object. Built-in
+     * reporters include 'default', 'verbose', 'dots', 'json', 'junit', 'tap', 'tap-flat', and
+     * 'html'. You can also provide a path to a custom reporter.
      */
-    reporters?: string[];
+    reporters?: SchemaReporter[];
     /**
-     * The name of the test runner to use for test execution.
+     * Specifies 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.
+     * A list of paths to global setup files that are executed before the test files. The
+     * application's polyfills and the Angular TestBed are always initialized before these files.
      */
     setupFiles?: string[];
     /**
-     * The name of the TypeScript configuration file.
+     * The path to the TypeScript configuration file, relative to the workspace root.
      */
     tsConfig: string;
     /**
-     * Re-run tests when source files change. Defaults to `true` in TTY environments and `false`
-     * otherwise.
+     * Enables watch mode, which re-runs tests when source files change. Defaults to `true` in
+     * TTY environments and `false` otherwise.
      */
     watch?: boolean;
 };
@@ -90,8 +115,12 @@ export declare enum CoverageReporters {
     Text = "text",
     TextSummary = "text-summary"
 }
+export type SchemaReporter = ReporterReporter[] | string;
+export type ReporterReporter = {
+    [key: string]: any;
+} | string;
 /**
- * The name of the test runner to use for test execution.
+ * Specifies the test runner to use for test execution.
  */
 export declare enum Runner {
     Karma = "karma",

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

@@ -15,7 +15,7 @@ var CoverageReporters;
     CoverageReporters["TextSummary"] = "text-summary";
 })(CoverageReporters || (exports.CoverageReporters = CoverageReporters = {}));
 /**
- * The name of the test runner to use for test execution.
+ * Specifies the test runner to use for test execution.
  */
 var Runner;
 (function (Runner) {