refactor(@angular/build): default tsConfig option in unit-test builder

The unit-test builder is updated to streamline the initial configuration by intelligently defaulting the `tsConfig` option.

If the `tsConfig` option is not provided in the project's configuration, the builder now checks for the existence of a `tsconfig.spec.json` file in the project's root. If found, it is used automatically. This removes the need for boilerplate `tsConfig` configuration in `angular.json` for the majority of projects.

Additionally, a validation check has been added to ensure that if a `tsConfig` path is specified, the file must exist. An actionable error is thrown if it is not found, preventing downstream build failures.

The builder's schema has been updated to reflect these changes, making the `tsConfig` option optional and documenting the new behavior.

Author: clydin

goldens/public-api/angular/build/index.api.md

@@ -232,7 +232,7 @@ export type UnitTestBuilderOptions = {
     reporters?: SchemaReporter[];
     runner: Runner;
     setupFiles?: string[];
-    tsConfig: string;
+    tsConfig?: string;
     watch?: boolean;
 };
 

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

@@ -296,10 +296,13 @@ export async function* execute(
       ...buildTargetOptions,
       ...runnerBuildOptions,
       watch: normalizedOptions.watch,
-      tsConfig: normalizedOptions.tsConfig,
       progress: normalizedOptions.buildProgress ?? buildTargetOptions.progress,
     } satisfies ApplicationBuilderInternalOptions;
 
+    if (normalizedOptions.tsConfig) {
+      applicationBuildOptions.tsConfig = normalizedOptions.tsConfig;
+    }
+
     const dumpDirectory = normalizedOptions.dumpVirtualFiles
       ? path.join(normalizedOptions.cacheOptions.path, 'unit-test', 'output-files')
       : undefined;

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

@@ -7,6 +7,7 @@
  */
 
 import { type BuilderContext, targetFromTargetString } from '@angular-devkit/architect';
+import { constants, promises as fs } from 'node:fs';
 import path from 'node:path';
 import { normalizeCacheOptions } from '../../utils/normalize-cache';
 import { getProjectRootPaths } from '../../utils/project-metadata';
@@ -15,6 +16,16 @@ import type { Schema as UnitTestBuilderOptions } from './schema';
 
 export type NormalizedUnitTestBuilderOptions = Awaited<ReturnType<typeof normalizeOptions>>;
 
+async function exists(path: string): Promise<boolean> {
+  try {
+    await fs.access(path, constants.F_OK);
+
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 function normalizeReporterOption(
   reporters: unknown[] | undefined,
 ): [string, Record<string, unknown>][] | undefined {
@@ -43,7 +54,21 @@ export async function normalizeOptions(
   const buildTargetSpecifier = options.buildTarget ?? `::development`;
   const buildTarget = targetFromTargetString(buildTargetSpecifier, projectName, 'build');
 
-  const { tsConfig, runner, browsers, progress, filter } = options;
+  const { runner, browsers, progress, filter } = options;
+
+  let tsConfig = options.tsConfig;
+  if (tsConfig) {
+    const fullTsConfigPath = path.join(workspaceRoot, tsConfig);
+    if (!(await exists(fullTsConfigPath))) {
+      throw new Error(`The specified tsConfig file '${tsConfig}' does not exist.`);
+    }
+  } else {
+    const tsconfigSpecPath = path.join(projectRoot, 'tsconfig.spec.json');
+    if (await exists(tsconfigSpecPath)) {
+      // The application builder expects a path relative to the workspace root.
+      tsConfig = path.relative(workspaceRoot, tsconfigSpecPath);
+    }
+  }
 
   return {
     // Project/workspace information

packages/angular/build/src/builders/unit-test/runners/karma/executor.ts

@@ -39,7 +39,7 @@ export class KarmaExecutor implements TestExecutor {
     )) as unknown as ApplicationBuilderInternalOptions;
 
     const karmaOptions: KarmaBuilderOptions = {
-      tsConfig: unitTestOptions.tsConfig,
+      tsConfig: unitTestOptions.tsConfig ?? buildTargetOptions.tsConfig,
       polyfills: buildTargetOptions.polyfills,
       assets: buildTargetOptions.assets,
       scripts: buildTargetOptions.scripts,

packages/angular/build/src/builders/unit-test/runners/vitest/build-options.ts

@@ -63,15 +63,7 @@ export async function getVitestBuildOptions(
   options: NormalizedUnitTestBuilderOptions,
   baseBuildOptions: Partial<ApplicationBuilderInternalOptions>,
 ): Promise<RunnerOptions> {
-  const {
-    workspaceRoot,
-    projectSourceRoot,
-    include,
-    exclude = [],
-    watch,
-    tsConfig,
-    providersFile,
-  } = options;
+  const { workspaceRoot, projectSourceRoot, include, exclude = [], watch, providersFile } = options;
 
   // Find test files
   const testFiles = await findTests(include, exclude, workspaceRoot, projectSourceRoot);
@@ -108,7 +100,6 @@ export async function getVitestBuildOptions(
     sourceMap: { scripts: true, vendor: false, styles: false },
     outputHashing: adjustOutputHashing(baseBuildOptions.outputHashing),
     optimization: false,
-    tsConfig,
     entryPoints,
     externalDependencies: ['vitest', '@vitest/browser/context'],
   };

packages/angular/build/src/builders/unit-test/schema.json

@@ -11,7 +11,7 @@
     },
     "tsConfig": {
       "type": "string",
-      "description": "The path to the TypeScript configuration file, relative to the workspace root."
+      "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",
@@ -188,5 +188,5 @@
     }
   },
   "additionalProperties": false,
-  "required": ["buildTarget", "tsConfig", "runner"]
+  "required": ["buildTarget", "runner"]
 }

packages/angular/build/src/builders/unit-test/tests/options/tsconfig_spec.ts

@@ -12,43 +12,48 @@ import {
   describeBuilder,
   UNIT_TEST_BUILDER_INFO,
   setupApplicationTarget,
+  expectLog,
 } from '../setup';
 
 describeBuilder(execute, UNIT_TEST_BUILDER_INFO, (harness) => {
-  xdescribe('Option: "tsConfig"', () => {
+  describe('Option: "tsConfig"', () => {
     beforeEach(async () => {
       setupApplicationTarget(harness);
     });
 
-    it('should fail when tsConfig is not provided', async () => {
+    it('should use "tsconfig.spec.json" by default when it exists', async () => {
       const { tsConfig, ...rest } = BASE_OPTIONS;
-      harness.useTarget('test', rest as any);
+      harness.useTarget('test', rest);
 
-      await expectAsync(harness.executeOnce()).toBeRejectedWithError(/"tsConfig" is required/);
+      // Create tsconfig.spec.json
+      await harness.writeFile(
+        'tsconfig.spec.json',
+        `{ "extends": "./tsconfig.json", "compilerOptions": { "types": ["jasmine"] }, "include": ["src/**/*.ts"] }`,
+      );
+
+      const { result } = await harness.executeOnce();
+      expect(result?.success).toBeTrue();
+      // TODO: Add expectation that the file was used.
     });
 
-    it('should fail when tsConfig is empty', async () => {
-      harness.useTarget('test', {
-        ...BASE_OPTIONS,
-        tsConfig: '',
-      });
+    it('should use build target tsConfig when "tsconfig.spec.json" does not exist', async () => {
+      const { tsConfig, ...rest } = BASE_OPTIONS;
+      harness.useTarget('test', rest);
 
-      await expectAsync(harness.executeOnce()).toBeRejectedWithError(
-        /must NOT have fewer than 1 characters/,
-      );
+      // The build target tsconfig is not setup to build the tests and should fail
+      const { result } = await harness.executeOnce();
+      expect(result?.success).toBeFalse();
     });
 
-    it('should fail when tsConfig does not exist', async () => {
+    it('should fail when user specified tsConfig does not exist', async () => {
       harness.useTarget('test', {
         ...BASE_OPTIONS,
-        tsConfig: 'src/tsconfig.spec.json',
+        tsConfig: 'random/tsconfig.spec.json',
       });
 
-      const { result, error } = await harness.executeOnce({ outputLogsOnFailure: false });
-      expect(result).toBeUndefined();
-      expect(error?.message).toMatch(
-        `The specified tsConfig file "src/tsconfig.spec.json" does not exist.`,
-      );
+      const { result, logs } = await harness.executeOnce({ outputLogsOnFailure: false });
+      expect(result?.success).toBeFalse();
+      expectLog(logs, `The specified tsConfig file 'random/tsconfig.spec.json' does not exist.`);
     });
   });
 });