refactor(@angular/build): clean up duplicate of code in the karma builders

alan-agius4 · alan-agius4 · commit 462bb3e70f15 · 2025-07-08T06:44:17.000Z
This ensures a cleaner and easier to follow code and also avoid having the fix bugs in multiple places. (cherry picked from commit b160819)
diff --git a/goldens/public-api/angular/build/index.api.md b/goldens/public-api/angular/build/index.api.md
@@ -153,9 +153,7 @@ export function executeDevServerBuilder(options: DevServerBuilderOptions, contex
 export function executeExtractI18nBuilder(options: ExtractI18nBuilderOptions, context: BuilderContext, extensions?: ApplicationBuilderExtensions): Promise<BuilderOutput>;
 
 // @public
-export function executeKarmaBuilder(options: KarmaBuilderOptions, context: BuilderContext, transforms?: {
-    karmaOptions?: (options: KarmaConfigOptions) => KarmaConfigOptions;
-}): AsyncIterable<BuilderOutput>;
+export function executeKarmaBuilder(options: KarmaBuilderOptions, context: BuilderContext, transforms?: KarmaBuilderTransformsOptions): AsyncIterable<BuilderOutput>;
 
 // @public
 export function executeNgPackagrBuilder(options: NgPackagrBuilderOptions, context: BuilderContext): AsyncIterableIterator<BuilderOutput>;
diff --git a/packages/angular/build/src/builders/karma/application_builder.ts b/packages/angular/build/src/builders/karma/application_builder.ts
@@ -12,7 +12,7 @@ import { randomUUID } from 'node:crypto';
 import * as fs from 'node:fs/promises';
 import type { IncomingMessage, ServerResponse } from 'node:http';
 import { createRequire } from 'node:module';
-import * as path from 'node:path';
+import path from 'node:path';
 import { ReadableStreamController } from 'node:stream/web';
 import { globSync } from 'tinyglobby';
 import { BuildOutputFileType } from '../../tools/esbuild/bundler-context';
@@ -24,7 +24,9 @@ import { ApplicationBuilderInternalOptions } from '../application/options';
 import { Result, ResultFile, ResultKind } from '../application/results';
 import { OutputHashing } from '../application/schema';
 import { findTests, getTestEntrypoints } from './find-tests';
-import { NormalizedKarmaBuilderOptions } from './options';
+import { NormalizedKarmaBuilderOptions, normalizeOptions } from './options';
+import { Schema as KarmaBuilderOptions } from './schema';
+import type { KarmaBuilderTransformsOptions } from './index';
 
 const localResolve = createRequire(__filename).resolve;
 const isWindows = process.platform === 'win32';
@@ -275,21 +277,20 @@ function injectKarmaReporter(
 }
 
 export function execute(
-  options: NormalizedKarmaBuilderOptions,
+  options: KarmaBuilderOptions,
   context: BuilderContext,
-  karmaOptions: ConfigOptions,
-  transforms: {
-    // The karma options transform cannot be async without a refactor of the builder implementation
-    karmaOptions?: (options: ConfigOptions) => ConfigOptions;
-  } = {},
+  transforms?: KarmaBuilderTransformsOptions,
 ): AsyncIterable<BuilderOutput> {
+  const normalizedOptions = normalizeOptions(context, options);
+  const karmaOptions = getBaseKarmaOptions(normalizedOptions, context);
+
   let karmaServer: Server;
 
   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) {
           controller.enqueue({ success: false, message: err.message });
@@ -336,13 +337,9 @@ async function getProjectSourceRoot(context: BuilderContext): Promise<string> {
   return projectSourceRoot;
 }
 
-function normalizePolyfills(polyfills: string | string[] | undefined): [string[], string[]] {
-  if (typeof polyfills === 'string') {
-    polyfills = [polyfills];
-  } else if (!polyfills) {
-    polyfills = [];
-  }
-
+function normalizePolyfills(
+  polyfills: string[] = [],
+): [polyfills: string[], jasmineCleanup: string[]] {
   const jasmineGlobalEntryPoint = localResolve('./polyfills/jasmine_global.js');
   const jasmineGlobalCleanupEntrypoint = localResolve('./polyfills/jasmine_global_cleanup.js');
   const sourcemapEntrypoint = localResolve('./polyfills/init_sourcemaps.js');
@@ -379,9 +376,7 @@ async function initializeApplication(
   options: NormalizedKarmaBuilderOptions,
   context: BuilderContext,
   karmaOptions: ConfigOptions,
-  transforms: {
-    karmaOptions?: (options: ConfigOptions) => ConfigOptions;
-  } = {},
+  transforms?: KarmaBuilderTransformsOptions,
 ): Promise<
   [typeof import('karma'), Config & ConfigOptions, BuildOptions, AsyncIterator<Result> | null]
 > {
@@ -423,13 +418,7 @@ async function initializeApplication(
     index: false,
     outputHashing: 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,
@@ -551,8 +540,8 @@ async function initializeApplication(
   }
 
   const parsedKarmaConfig: Config & ConfigOptions = await karma.config.parseConfig(
-    options.karmaConfig && path.resolve(context.workspaceRoot, options.karmaConfig),
-    transforms.karmaOptions ? transforms.karmaOptions(karmaOptions) : karmaOptions,
+    options.karmaConfig,
+    transforms?.karmaOptions ? await transforms.karmaOptions(karmaOptions) : karmaOptions,
     { promiseConfig: true, throwErrors: true },
   );
 
@@ -718,3 +707,82 @@ function getInstrumentationExcludedPaths(root: string, excludedPaths: string[]):
 
   return excluded;
 }
+function getBaseKarmaOptions(
+  options: NormalizedKarmaBuilderOptions,
+  context: BuilderContext,
+): ConfigOptions {
+  // 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: ConfigOptions = 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: string,
+  projectName: string,
+): ConfigOptions & Record<string, unknown> {
+  let coverageFolderName = projectName.charAt(0) === '@' ? projectName.slice(1) : projectName;
+  coverageFolderName = coverageFolderName.toLowerCase();
+
+  const workspaceRootRequire = 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: path.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,
+  };
+}
diff --git a/packages/angular/build/src/builders/karma/index.ts b/packages/angular/build/src/builders/karma/index.ts
@@ -13,114 +13,24 @@ import {
   createBuilder,
 } from '@angular-devkit/architect';
 import type { ConfigOptions } from 'karma';
-import { createRequire } from 'node:module';
-import path from 'node:path';
-import { NormalizedKarmaBuilderOptions, normalizeOptions } from './options';
+
 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 async function* execute(
   options: KarmaBuilderOptions,
   context: BuilderContext,
-  transforms: {
-    // The karma options transform cannot be async without a refactor of the builder implementation
-    karmaOptions?: (options: KarmaConfigOptions) => KarmaConfigOptions;
-  } = {},
+  transforms?: KarmaBuilderTransformsOptions,
 ): AsyncIterable<BuilderOutput> {
   const { execute } = await import('./application_builder');
-  const normalizedOptions = normalizeOptions(options);
-  const karmaOptions = getBaseKarmaOptions(normalizedOptions, context);
-
-  yield* execute(normalizedOptions, context, karmaOptions, transforms);
-}
-
-function getBaseKarmaOptions(
-  options: NormalizedKarmaBuilderOptions,
-  context: BuilderContext,
-): KarmaConfigOptions {
-  const 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: KarmaConfigOptions = 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 (options.browsers) {
-    karmaOptions.browsers = options.browsers;
-  }
-
-  if (options.reporters) {
-    karmaOptions.reporters = options.reporters;
-  }
-
-  return karmaOptions;
-}
-
-function getBuiltInKarmaConfig(
-  workspaceRoot: string,
-  projectName: string,
-): ConfigOptions & Record<string, unknown> {
-  let coverageFolderName = projectName.charAt(0) === '@' ? projectName.slice(1) : projectName;
-  coverageFolderName = coverageFolderName.toLowerCase();
-
-  const workspaceRootRequire = 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)),
-    jasmineHtmlReporter: {
-      suppressAll: true, // removes the duplicated traces
-    },
-    coverageReporter: {
-      dir: path.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);
 }
 
 export type { KarmaBuilderOptions };
diff --git a/packages/angular/build/src/builders/karma/options.ts b/packages/angular/build/src/builders/karma/options.ts
@@ -6,12 +6,23 @@
  * found in the LICENSE file at https://angular.dev/license
  */
 
+import type { BuilderContext } from '@angular-devkit/architect';
+import { resolve } from 'node:path';
 import { Schema as KarmaBuilderOptions } from './schema';
 
-export type NormalizedKarmaBuilderOptions = Awaited<ReturnType<typeof normalizeOptions>>;
+export type NormalizedKarmaBuilderOptions = ReturnType<typeof normalizeOptions>;
 
-export function normalizeOptions(options: KarmaBuilderOptions) {
-  const { watch = true, include = [], exclude = [], reporters = [], browsers, ...rest } = options;
+export function normalizeOptions(context: BuilderContext, options: KarmaBuilderOptions) {
+  const {
+    sourceMap,
+    karmaConfig,
+    browsers,
+    watch = true,
+    include = [],
+    exclude = [],
+    reporters = [],
+    ...rest
+  } = options;
 
   let normalizedBrowsers: string[] | undefined;
   if (typeof options.browsers === 'string' && options.browsers) {
@@ -25,12 +36,23 @@ export function normalizeOptions(options: KarmaBuilderOptions) {
     .reduce<string[]>((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 ? resolve(context.workspaceRoot, karmaConfig) : undefined,
     reporters: normalizedReporters.length ? normalizedReporters : undefined,
     browsers: normalizedBrowsers,
     watch,
     include,
     exclude,
-    ...rest,
   };
 }
diff --git a/packages/angular/build/src/private.ts b/packages/angular/build/src/private.ts
@@ -26,7 +26,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';
 
 // Tools
 export * from './tools/babel/plugins';
diff --git a/packages/angular_devkit/build_angular/src/builders/karma/index.ts b/packages/angular_devkit/build_angular/src/builders/karma/index.ts
