feat(@angular-devkit/build-angular): support karma with application builder

Author: jkrems

packages/angular_devkit/build_angular/src/builders/karma/index.ts

@@ -6,20 +6,35 @@
  * found in the LICENSE file at https://angular.dev/license
  */
 
-import { assertCompatibleAngularVersion, purgeStaleBuildCache } from '@angular/build/private';
-import { BuilderContext, BuilderOutput, createBuilder } from '@angular-devkit/architect';
+import {
+  ResultKind,
+  assertCompatibleAngularVersion,
+  buildApplicationInternal,
+  purgeStaleBuildCache,
+} from '@angular/build/private';
+import {
+  BuilderContext,
+  BuilderOutput,
+  createBuilder,
+  targetFromTargetString,
+} from '@angular-devkit/architect';
 import { strings } from '@angular-devkit/core';
-import type { Config, ConfigOptions } from 'karma';
+import { randomUUID } from 'crypto';
+import * as fs from 'fs/promises';
+import type { Config, ConfigOptions, InlinePluginDef } from 'karma';
 import { createRequire } from 'module';
 import * as path from 'path';
 import { Observable, defaultIfEmpty, from, switchMap } from 'rxjs';
 import { Configuration } from 'webpack';
 import { getCommonConfig, getStylesConfig } from '../../tools/webpack/configs';
 import { ExecutionTransformer } from '../../transforms';
+import { findTestFiles } from '../../utils/test-files';
 import { generateBrowserWebpackConfigFromContext } from '../../utils/webpack-browser-config';
 import { Schema as BrowserBuilderOptions, OutputHashing } from '../browser/schema';
+import { writeTestFiles } from '../web-test-runner/write-test-files';
 import { FindTestsPlugin } from './find-tests-plugin';
-import { Schema as KarmaBuilderOptions } from './schema';
+import { BuilderMode, Schema as KarmaBuilderOptions } from './schema';
+import { readFileSync } from 'fs';
 
 export type KarmaConfigOptions = ConfigOptions & {
   buildWebpack?: unknown;
@@ -30,10 +45,17 @@ async function initialize(
   options: KarmaBuilderOptions,
   context: BuilderContext,
   webpackConfigurationTransformer?: ExecutionTransformer<Configuration>,
-): Promise<[typeof import('karma'), Configuration]> {
+): Promise<[typeof import('karma'), Configuration | null]> {
   // Purge old build disk cache.
   await purgeStaleBuildCache(context);
 
+  const useEsbuild = await checkForEsbuild(options, context);
+  if (useEsbuild) {
+    const karma = await import('karma');
+
+    return [karma, null];
+  }
+
   const { config } = await generateBrowserWebpackConfigFromContext(
     // only two properties are missing:
     // * `outputPath` which is fixed for tests
@@ -64,6 +86,199 @@ async function initialize(
   return [karma, (await webpackConfigurationTransformer?.(config)) ?? config];
 }
 
+async function createEsbuildConfig(
+  options: KarmaBuilderOptions,
+  context: BuilderContext,
+  karma: typeof import('karma'),
+  karmaOptions: KarmaConfigOptions,
+  transforms: {
+    karmaOptions?: (options: KarmaConfigOptions) => KarmaConfigOptions;
+  } = {},
+) {
+  const testDir = path.join(context.workspaceRoot, 'dist/test-out', randomUUID());
+
+  // Parallelize startup work.
+  const [testFiles] = await Promise.all([
+    // Glob for files to test.
+    findTestFiles(options.include ?? [], options.exclude ?? [], context.workspaceRoot),
+    // Clean build output path.
+    fs.rm(testDir, { recursive: true, force: true }),
+  ]);
+
+  const entryPoints = new Set([
+    ...testFiles,
+    // 'jasmine-core/lib/jasmine-core/jasmine.js',
+    '@angular-devkit/build-angular/src/builders/karma/init_test_bed.js',
+  ]);
+  const outputPath = testDir;
+  // Extract `zone.js/testing` to a separate entry point because it needs to be loaded after Jasmine.
+  const [polyfills, hasZoneTesting] = extractZoneTesting(options.polyfills);
+  if (hasZoneTesting) {
+    entryPoints.add('zone.js/testing');
+  }
+  // see: packages/angular_devkit/build_angular/src/tools/webpack/configs/common.ts
+  // TODO: Make this relative to tsConfig.
+  // const localizePackageInitEntryPoint = '@angular/localize/init';
+  // const hasLocalizeType = tsConfig.options.types?.some(
+  //   (t) => t === '@angular/localize' || t === localizePackageInitEntryPoint,
+  // );
+
+  // if (hasLocalizeType) {
+  //   entryPoints['main'] = [localizePackageInitEntryPoint];
+  // }
+  polyfills.push('@angular/localize/init');
+
+  // Build tests with `application` builder, using test files as entry points.
+  // Also bundle in Jasmine and the Jasmine runner script, which need to share chunked dependencies.
+  const buildOutput = await first(
+    buildApplicationInternal(
+      {
+        entryPoints,
+        tsConfig: options.tsConfig,
+        outputPath,
+        aot: false,
+        index: false,
+        outputHashing: OutputHashing.None,
+        optimization: false,
+        externalDependencies: [
+          // Resolved by `@web/test-runner` at runtime with dynamically generated code.
+          // '@web/test-runner-core',
+        ],
+        sourceMap: {
+          scripts: true,
+          styles: true,
+          vendor: true,
+        },
+        polyfills,
+      },
+      context,
+    ),
+  );
+  if (buildOutput.kind === ResultKind.Failure) {
+    // TODO: Forward {success: false}
+    throw new Error('Build failed');
+  } else if (buildOutput.kind !== ResultKind.Full) {
+    // TODO: Forward {success: false}
+    // return {
+    //   success: false,
+    //   error: 'A full build result is required from the application builder.',
+    // };
+    throw new Error('A full build result is required from the application builder.');
+  }
+
+  // Write test files
+  await writeTestFiles(buildOutput.files, testDir);
+
+  // TODO: Base this on the buildOutput.files to make it less fragile to exclude patterns?
+  karmaOptions.files ??= [];
+  karmaOptions.files = karmaOptions.files.concat(
+    [`${testDir}/polyfills.js`].map((pattern) => ({ pattern, type: 'module' })),
+  );
+  karmaOptions.files = karmaOptions.files.concat(
+    [
+      `${testDir}/chunk-*.js`,
+      `${testDir}/testing.js`, // `zone.js/testing`
+    ].map((pattern) => ({ pattern, type: 'module', included: false })),
+  );
+  karmaOptions.files = karmaOptions.files.concat(
+    [`${testDir}/*.js`].map((pattern) => ({ pattern, type: 'module' })),
+  );
+
+  const parsedKarmaConfig: Config & KarmaConfigOptions = await karma.config.parseConfig(
+    options.karmaConfig && path.resolve(context.workspaceRoot, options.karmaConfig),
+    transforms.karmaOptions ? transforms.karmaOptions(karmaOptions) : karmaOptions,
+    { promiseConfig: true, throwErrors: true },
+  );
+
+  // Remove the webpack plugin/framework:
+  // Alternative would be to make the Karma plugin "smart" but that's a tall order
+  // with managing unneeded imports etc..
+  parsedKarmaConfig.plugins = (parsedKarmaConfig.plugins ?? [])
+    .filter((plugin: string | InlinePluginDef) => {
+      if (typeof plugin === 'string') {
+        return plugin !== 'framework:@angular-devkit/build-angular';
+      }
+
+      return !plugin['framework:@angular-devkit/build-angular'];
+    })
+    .concat([
+      {
+        ['preprocessor:attach-source-maps']: [
+          'factory',
+          Object.assign(
+            () => {
+              interface BasicSourceMap {
+                file?: string;
+                sourcesContent?: unknown;
+              }
+              interface KarmaFile {
+                path: string;
+                readonly originalPath: string;
+                encodings: { [key: string]: Buffer };
+                type: unknown;
+                sourceMap?: BasicSourceMap;
+              }
+
+              return (
+                content: Buffer,
+                file: KarmaFile,
+                done: (err: Error | null, content: Buffer) => void,
+              ) => {
+                if (file.path.startsWith(`${testDir}/`) && file.path.endsWith('.js')) {
+                  // Attempt to load source map.
+                  const sourceMapPath = `${file.path}.map`;
+                  const mapBytes = readFileSync(sourceMapPath, 'utf8');
+                  file.sourceMap = JSON.parse(mapBytes) as BasicSourceMap;
+                  delete file.sourceMap.sourcesContent;
+                  file.sourceMap.file = file.path; // basename?
+                }
+
+                done(null, content);
+              };
+            },
+            { '$inject': [] },
+          ),
+        ],
+      },
+    ]);
+  parsedKarmaConfig.frameworks = parsedKarmaConfig.frameworks?.filter(
+    (framework: string) => framework !== '@angular-devkit/build-angular',
+  );
+
+  // When using code-coverage, auto-add karma-coverage.
+  // This was done as part of the karma plugin for webpack.
+  if (
+    options.codeCoverage &&
+    !parsedKarmaConfig.reporters?.some((r: string) => r === 'coverage' || r === 'coverage-istanbul')
+  ) {
+    parsedKarmaConfig.reporters = (parsedKarmaConfig.reporters ?? []).concat(['coverage']);
+  }
+
+  /*
+  const projectRoot = path.join(workspaceRoot, (projectMetadata.root as string | undefined) ?? '');
+  const sourceRoot = projectMetadata.sourceRoot as string | undefined;
+  const projectSourceRoot = sourceRoot ? path.join(workspaceRoot, sourceRoot) : undefined;
+  */
+
+  // Add preprocessor to instrument code for coverage gathering.
+  if (options.codeCoverage) {
+    parsedKarmaConfig.preprocessors ??= {};
+    // sourceRoot ?? projectRoot
+    /*
+    {
+      includedBasePath: sourceRoot ?? projectRoot,
+      excludedPaths: getInstrumentationExcludedPaths(root, codeCoverageExclude),
+    }
+    */
+    parsedKarmaConfig.preprocessors[`${testDir}/!(polyfills|testing).js`] = [
+      'attach-source-maps',
+      'coverage',
+    ];
+  }
+
+  return [karma, parsedKarmaConfig] as [typeof karma, KarmaConfigOptions];
+}
+
 /**
  * @experimental Direct usage of this function is considered experimental.
  */
@@ -92,9 +307,11 @@ export function execute(
         throw new Error(`The 'karma' builder requires a target to be specified.`);
       }
 
+      const useEsbuild = !webpackConfig;
+
       const karmaOptions: KarmaConfigOptions = options.karmaConfig
         ? {}
-        : getBuiltInKarmaConfig(context.workspaceRoot, projectName);
+        : getBuiltInKarmaConfig(context.workspaceRoot, projectName, useEsbuild);
 
       karmaOptions.singleRun = singleRun;
 
@@ -122,6 +339,10 @@ export function execute(
         }
       }
 
+      if (useEsbuild) {
+        return createEsbuildConfig(options, context, karma, karmaOptions, transforms);
+      }
+
       if (!options.main) {
         webpackConfig.entry ??= {};
         if (typeof webpackConfig.entry === 'object' && !Array.isArray(webpackConfig.entry)) {
@@ -195,6 +416,7 @@ export function execute(
 function getBuiltInKarmaConfig(
   workspaceRoot: string,
   projectName: string,
+  useEsbuild: boolean,
 ): ConfigOptions & Record<string, unknown> {
   let coverageFolderName = projectName.charAt(0) === '@' ? projectName.slice(1) : projectName;
   if (/[A-Z]/.test(coverageFolderName)) {
@@ -206,13 +428,13 @@ function getBuiltInKarmaConfig(
   // Any changes to the config here need to be synced to: packages/schematics/angular/config/files/karma.conf.js.template
   return {
     basePath: '',
-    frameworks: ['jasmine', '@angular-devkit/build-angular'],
+    frameworks: ['jasmine', ...(useEsbuild ? [] : ['@angular-devkit/build-angular'])],
     plugins: [
       'karma-jasmine',
       'karma-chrome-launcher',
       'karma-jasmine-html-reporter',
       'karma-coverage',
-      '@angular-devkit/build-angular/plugins/karma',
+      ...(useEsbuild ? [] : ['@angular-devkit/build-angular/plugins/karma']),
     ].map((p) => workspaceRootRequire(p)),
     jasmineHtmlReporter: {
       suppressAll: true, // removes the duplicated traces
@@ -262,3 +484,76 @@ function getBuiltInMainFile(): string {
 
   return `ng-virtual-main.js!=!data:text/javascript;base64,${content}`;
 }
+
+async function checkForEsbuild(
+  options: KarmaBuilderOptions,
+  context: BuilderContext,
+): Promise<boolean> {
+  if (options.builderMode !== BuilderMode.Detect) {
+    return options.builderMode === BuilderMode.Application;
+  }
+
+  // Look up the current project's build target using a development configuration.
+  const buildTargetSpecifier = `::development`;
+  const buildTarget = targetFromTargetString(
+    buildTargetSpecifier,
+    context.target?.project,
+    'build',
+  );
+
+  try {
+    const developmentBuilderName = await context.getBuilderNameForTarget(buildTarget);
+
+    return isEsbuildBased(developmentBuilderName);
+  } catch (e) {
+    if (!(e instanceof Error) || e.message !== 'Project target does not exist.') {
+      throw e;
+    }
+    // If we can't find a development builder, we can't use 'detect'.
+    throw new Error(
+      'Failed to detect the detect the builder used by the application. Please set builderMode explicitly.',
+    );
+  }
+}
+
+function isEsbuildBased(
+  builderName: string,
+): builderName is
+  | '@angular/build:application'
+  | '@angular-devkit/build-angular:application'
+  | '@angular-devkit/build-angular:browser-esbuild' {
+  if (
+    builderName === '@angular/build:application' ||
+    builderName === '@angular-devkit/build-angular:application' ||
+    builderName === '@angular-devkit/build-angular:browser-esbuild'
+  ) {
+    return true;
+  }
+
+  return false;
+}
+
+function extractZoneTesting(
+  polyfills: readonly string[] | string | undefined,
+): [polyfills: string[], hasZoneTesting: boolean] {
+  if (typeof polyfills === 'string') {
+    polyfills = [polyfills];
+  }
+  polyfills ??= [];
+
+  const polyfillsWithoutZoneTesting = polyfills.filter(
+    (polyfill) => polyfill !== 'zone.js/testing',
+  );
+  const hasZoneTesting = polyfills.length !== polyfillsWithoutZoneTesting.length;
+
+  return [polyfillsWithoutZoneTesting, hasZoneTesting];
+}
+
+/** Returns the first item yielded by the given generator and cancels the execution. */
+async function first<T>(generator: AsyncIterable<T>): Promise<T> {
+  for await (const value of generator) {
+    return value;
+  }
+
+  throw new Error('Expected generator to emit at least once.');
+}