feat(@schematics/angular): add migrate-karma-to-vitest update migration

Migrate projects using the Karma unit-test builder to the new
@angular/build:unit-test builder with Vitest.

This migration automatically updates target builders, translates builder options
(such as coverage and browsers format), moves custom build options to dedicated
configurations to prevent loss of custom settings, cleans up default
configuration files, and installs required Vitest runner packages.

Author: clydin

packages/schematics/angular/migrations/migrate-karma-to-vitest/migration.ts

@@ -0,0 +1,388 @@
+/**
+ * @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 type { json } from '@angular-devkit/core';
+import { Rule, SchematicContext, Tree, chain } from '@angular-devkit/schematics';
+import { DependencyType, ExistingBehavior, addDependency } from '../../utility/dependency';
+import { latestVersions } from '../../utility/latest-versions';
+import { TargetDefinition, allTargetOptions, updateWorkspace } from '../../utility/workspace';
+import { Builders } from '../../utility/workspace-models';
+import { KarmaConfigAnalysis, analyzeKarmaConfig } from '../karma/karma-config-analyzer';
+import { compareKarmaConfigToDefault, hasDifferences } from '../karma/karma-config-comparer';
+
+const SUPPORTED_REPORTERS = new Set([
+  'default',
+  'verbose',
+  'dots',
+  'json',
+  'junit',
+  'tap',
+  'tap-flat',
+  'html',
+]);
+
+function extractReporters(
+  analysis: KarmaConfigAnalysis,
+  options: Record<string, json.JsonValue | undefined>,
+  projectName: string,
+  context: SchematicContext,
+): void {
+  const reporters = analysis.settings.get('reporters');
+  if (Array.isArray(reporters)) {
+    const mappedReporters: string[] = [];
+    for (const r of reporters) {
+      if (typeof r === 'string') {
+        if (r === 'progress') {
+          mappedReporters.push('default');
+        } else if (r === 'kjhtml') {
+          context.logger.warn(
+            `Project "${projectName}" uses the "kjhtml" reporter. ` +
+              `This has not been automatically mapped. ` +
+              `For an interactive test UI in Vitest, consider setting the "ui" option to true in your test target options ` +
+              `and installing "@vitest/ui".`,
+          );
+        } else if (SUPPORTED_REPORTERS.has(r)) {
+          mappedReporters.push(r);
+        } else {
+          context.logger.warn(
+            `Project "${projectName}" uses a custom Karma reporter "${r}". ` +
+              `This reporter cannot be automatically mapped to Vitest. ` +
+              `Please check the Vitest documentation for equivalent reporters.`,
+          );
+        }
+      } else {
+        context.logger.warn(
+          `Project "${projectName}" has a non-string reporter in Karma config. ` +
+            `This cannot be automatically mapped to Vitest.`,
+        );
+      }
+    }
+    if (mappedReporters.length > 0) {
+      options['reporters'] = [...new Set(mappedReporters)];
+    }
+  }
+}
+
+function extractCoverageSettings(
+  analysis: KarmaConfigAnalysis,
+  options: Record<string, json.JsonValue | undefined>,
+): void {
+  const coverageReporter = analysis.settings.get('coverageReporter');
+  if (typeof coverageReporter !== 'object' || coverageReporter === null) {
+    return;
+  }
+
+  // Extract coverage reporters
+  const covReporters = (coverageReporter as Record<string, unknown>)['reporters'];
+  if (Array.isArray(covReporters)) {
+    const mappedCovReporters: string[] = [];
+    for (const r of covReporters) {
+      if (typeof r === 'object' && r !== null && 'type' in r) {
+        const type = r['type'];
+        if (typeof type === 'string') {
+          mappedCovReporters.push(type);
+        }
+      } else if (typeof r === 'string') {
+        mappedCovReporters.push(r);
+      }
+    }
+    if (mappedCovReporters.length > 0) {
+      options['coverageReporters'] = mappedCovReporters;
+    }
+  }
+
+  // Extract coverage thresholds
+  const check = (coverageReporter as Record<string, unknown>)['check'];
+  if (typeof check === 'object' && check !== null) {
+    const global = (check as Record<string, unknown>)['global'];
+    if (typeof global === 'object' && global !== null) {
+      const thresholds: Record<string, number> = {};
+      const keys = ['statements', 'branches', 'functions', 'lines'];
+      for (const key of keys) {
+        const value = (global as Record<string, unknown>)[key];
+        if (typeof value === 'number') {
+          thresholds[key] = value;
+        }
+      }
+      if (Object.keys(thresholds).length > 0) {
+        options['coverageThresholds'] = {
+          ...thresholds,
+          perFile: false,
+        };
+      }
+    }
+  }
+}
+
+async function processKarmaConfig(
+  karmaConfig: string,
+  options: Record<string, json.JsonValue | undefined>,
+  projectName: string,
+  context: SchematicContext,
+  tree: Tree,
+  removableKarmaConfigs: Map<string, boolean>,
+  needDevkitPlugin: boolean,
+): Promise<void> {
+  if (tree.exists(karmaConfig)) {
+    const content = tree.readText(karmaConfig);
+    const analysis = analyzeKarmaConfig(content);
+
+    extractReporters(analysis, options, projectName, context);
+    extractCoverageSettings(analysis, options);
+
+    let isRemovable = removableKarmaConfigs.get(karmaConfig);
+    if (isRemovable === undefined) {
+      if (analysis.hasUnsupportedValues) {
+        isRemovable = false;
+      } else {
+        const diff = await compareKarmaConfigToDefault(
+          analysis,
+          projectName,
+          karmaConfig,
+          needDevkitPlugin,
+        );
+        isRemovable = !hasDifferences(diff) && diff.isReliable;
+      }
+      removableKarmaConfigs.set(karmaConfig, isRemovable);
+    }
+
+    if (isRemovable) {
+      tree.delete(karmaConfig);
+    } else {
+      context.logger.warn(
+        `Project "${projectName}" uses a custom Karma configuration file "${karmaConfig}". ` +
+          `Tests have been migrated to use Vitest, but you may need to manually migrate custom settings ` +
+          `from this Karma config to a Vitest config (e.g. vitest.config.ts).`,
+      );
+    }
+  }
+  delete options['karmaConfig'];
+}
+
+async function processTestTargetOptions(
+  testTarget: TargetDefinition,
+  projectName: string,
+  context: SchematicContext,
+  tree: Tree,
+  removableKarmaConfigs: Map<string, boolean>,
+  customBuildOptions: Record<string, json.JsonValue | undefined>,
+  needDevkitPlugin: boolean,
+): Promise<boolean> {
+  let needsCoverage = false;
+  const buildOptionsKeys = [
+    'assets',
+    'styles',
+    'scripts',
+    'polyfills',
+    'inlineStyleLanguage',
+    'stylePreprocessorOptions',
+    'externalDependencies',
+    'loader',
+    'define',
+    'fileReplacements',
+    'webWorkerTsConfig',
+    'aot',
+  ];
+
+  for (const [, options] of allTargetOptions(testTarget, false)) {
+    // Collect custom build options
+    for (const key of buildOptionsKeys) {
+      if (options[key] !== undefined) {
+        customBuildOptions[key] = options[key];
+        delete options[key];
+      }
+    }
+
+    // Map Karma options to Unit-Test options
+    if (options['codeCoverage'] !== undefined) {
+      options['coverage'] = options['codeCoverage'];
+      delete options['codeCoverage'];
+    }
+
+    if (options['codeCoverageExclude'] !== undefined) {
+      options['coverageExclude'] = options['codeCoverageExclude'];
+      delete options['codeCoverageExclude'];
+    }
+
+    if (options['coverage'] === true || options['coverageExclude'] !== undefined) {
+      needsCoverage = true;
+    }
+
+    if (options['sourceMap'] !== undefined) {
+      context.logger.info(
+        `Project "${projectName}" has "sourceMap" set for tests. ` +
+          `In unit-test builder with Vitest, source maps are always enabled. The option has been removed.`,
+      );
+      delete options['sourceMap'];
+    }
+
+    // Convert browser list to array format if it is a comma-separated string
+    const browsers = options['browsers'];
+    if (typeof browsers === 'string') {
+      options['browsers'] = browsers.split(',').map((b) => b.trim());
+    } else if (browsers === false) {
+      options['browsers'] = [];
+    }
+
+    // Check if the karma configuration file can be safely removed and extract settings
+    const karmaConfig = options['karmaConfig'];
+    if (typeof karmaConfig === 'string') {
+      await processKarmaConfig(
+        karmaConfig,
+        options,
+        projectName,
+        context,
+        tree,
+        removableKarmaConfigs,
+        needDevkitPlugin,
+      );
+    }
+
+    // Map the main entry file to the setupFiles of the unit-test builder
+    const mainFile = options['main'];
+    if (typeof mainFile === 'string') {
+      options['setupFiles'] = [...((options['setupFiles'] as string[]) || []), mainFile];
+
+      context.logger.info(
+        `Project "${projectName}" uses a "main" entry file for tests: "${mainFile}". ` +
+          `This has been mapped to the unit-test builder "setupFiles" array. ` +
+          `Please ensure you remove any TestBed.initTestEnvironment calls from this file ` +
+          `as the builder now handles test environment initialization automatically.`,
+      );
+    }
+    delete options['main'];
+  }
+
+  return needsCoverage;
+}
+
+function updateProjects(tree: Tree, context: SchematicContext): Rule {
+  return updateWorkspace(async (workspace) => {
+    let hasMigratedAny = false;
+    let needsCoverage = false;
+    const removableKarmaConfigs = new Map<string, boolean>();
+
+    for (const [projectName, project] of workspace.projects) {
+      // Restrict to application types for now
+      if (project.extensions.projectType !== 'application') {
+        continue;
+      }
+
+      // Find the test target to migrate
+      const testTarget = project.targets.get('test');
+      if (!testTarget) {
+        continue;
+      }
+
+      let isKarma = false;
+      let needDevkitPlugin = false;
+      // Check if target uses Karma builders
+      switch (testTarget.builder) {
+        case Builders.Karma:
+          isKarma = true;
+          needDevkitPlugin = true;
+          break;
+        case Builders.BuildKarma:
+          isKarma = true;
+          break;
+      }
+
+      if (!isKarma) {
+        continue;
+      }
+
+      // Store custom build options to move to a new build configuration if needed
+      // Match Karma behavior where AOT was disabled by default
+      const customBuildOptions: Record<string, json.JsonValue | undefined> = {
+        aot: false,
+        optimization: false,
+        extractLicenses: false,
+      };
+
+      const projectNeedsCoverage = await processTestTargetOptions(
+        testTarget,
+        projectName,
+        context,
+        tree,
+        removableKarmaConfigs,
+        customBuildOptions,
+        needDevkitPlugin,
+      );
+
+      if (projectNeedsCoverage) {
+        needsCoverage = true;
+      }
+
+      // If we have custom build options, create a testing configuration
+      if (Object.keys(customBuildOptions).length > 0) {
+        const buildTarget = project.targets.get('build');
+        if (buildTarget) {
+          const baseOptions = buildTarget.options || {};
+          const finalConfig: Record<string, json.JsonValue | undefined> = {};
+
+          // Omit options that already have the same value in the base build options.
+          // Using JSON.stringify for a basic deep comparison of arrays and objects.
+          for (const [key, value] of Object.entries(customBuildOptions)) {
+            if (JSON.stringify(value) !== JSON.stringify(baseOptions[key])) {
+              finalConfig[key] = value;
+            }
+          }
+
+          if (Object.keys(finalConfig).length > 0) {
+            buildTarget.configurations ??= {};
+
+            let configName = 'testing';
+            if (buildTarget.configurations[configName]) {
+              let counter = 1;
+              while (buildTarget.configurations[`${configName}-${counter}`]) {
+                counter++;
+              }
+              configName = `${configName}-${counter}`;
+            }
+
+            buildTarget.configurations[configName] = finalConfig;
+
+            testTarget.options ??= {};
+            testTarget.options['buildTarget'] = `:build:${configName}`;
+          }
+        }
+      }
+
+      // Update builder
+      testTarget.builder = '@angular/build:unit-test';
+      testTarget.options ??= {};
+      testTarget.options['runner'] = 'vitest';
+
+      hasMigratedAny = true;
+    }
+
+    if (hasMigratedAny) {
+      const rules = [
+        addDependency('vitest', latestVersions['vitest'], {
+          type: DependencyType.Dev,
+          existing: ExistingBehavior.Skip,
+        }),
+      ];
+
+      if (needsCoverage) {
+        rules.push(
+          addDependency('@vitest/coverage-v8', latestVersions['@vitest/coverage-v8'], {
+            type: DependencyType.Dev,
+            existing: ExistingBehavior.Skip,
+          }),
+        );
+      }
+
+      return chain(rules);
+    }
+  });
+}
+
+export default function (): Rule {
+  return updateProjects;
+}