feat(matcher): add per-test filtering via testsFilter and SA11Y_AUTO_FILTER_TESTS

Implements the long-standing TODO for per-test exclusion from automatic
accessibility checks. Adds:
- `testsFilter` field to `AutoCheckOpts` — array of test name substrings
- `skipTestByName()` exported utility, mirroring `skipTest()` for files
- `SA11Y_AUTO_FILTER_TESTS` env var for pipeline-level test name exclusions
- `updateAutoCheckOpts` reads the env var and merges into `testsFilter`

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: 2 people

packages/matcher/__tests__/automaticMatcher.test.ts

@@ -5,7 +5,7 @@
  * For full license text, see the LICENSE file in the repo root or https://opensource.org/licenses/BSD-3-Clause
  */
 
-import { runAutomaticCheck, skipTest, registerCustomSa11yRules } from '../src';
+import { runAutomaticCheck, skipTest, skipTestByName, registerCustomSa11yRules } from '../src';
 
 import {
     beforeEachSetup,
@@ -106,6 +106,39 @@ describe('automatic checks call', () => {
         }
     );
 
+
+    test.each([
+        ['my test name', undefined, false],
+        ['my test name', [], false],
+        ['my test name', ['my test'], true],
+        ['my test name', ['MY TEST'], true],
+        ['my test name', ['my test', 'other'], true],
+        ['my test name', ['other'], false],
+        ['my test name', ['my test name extra'], false],
+    ])(
+        'should filter test by name as expected with args # %#',
+        (testName: string, testsFilter: string[] | undefined, expectedResult: boolean) => {
+            expect(skipTestByName(testName, testsFilter)).toBe(expectedResult);
+        }
+    );
+
+    it('should skip auto checks when test name is excluded using testsFilter', async () => {
+        document.body.innerHTML = domWithA11yIssues;
+        await expect(
+            runAutomaticCheck(
+                { testsFilter: ['non-matching-name', testName] },
+                { renderedDOMDumpDirPath: '' },
+                testPath,
+                testName
+            )
+        ).resolves.toBeUndefined();
+    });
+
+    it('should run auto checks when test name is not excluded using testsFilter', async () => {
+        document.body.innerHTML = domWithA11yIssues;
+        await expect(runAutomaticCheck({ testsFilter: ['non-matching-name'] }, {}, testPath, testName)).rejects.toThrow();
+    });
+
     it('should skip auto checks when file is excluded using filter', async () => {
         document.body.innerHTML = domWithA11yIssues;
         await expect(
@@ -199,6 +232,7 @@ describe('automatic.ts exports', () => {
             cleanupAfterEach: true,
             consolidateResults: true,
             filesFilter: [],
+            testsFilter: [],
             runDOMMutationObserver: false,
             enableIncompleteResults: false,
         });

packages/matcher/src/automatic.ts

@@ -21,10 +21,10 @@ export type AutoCheckOpts = {
     runAfterEach?: boolean;
     cleanupAfterEach?: boolean;
     consolidateResults?: boolean;
-    // TODO (feat): add support for optional exclusion of selected tests
-    // excludeTests?: string[];
-    // List of test file paths (as regex) to filter for automatic checks
+    // List of test file path substrings to filter for automatic checks
     filesFilter?: string[];
+    // List of test name substrings to filter for automatic checks
+    testsFilter?: string[];
     runDOMMutationObserver?: boolean;
     enableIncompleteResults?: boolean;
 };
@@ -45,6 +45,7 @@ export const defaultAutoCheckOpts: AutoCheckOpts = {
     cleanupAfterEach: true,
     consolidateResults: true,
     filesFilter: [],
+    testsFilter: [],
     runDOMMutationObserver: false,
     enableIncompleteResults: false,
 };
@@ -75,6 +76,20 @@ export function skipTest(testPath: string | undefined, filesFilter?: string[]):
     return skip;
 }
 
+/**
+ * Check if current test needs to be skipped based on test name filter
+ */
+export function skipTestByName(testName: string | undefined, testsFilter?: string[]): boolean {
+    if (!testName || !testsFilter || testsFilter.length === 0) return false;
+    const skip = testsFilter.some((filter) => testName.toLowerCase().includes(filter.toLowerCase()));
+    if (skip) {
+        log(
+            `Skipping automatic accessibility check for test "${testName}" as it matches given tests filter: ${testsFilter.toString()}`
+        );
+    }
+    return skip;
+}
+
 /**
  * Run accessibility check on each element node in the body using {@link toBeAccessible}
  * @param opts - Options for automatic checks {@link AutoCheckOpts}
@@ -87,6 +102,7 @@ export async function runAutomaticCheck(
     isFakeTimerUsed: () => boolean = () => false
 ): Promise<void> {
     if (skipTest(testPath, opts.filesFilter)) return;
+    if (skipTestByName(testName, opts.testsFilter)) return;
 
     // Skip automatic check if test is using fake timer as it would result in timeout
     if (isFakeTimerUsed()) {

packages/matcher/src/index.ts

@@ -11,6 +11,7 @@ export {
     mutationObserverCallback,
     observerOptions,
     skipTest,
+    skipTestByName,
     runAutomaticCheck,
     AutoCheckOpts,
     RenderedDOMSaveOpts,

packages/matcher/src/setup.ts

@@ -79,6 +79,11 @@ export function updateAutoCheckOpts(autoCheckOpts: AutoCheckOpts): void {
         'ui-help-components/modules/forceHelp/linkToKnownIssue/__tests__/linkToKnownIssue.spec.js',
     ]);
 
+    if (process.env.SA11Y_AUTO_FILTER_TESTS?.trim().length) {
+        autoCheckOpts.testsFilter = (autoCheckOpts.testsFilter ?? []).concat(
+            process.env.SA11Y_AUTO_FILTER_TESTS.split(',')
+        );
+    }
     autoCheckOpts.runDOMMutationObserver ||= !!process.env.SA11Y_ENABLE_DOM_MUTATION_OBSERVER;
     autoCheckOpts.enableIncompleteResults ||= !!process.env.SA11Y_ENABLE_INCOMPLETE_RESULTS;
 }