@depup/angular__build 21.2.2-depup.0

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

@@ -0,0 +1,229 @@
+/**
+ * Unit testing options for Angular applications.
+ */
+export type Schema = {
+    /**
+     * Specifies the browser viewport dimensions for browser-based tests in the format
+     * `widthxheight`.
+     */
+    browserViewport?: string;
+    /**
+     * 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[];
+    /**
+     * Specifies the build target to use for the unit test build in the format
+     * `project:target[:configuration]`. This defaults to the `build` target of the current
+     * project with the `development` configuration. You can also pass a comma-separated list of
+     * configurations. Example: `project:target:production,staging`.
+     */
+    buildTarget?: string;
+    /**
+     * Enables coverage reporting for tests.
+     */
+    coverage?: boolean;
+    /**
+     * Specifies glob patterns of files to exclude from the coverage report.
+     */
+    coverageExclude?: string[];
+    /**
+     * Specifies glob patterns of files to include in the coverage report.
+     */
+    coverageInclude?: string[];
+    /**
+     * Specifies the reporters to use for 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'.
+     */
+    coverageReporters?: SchemaCoverageReporter[];
+    /**
+     * Specifies minimum coverage thresholds that must be met. If thresholds are not met, the
+     * builder will exit with an error.
+     */
+    coverageThresholds?: CoverageThresholds;
+    /**
+     * Specifies coverage watermarks for the HTML reporter. These determine the color coding for
+     * high, medium, and low coverage.
+     */
+    coverageWatermarks?: CoverageWatermarks;
+    /**
+     * Enables debugging mode for tests, allowing the use of the Node Inspector.
+     */
+    debug?: boolean;
+    /**
+     * 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[];
+    /**
+     * 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;
+    /**
+     * Forces all configured browsers to run in headless mode. When using the Vitest runner,
+     * this option is ignored if no browsers are configured. The Karma runner does not support
+     * this option.
+     */
+    headless?: boolean;
+    /**
+     * 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 test files
+     * within) and file paths (includes the corresponding test file if one exists).
+     */
+    include?: string[];
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * 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?: SchemaReporter[];
+    /**
+     * Specifies the test runner to use for test execution.
+     */
+    runner?: Runner;
+    /**
+     * Specifies the configuration file for the selected test runner. If a string is provided,
+     * it will be used as the path to the configuration file. If `true`, the builder will search
+     * for a default configuration file (e.g., `vitest.config.ts` or `karma.conf.js`). If
+     * `false`, no external configuration file will be used.\nFor Vitest, this enables advanced
+     * options and the use of custom plugins. Please note that while the file is loaded, the
+     * Angular team does not provide direct support for its specific contents or any third-party
+     * plugins used within it.
+     */
+    runnerConfig?: RunnerConfig;
+    /**
+     * 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 path to the TypeScript configuration file, relative to the workspace root. Defaults
+     * to `tsconfig.spec.json` in the project root if it exists. If not specified and the
+     * default does not exist, the `tsConfig` from the specified `buildTarget` will be used.
+     */
+    tsConfig?: string;
+    /**
+     * Enables the Vitest UI for interactive test execution. This option is only available for
+     * the Vitest runner.
+     */
+    ui?: boolean;
+    /**
+     * Enables watch mode, which re-runs tests when source files change. Defaults to `true` in
+     * TTY environments and `false` otherwise.
+     */
+    watch?: boolean;
+};
+export type SchemaCoverageReporter = CoverageReporterCoverageReporterUnion[] | CoverageReporterEnum;
+export type CoverageReporterCoverageReporterUnion = CoverageReporterEnum | {
+    [key: string]: any;
+};
+export declare enum CoverageReporterEnum {
+    Cobertura = "cobertura",
+    Html = "html",
+    Json = "json",
+    JsonSummary = "json-summary",
+    Lcov = "lcov",
+    Lcovonly = "lcovonly",
+    Text = "text",
+    TextSummary = "text-summary"
+}
+/**
+ * Specifies minimum coverage thresholds that must be met. If thresholds are not met, the
+ * builder will exit with an error.
+ */
+export type CoverageThresholds = {
+    /**
+     * Minimum percentage of branches covered.
+     */
+    branches?: number;
+    /**
+     * Minimum percentage of functions covered.
+     */
+    functions?: number;
+    /**
+     * Minimum percentage of lines covered.
+     */
+    lines?: number;
+    /**
+     * When true, thresholds are enforced for each file individually.
+     */
+    perFile?: boolean;
+    /**
+     * Minimum percentage of statements covered.
+     */
+    statements?: number;
+};
+/**
+ * Specifies coverage watermarks for the HTML reporter. These determine the color coding for
+ * high, medium, and low coverage.
+ */
+export type CoverageWatermarks = {
+    /**
+     * The high and low watermarks for branches coverage. `[low, high]`
+     */
+    branches?: number[];
+    /**
+     * The high and low watermarks for functions coverage. `[low, high]`
+     */
+    functions?: number[];
+    /**
+     * The high and low watermarks for lines coverage. `[low, high]`
+     */
+    lines?: number[];
+    /**
+     * The high and low watermarks for statements coverage. `[low, high]`
+     */
+    statements?: number[];
+};
+export type SchemaReporter = ReporterReporter[] | string;
+export type ReporterReporter = {
+    [key: string]: any;
+} | string;
+/**
+ * Specifies the test runner to use for test execution.
+ */
+export declare enum Runner {
+    Karma = "karma",
+    Vitest = "vitest"
+}
+/**
+ * Specifies the configuration file for the selected test runner. If a string is provided,
+ * it will be used as the path to the configuration file. If `true`, the builder will search
+ * for a default configuration file (e.g., `vitest.config.ts` or `karma.conf.js`). If
+ * `false`, no external configuration file will be used.\nFor Vitest, this enables advanced
+ * options and the use of custom plugins. Please note that while the file is loaded, the
+ * Angular team does not provide direct support for its specific contents or any third-party
+ * plugins used within it.
+ */
+export type RunnerConfig = boolean | string;

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

@@ -0,0 +1,25 @@
+"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 = exports.CoverageReporterEnum = void 0;
+var CoverageReporterEnum;
+(function (CoverageReporterEnum) {
+    CoverageReporterEnum["Cobertura"] = "cobertura";
+    CoverageReporterEnum["Html"] = "html";
+    CoverageReporterEnum["Json"] = "json";
+    CoverageReporterEnum["JsonSummary"] = "json-summary";
+    CoverageReporterEnum["Lcov"] = "lcov";
+    CoverageReporterEnum["Lcovonly"] = "lcovonly";
+    CoverageReporterEnum["Text"] = "text";
+    CoverageReporterEnum["TextSummary"] = "text-summary";
+})(CoverageReporterEnum || (exports.CoverageReporterEnum = CoverageReporterEnum = {}));
+/**
+ * Specifies the test runner to use for test execution.
+ */
+var Runner;
+(function (Runner) {
+    Runner["Karma"] = "karma";
+    Runner["Vitest"] = "vitest";
+})(Runner || (exports.Runner = Runner = {}));
+//# sourceMappingURL=schema.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["schema.ts"],"names":[],"mappings":";AACA,mFAAmF;AACnF,oFAAoF;;;AAyJpF,IAAY,oBASX;AATD,WAAY,oBAAoB;IAC5B,+CAAuB,CAAA;IACvB,qCAAa,CAAA;IACb,qCAAa,CAAA;IACb,oDAA4B,CAAA;IAC5B,qCAAa,CAAA;IACb,6CAAqB,CAAA;IACrB,qCAAa,CAAA;IACb,oDAA4B,CAAA;AAChC,CAAC,EATW,oBAAoB,oCAApB,oBAAoB,QAS/B;AAwDD;;GAEG;AACH,IAAY,MAGX;AAHD,WAAY,MAAM;IACd,yBAAe,CAAA;IACf,2BAAiB,CAAA;AACrB,CAAC,EAHW,MAAM,sBAAN,MAAM,QAGjB"}

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

@@ -0,0 +1,280 @@
+{
+  "$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": "Specifies the build target to use for the unit test build in the format `project:target[:configuration]`. This defaults to the `build` target of the current project with the `development` configuration. You can also pass a comma-separated list of configurations. Example: `project:target:production,staging`.",
+      "pattern": "^[^:\\s]*:[^:\\s]*(:[^\\s]+)?$"
+    },
+    "tsConfig": {
+      "type": "string",
+      "description": "The path to the TypeScript configuration file, relative to the workspace root. Defaults to `tsconfig.spec.json` in the project root if it exists. If not specified and the default does not exist, the `tsConfig` from the specified `buildTarget` will be used."
+    },
+    "runner": {
+      "type": "string",
+      "description": "Specifies the test runner to use for test execution.",
+      "default": "vitest",
+      "enum": ["karma", "vitest"]
+    },
+    "runnerConfig": {
+      "type": ["string", "boolean"],
+      "description": "Specifies the configuration file for the selected test runner. If a string is provided, it will be used as the path to the configuration file. If `true`, the builder will search for a default configuration file (e.g., `vitest.config.ts` or `karma.conf.js`). If `false`, no external configuration file will be used.\\nFor Vitest, this enables advanced options and the use of custom plugins. Please note that while the file is loaded, the Angular team does not provide direct support for its specific contents or any third-party plugins used within it.",
+      "default": false
+    },
+    "browsers": {
+      "description": "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.",
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "minItems": 1
+    },
+    "browserViewport": {
+      "description": "Specifies the browser viewport dimensions for browser-based tests in the format `widthxheight`.",
+      "type": "string",
+      "pattern": "^\\d+x\\d+$"
+    },
+    "include": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "default": ["**/*.spec.ts", "**/*.test.ts"],
+      "description": "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 test files within) and file paths (includes the corresponding test file if one exists)."
+    },
+    "exclude": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "description": "Specifies glob patterns of files to exclude from testing, relative to the project root."
+    },
+    "filter": {
+      "type": "string",
+      "description": "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'."
+    },
+    "watch": {
+      "type": "boolean",
+      "description": "Enables watch mode, which re-runs tests when source files change. Defaults to `true` in TTY environments and `false` otherwise."
+    },
+    "headless": {
+      "type": "boolean",
+      "description": "Forces all configured browsers to run in headless mode. When using the Vitest runner, this option is ignored if no browsers are configured. The Karma runner does not support this option."
+    },
+    "debug": {
+      "type": "boolean",
+      "description": "Enables debugging mode for tests, allowing the use of the Node Inspector.",
+      "default": false
+    },
+    "ui": {
+      "type": "boolean",
+      "description": "Enables the Vitest UI for interactive test execution. This option is only available for the Vitest runner."
+    },
+    "coverage": {
+      "type": "boolean",
+      "description": "Enables coverage reporting for tests.",
+      "default": false
+    },
+    "coverageInclude": {
+      "type": "array",
+      "description": "Specifies glob patterns of files to include in the coverage report.",
+      "items": {
+        "type": "string"
+      }
+    },
+    "coverageExclude": {
+      "type": "array",
+      "description": "Specifies glob patterns of files to exclude from the coverage report.",
+      "items": {
+        "type": "string"
+      }
+    },
+    "coverageReporters": {
+      "type": "array",
+      "description": "Specifies the reporters to use for 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'.",
+      "items": {
+        "oneOf": [
+          {
+            "enum": [
+              "html",
+              "lcov",
+              "lcovonly",
+              "text",
+              "text-summary",
+              "cobertura",
+              "json",
+              "json-summary"
+            ]
+          },
+          {
+            "type": "array",
+            "minItems": 1,
+            "maxItems": 2,
+            "items": [
+              {
+                "enum": [
+                  "html",
+                  "lcov",
+                  "lcovonly",
+                  "text",
+                  "text-summary",
+                  "cobertura",
+                  "json",
+                  "json-summary"
+                ]
+              },
+              {
+                "type": "object"
+              }
+            ]
+          }
+        ]
+      }
+    },
+    "coverageThresholds": {
+      "type": "object",
+      "description": "Specifies minimum coverage thresholds that must be met. If thresholds are not met, the builder will exit with an error.",
+      "properties": {
+        "perFile": {
+          "type": "boolean",
+          "description": "When true, thresholds are enforced for each file individually."
+        },
+        "statements": {
+          "type": "number",
+          "description": "Minimum percentage of statements covered."
+        },
+        "branches": {
+          "type": "number",
+          "description": "Minimum percentage of branches covered."
+        },
+        "functions": {
+          "type": "number",
+          "description": "Minimum percentage of functions covered."
+        },
+        "lines": {
+          "type": "number",
+          "description": "Minimum percentage of lines covered."
+        }
+      },
+      "additionalProperties": false
+    },
+    "coverageWatermarks": {
+      "type": "object",
+      "description": "Specifies coverage watermarks for the HTML reporter. These determine the color coding for high, medium, and low coverage.",
+      "properties": {
+        "statements": {
+          "type": "array",
+          "description": "The high and low watermarks for statements coverage. `[low, high]`",
+          "items": { "type": "number" },
+          "minItems": 2,
+          "maxItems": 2
+        },
+        "branches": {
+          "type": "array",
+          "description": "The high and low watermarks for branches coverage. `[low, high]`",
+          "items": { "type": "number" },
+          "minItems": 2,
+          "maxItems": 2
+        },
+        "functions": {
+          "type": "array",
+          "description": "The high and low watermarks for functions coverage. `[low, high]`",
+          "items": { "type": "number" },
+          "minItems": 2,
+          "maxItems": 2
+        },
+        "lines": {
+          "type": "array",
+          "description": "The high and low watermarks for lines coverage. `[low, high]`",
+          "items": { "type": "number" },
+          "minItems": 2,
+          "maxItems": 2
+        }
+      },
+      "additionalProperties": false
+    },
+    "reporters": {
+      "type": "array",
+      "description": "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.",
+      "items": {
+        "oneOf": [
+          {
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "enum": ["default", "verbose", "dots", "json", "junit", "tap", "tap-flat", "html"]
+              }
+            ]
+          },
+          {
+            "type": "array",
+            "minItems": 1,
+            "maxItems": 2,
+            "items": [
+              {
+                "anyOf": [
+                  {
+                    "type": "string"
+                  },
+                  {
+                    "enum": [
+                      "default",
+                      "verbose",
+                      "dots",
+                      "json",
+                      "junit",
+                      "tap",
+                      "tap-flat",
+                      "html"
+                    ]
+                  }
+                ]
+              },
+              {
+                "type": "object"
+              }
+            ]
+          }
+        ]
+      }
+    },
+    "outputFile": {
+      "type": "string",
+      "description": "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."
+    },
+    "providersFile": {
+      "type": "string",
+      "description": "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.",
+      "minLength": 1
+    },
+    "setupFiles": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "description": "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."
+    },
+    "progress": {
+      "type": "boolean",
+      "description": "Shows build progress information in the console. Defaults to the `progress` setting of the specified `buildTarget`."
+    },
+    "listTests": {
+      "type": "boolean",
+      "description": "Lists all discovered test files and exits the process without building or executing the tests.",
+      "default": false
+    },
+    "dumpVirtualFiles": {
+      "type": "boolean",
+      "description": "Dumps build output files to the `.angular/cache` directory for debugging purposes.",
+      "default": false,
+      "visible": false
+    }
+  },
+  "additionalProperties": false,
+  "required": []
+}

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

@@ -0,0 +1,47 @@
+/**
+ * @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
+ */
+/**
+ * Finds all test files in the project. This function implements a special handling
+ * for static paths (non-globs) to improve developer experience. For example, if a
+ * user provides a path to a component, this function will find the corresponding
+ * test file. If a user provides a path to a directory, it will find all test
+ * files within that directory.
+ *
+ * @param include Glob patterns of files to include.
+ * @param exclude Glob patterns of files to exclude.
+ * @param workspaceRoot The absolute path to the workspace root.
+ * @param projectSourceRoot The absolute path to the project's source root.
+ * @returns A unique set of absolute paths to all test files.
+ */
+export declare function findTests(include: string[], exclude: string[], workspaceRoot: string, projectSourceRoot: string): Promise<string[]>;
+interface TestEntrypointsOptions {
+    projectSourceRoot: string;
+    workspaceRoot: string;
+    removeTestExtension?: boolean;
+    prefix?: string;
+}
+/**
+ * Generates unique, dash-delimited bundle names for a set of test files.
+ * This is used to create distinct output files for each test.
+ *
+ * @param testFiles An array of absolute paths to test files.
+ * @param options Configuration options for generating entry points.
+ * @returns A map where keys are the generated unique bundle names and values are the original file paths.
+ */
+export declare function getTestEntrypoints(testFiles: string[], { projectSourceRoot, workspaceRoot, removeTestExtension, prefix, }: TestEntrypointsOptions): Map<string, string>;
+/**
+ * Generates a unique, dash-delimited name from a file path. This is used to
+ * create a consistent and readable bundle name for a given test file.
+ *
+ * @param testFile The absolute path to the test file.
+ * @param roots An array of root paths to remove from the beginning of the test file path.
+ * @param removeTestExtension Whether to remove the test file infix and extension from the result.
+ * @returns A dash-cased name derived from the relative path of the test file.
+ */
+export declare function generateNameFromPath(testFile: string, roots: string[], removeTestExtension: boolean): string;
+export {};