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,34 @@
  * 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 { randomUUID } from 'crypto';
+import * as fs from 'fs/promises';
 import type { Config, ConfigOptions } 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';
 
 export type KarmaConfigOptions = ConfigOptions & {
   buildWebpack?: unknown;
@@ -30,10 +44,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
@@ -92,9 +113,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 +145,116 @@ export function execute(
         }
       }
 
+      if (useEsbuild) {
+        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
+        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(
+          [`**/*.js`].map((pattern) => ({ pattern, type: 'module' })),
+        );
+        karmaOptions.exclude = (karmaOptions.exclude ?? []).concat([
+          `polyfills.js`,
+          `chunk-*.js`,
+          // `!jasmine.js`,
+          // `!jasmine_runner.js`,
+          `testing.js`, // `zone.js/testing`
+          '*.js',
+        ]);
+
+        const parsedKarmaConfig = 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 as any).plugins = (parsedKarmaConfig as any).plugins.filter(
+          (plugin: { [key: string]: unknown }) => {
+            // Remove the webpack Karma plugin.
+            return !plugin['framework:@angular-devkit/build-angular'];
+          },
+        );
+        (parsedKarmaConfig as any).frameworks = (parsedKarmaConfig as any).frameworks.filter(
+          (framework: string) => {
+            // Remove the webpack "framework".
+            return framework !== '@angular-devkit/build-angular';
+          },
+        );
+
+        // Add the plugin/framework for the application builder:
+        // The options here are, to a certain extend:
+        // - Run the dev server as a Karma plugin.
+        // - Run the build separately and let Karma serve the files.
+
+        return [karma, parsedKarmaConfig] as [typeof karma, KarmaConfigOptions];
+      }
+
       if (!options.main) {
         webpackConfig.entry ??= {};
         if (typeof webpackConfig.entry === 'object' && !Array.isArray(webpackConfig.entry)) {
@@ -195,6 +328,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 +340,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 +396,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.');
+}

packages/angular_devkit/build_angular/src/builders/karma/init_test_bed.js

@@ -0,0 +1,19 @@
+/**
+ * @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
+ */
+
+import { getTestBed } from '@angular/core/testing';
+import {
+  BrowserDynamicTestingModule,
+  platformBrowserDynamicTesting,
+} from '@angular/platform-browser-dynamic/testing';
+
+// Initialize the Angular testing environment.
+getTestBed().initTestEnvironment(BrowserDynamicTestingModule, platformBrowserDynamicTesting(), {
+  errorOnUnknownElements: true,
+  errorOnUnknownProperties: true,
+});

packages/angular_devkit/build_angular/src/builders/karma/schema.json

@@ -267,6 +267,12 @@
         "type": "string"
       }
     },
+    "builderMode": {
+      "type": "string",
+      "description": "Determines how to build the code under test. If set to 'detect', attempts to follow the development builder.",
+      "enum": ["detect", "browser", "application"],
+      "default": "browser"
+    },
     "webWorkerTsConfig": {
       "type": "string",
       "description": "TypeScript configuration for Web Worker modules."