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

This ensures a cleaner and easier to follow code and also avoid having the fix bugs in multiple places.

Author: alan-agius4

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>;

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,
+ };
+}

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 };

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,
  };
 }

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';