feat(@angular/build): add 'filter' option to unit-test builder

This change introduces a new `filter` option to the `unit-test` builder. This allows users to specify a regular expression to match against test description names, providing a way to run a subset of tests.

The option is implemented for the Vitest runner by passing the value to the `testNamePattern` configuration option. A warning is added for the Karma runner to inform users that the option is not yet supported there.

Author: clydin

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

@@ -222,6 +222,7 @@ export type UnitTestBuilderOptions = {
     codeCoverageReporters?: SchemaCodeCoverageReporter[];
     debug?: boolean;
     exclude?: string[];
+    filter?: string;
     include?: string[];
     progress?: boolean;
     providersFile?: string;

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

@@ -33,7 +33,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, reporters, browsers, progress, filter } = options;
 
   return {
     // Project/workspace information
@@ -45,6 +45,7 @@ export async function normalizeOptions(
     buildTarget,
     include: options.include ?? ['**/*.spec.ts'],
     exclude: options.exclude,
+    filter,
     runnerName: runner,
     codeCoverage: options.codeCoverage
       ? {

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

@@ -33,6 +33,12 @@ export class KarmaExecutor implements TestExecutor {
       );
     }
 
+    if (unitTestOptions.filter) {
+      context.logger.warn(
+        'The "karma" test runner does not support the "filter" option. The option will be ignored.',
+      );
+    }
+
     const buildTargetOptions = (await context.validateOptions(
       await context.getTargetOptions(unitTestOptions.buildTarget),
       await context.getBuilderNameForTarget(unitTestOptions.buildTarget),

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

@@ -187,6 +187,7 @@ export class VitestExecutor implements TestExecutor {
         project: ['base', this.projectName],
         name: 'base',
         include: [],
+        testNamePattern: this.options.filter,
         reporters: reporters ?? ['default'],
         watch,
         coverage: generateCoverageOption(codeCoverage),

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

@@ -41,6 +41,10 @@
       },
       "description": "Globs of files to exclude, relative to the project root."
     },
+    "filter": {
+      "type": "string",
+      "description": "A regular expression to match against test names, running only matching tests."
+    },
     "watch": {
       "type": "boolean",
       "description": "Re-run tests when source files change. Defaults to `true` in TTY environments and `false` otherwise."

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

@@ -0,0 +1,62 @@
+/**
+ * @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 { execute } from '../../builder';
+import {
+  BASE_OPTIONS,
+  describeBuilder,
+  UNIT_TEST_BUILDER_INFO,
+  setupApplicationTarget,
+} from '../setup';
+
+describeBuilder(execute, UNIT_TEST_BUILDER_INFO, (harness) => {
+  describe('Option: "filter"', () => {
+    beforeEach(async () => {
+      setupApplicationTarget(harness);
+
+      await harness.writeFiles({
+        'src/app/pass.spec.ts': `
+          describe('Passing Suite', () => {
+            it('should pass', () => {
+              expect(true).toBe(true);
+            });
+          });
+        `,
+        'src/app/fail.spec.ts': `
+          describe('Failing Suite', () => {
+            it('should fail', () => {
+              expect(true).toBe(false);
+            });
+          });
+        `,
+      });
+    });
+
+    it('should only run tests that match the filter regex', async () => {
+      harness.useTarget('test', {
+        ...BASE_OPTIONS,
+        // This filter should only match the 'should pass' test
+        filter: 'pass$',
+      });
+
+      const { result } = await harness.executeOnce();
+      // The overall result should be success because the failing test was filtered out.
+      expect(result?.success).toBe(true);
+    });
+
+    it('should run all tests when no filter is provided', async () => {
+      harness.useTarget('test', {
+        ...BASE_OPTIONS,
+      });
+
+      const { result } = await harness.executeOnce();
+      // The overall result should be failure because the failing test was included.
+      expect(result?.success).toBe(false);
+    });
+  });
+});