feat(@angular/build): allow options for unit test reporters

This change enhances the `reporters` option in the unit-test builder to support passing an options object, similar to the existing `codeCoverageReporters` option. Users can now specify a reporter as a tuple of `[name, options]`.

- The `schema.json` is updated to allow either a string or a `[string, object]` tuple in the `reporters` array. An `enum` is provided for common reporters while still allowing custom string paths.
- The option normalization logic in `options.ts` is refactored into a shared helper function to handle both `reporters` and `codeCoverageReporters`, reducing code duplication.
- The Karma runner, which does not support reporter options, is updated to safely ignore them and warn the user.

Author: clydin

goldens/public-api/angular/build/index.api.md

@@ -225,7 +225,7 @@ export type UnitTestBuilderOptions = {
     include?: string[];
     progress?: boolean;
     providersFile?: string;
-    reporters?: string[];
+    reporters?: SchemaReporter[];
     runner: Runner;
     setupFiles?: string[];
     tsConfig: string;

packages/angular/build/src/builders/unit-test/options.ts

@@ -15,6 +15,16 @@ import type { Schema as UnitTestBuilderOptions } from './schema';
 
 export type NormalizedUnitTestBuilderOptions = Awaited<ReturnType<typeof normalizeOptions>>;
 
+function normalizeReporterOption(
+  reporters: unknown[] | undefined,
+): [string, Record<string, unknown>][] | undefined {
+  return reporters?.map((entry) =>
+    typeof entry === 'string'
+      ? ([entry, {}] as [string, Record<string, unknown>])
+      : (entry as [string, Record<string, unknown>]),
+  );
+}
+
 export async function normalizeOptions(
   context: BuilderContext,
   projectName: string,
@@ -33,7 +43,7 @@ export async function normalizeOptions(
   const buildTargetSpecifier = options.buildTarget ?? `::development`;
   const buildTarget = targetFromTargetString(buildTargetSpecifier, projectName, 'build');
 
-  const { tsConfig, runner, reporters, browsers, progress } = options;
+  const { tsConfig, runner, browsers, progress } = options;
 
   return {
     // Project/workspace information
@@ -49,16 +59,12 @@ export async function normalizeOptions(
     codeCoverage: options.codeCoverage
       ? {
           exclude: options.codeCoverageExclude,
-          reporters: options.codeCoverageReporters?.map((entry) =>
-            typeof entry === 'string'
-              ? ([entry, {}] as [string, Record<string, unknown>])
-              : (entry as [string, Record<string, unknown>]),
-          ),
+          reporters: normalizeReporterOption(options.codeCoverageReporters),
         }
       : undefined,
     tsConfig,
     buildProgress: progress,
-    reporters,
+    reporters: normalizeReporterOption(options.reporters),
     browsers,
     watch: options.watch ?? isTTY(),
     debug: options.debug ?? false,

packages/angular/build/src/builders/unit-test/runners/karma/executor.ts

@@ -60,7 +60,16 @@ export class KarmaExecutor implements TestExecutor {
       codeCoverage: !!unitTestOptions.codeCoverage,
       codeCoverageExclude: unitTestOptions.codeCoverage?.exclude,
       fileReplacements: buildTargetOptions.fileReplacements,
-      reporters: unitTestOptions.reporters,
+      reporters: unitTestOptions.reporters?.map((reporter) => {
+        // Karma only supports string reporters.
+        if (Object.keys(reporter[1]).length > 0) {
+          context.logger.warn(
+            `The "karma" test runner does not support options for the "${reporter[0]}" reporter. The options will be ignored.`,
+          );
+        }
+
+        return reporter[0];
+      }),
       webWorkerTsConfig: buildTargetOptions.webWorkerTsConfig,
       aot: buildTargetOptions.aot,
     };

packages/angular/build/src/builders/unit-test/schema.json

@@ -88,9 +88,40 @@
     },
     "reporters": {
       "type": "array",
-      "description": "Test runner reporters to use. Directly passed to the test runner.",
+      "description": "Specifies the reporters to use during test execution. Each reporter can be a string representing its name, or a tuple containing the name and an options object. Built-in reporters include 'default', 'verbose', 'dots', 'json', 'junit', 'tap', 'tap-flat', and 'html'. You can also provide a path to a custom reporter.",
       "items": {
-        "type": "string"
+        "oneOf": [
+          {
+            "anyOf": [
+              {
+                "$ref": "#/definitions/reporters-enum"
+              },
+              {
+                "type": "string"
+              }
+            ]
+          },
+          {
+            "type": "array",
+            "minItems": 1,
+            "maxItems": 2,
+            "items": [
+              {
+                "anyOf": [
+                  {
+                    "$ref": "#/definitions/reporters-enum"
+                  },
+                  {
+                    "type": "string"
+                  }
+                ]
+              },
+              {
+                "type": "object"
+              }
+            ]
+          }
+        ]
       }
     },
     "providersFile": {
@@ -124,6 +155,10 @@
         "json",
         "json-summary"
       ]
+    },
+    "reporters-enum": {
+      "type": "string",
+      "enum": ["default", "verbose", "dots", "json", "junit", "tap", "tap-flat", "html"]
     }
   }
 }

packages/angular/build/src/builders/unit-test/tests/options/reporters_spec.ts

@@ -15,34 +15,66 @@ import {
 } from '../setup';
 
 describeBuilder(execute, UNIT_TEST_BUILDER_INFO, (harness) => {
-  xdescribe('Option: "reporters"', () => {
-    beforeEach(async () => {
+  describe('Option: "reporters"', () => {
+    beforeEach(() => {
       setupApplicationTarget(harness);
     });
 
-    it('should use the default reporter when none is specified', async () => {
+    it(`should support a single reporter`, async () => {
       harness.useTarget('test', {
         ...BASE_OPTIONS,
+        reporters: ['json'],
       });
 
-      const { result, logs } = await harness.executeOnce();
+      const { result } = await harness.executeOnce();
       expect(result?.success).toBeTrue();
-      expect(logs).toContain(
-        jasmine.objectContaining({ message: jasmine.stringMatching(/DefaultReporter/) }),
-      );
     });
 
-    it('should use a custom reporter when specified', async () => {
+    it(`should support multiple reporters`, async () => {
       harness.useTarget('test', {
         ...BASE_OPTIONS,
-        reporters: ['json'],
+        reporters: ['json', 'verbose'],
+      });
+
+      const { result } = await harness.executeOnce();
+      expect(result?.success).toBeTrue();
+    });
+
+    it(`should support a single reporter with options`, async () => {
+      harness.useTarget('test', {
+        ...BASE_OPTIONS,
+        reporters: [['json', { outputFile: 'a.json' }]],
+      });
+
+      const { result } = await harness.executeOnce();
+      expect(result?.success).toBeTrue();
+      harness.expectFile('a.json').toExist();
+    });
+
+    it(`should support multiple reporters with options`, async () => {
+      harness.useTarget('test', {
+        ...BASE_OPTIONS,
+        reporters: [
+          ['json', { outputFile: 'a.json' }],
+          ['junit', { outputFile: 'a.xml' }],
+        ],
+      });
+
+      const { result } = await harness.executeOnce();
+      expect(result?.success).toBeTrue();
+      harness.expectFile('a.json').toExist();
+      harness.expectFile('a.xml').toExist();
+    });
+
+    it(`should support multiple reporters with and without options`, async () => {
+      harness.useTarget('test', {
+        ...BASE_OPTIONS,
+        reporters: [['json', { outputFile: 'a.json' }], 'verbose', 'default'],
       });
 
-      const { result, logs } = await harness.executeOnce();
+      const { result } = await harness.executeOnce();
       expect(result?.success).toBeTrue();
-      expect(logs).toContain(
-        jasmine.objectContaining({ message: jasmine.stringMatching(/JsonReporter/) }),
-      );
+      harness.expectFile('a.json').toExist();
     });
   });
 });