[harness eval #34649] fix: preserve disabled a11y rules with runOnly

code/addons/a11y/src/a11yRunner.test.ts

@@ -1,21 +1,62 @@
+import type { AxeResults } from 'axe-core';
 import type { Mock } from 'vitest';
 import { beforeEach, describe, expect, it, vi } from 'vitest';
 
 import { addons } from 'storybook/preview-api';
 
 import { EVENTS } from './constants.ts';
 
+const { axeMock, documentMock } = vi.hoisted(() => {
+  const documentMock = {
+    body: {},
+    getElementById: vi.fn(),
+    location: { pathname: '/iframe.html' },
+  };
+
+  return {
+    documentMock,
+    axeMock: {
+      reset: vi.fn(),
+      configure: vi.fn(),
+      run: vi.fn(),
+    },
+  };
+});
+
+vi.mock('@storybook/global', () => ({
+  global: {
+    document: documentMock,
+  },
+}));
+
+vi.mock('axe-core', () => ({
+  default: axeMock,
+}));
+
 vi.mock('storybook/preview-api');
 const mockedAddons = vi.mocked(addons);
 
+const axeResults = {
+  violations: [],
+  passes: [],
+  incomplete: [],
+  inapplicable: [],
+} as Partial<AxeResults> as AxeResults;
+
 describe('a11yRunner', () => {
   let mockChannel: { on: Mock; emit?: Mock };
 
   beforeEach(() => {
-    mockedAddons.getChannel.mockReset();
+    vi.resetModules();
+    vi.clearAllMocks();
+
+    documentMock.getElementById.mockReturnValue(null);
+    axeMock.run.mockResolvedValue(axeResults);
 
     mockChannel = { on: vi.fn(), emit: vi.fn() };
-    mockedAddons.getChannel.mockReturnValue(mockChannel as any);
+    mockedAddons.getChannel.mockReturnValue(
+      mockChannel as unknown as ReturnType<typeof addons.getChannel>
+    );
   });
 
   it('should listen to events', async () => {
@@ -24,4 +65,67 @@ describe('a11yRunner', () => {
     expect(mockedAddons.getChannel).toHaveBeenCalled();
     expect(mockChannel.on).toHaveBeenCalledWith(EVENTS.MANUAL, expect.any(Function));
   });
+
+  it('passes disabled configured rules to axe.run when runOnly is present', async () => {
+    const { run } = await import('./a11yRunner.ts');
+    const input = {
+      config: {
+        rules: [
+          { id: 'target-size', enabled: false },
+          { id: 'color-contrast', enabled: true },
+        ],
+      },
+      options: {
+        runOnly: ['wcag2a'],
+        rules: {
+          'button-name': { enabled: false },
+        },
+      },
+    };
+
+    await run(input, 'example-story');
+
+    expect(axeMock.configure).toHaveBeenCalledWith({
+      rules: [
+        { id: 'region', enabled: false },
+        { id: 'target-size', enabled: false },
+        { id: 'color-contrast', enabled: true },
+      ],
+    });
+    expect(axeMock.run).toHaveBeenCalledWith(expect.any(Object), {
+      runOnly: ['wcag2a'],
+      rules: {
+        region: { enabled: false },
+        'target-size': { enabled: false },
+        'button-name': { enabled: false },
+      },
+    });
+    expect(axeMock.run.mock.calls[0][1]).not.toBe(input.options);
+    expect(input.options).toEqual({
+      runOnly: ['wcag2a'],
+      rules: {
+        'button-name': { enabled: false },
+      },
+    });
+  });
+
+  it('respects configured rule overrides when collecting disabled rules', async () => {
+    const { run } = await import('./a11yRunner.ts');
+
+    await run(
+      {
+        config: {
+          rules: [{ id: 'region', enabled: true }],
+        },
+        options: {
+          runOnly: ['wcag2a'],
+        },
+      },
+      'example-story'
+    );
+
+    expect(axeMock.run).toHaveBeenCalledWith(expect.any(Object), {
+      runOnly: ['wcag2a'],
+    });
+  });
 });

code/addons/a11y/src/a11yRunner.ts

@@ -2,7 +2,7 @@ import { ElementA11yParameterError } from 'storybook/internal/preview-errors';
 
 import { global } from '@storybook/global';
 
-import type { AxeResults, ContextProp, ContextSpec } from 'axe-core';
+import type { AxeResults, ContextProp, ContextSpec, RunOptions, Spec } from 'axe-core';
 import { addons, waitForAnimations } from 'storybook/preview-api';
 
 import { withLinkPaths } from './a11yRunnerUtils.ts';
@@ -21,6 +21,44 @@ const DISABLED_RULES = [
   'region',
 ] as const;
 
+const getDisabledRules = (rules: Spec['rules'] = []) => {
+  const ruleStates = new Map<string, boolean>();
+
+  rules.forEach(({ id, enabled }) => {
+    if (id && typeof enabled === 'boolean') {
+      ruleStates.set(id, enabled);
+    }
+  });
+
+  return Object.fromEntries(
+    Array.from(ruleStates.entries())
+      .filter(([, enabled]) => !enabled)
+      .map(([id]) => [id, { enabled: false }])
+  ) as NonNullable<RunOptions['rules']>;
+};
+
+const mergeDisabledRulesIntoRunOptions = (options: RunOptions, config: Spec): RunOptions => {
+  // axe.run({ runOnly }) can re-enable tagged rules, so mirror configured disables into
+  // the same run options object without mutating the user's parameters.
+  if (!options.runOnly) {
+    return options;
+  }
+
+  const disabledRules = getDisabledRules(config.rules);
+
+  if (Object.keys(disabledRules).length === 0) {
+    return options;
+  }
+
+  return {
+    ...options,
+    rules: {
+      ...disabledRules,
+      ...options.rules,
+    },
+  };
+};
+
 // A simple queue to run axe-core in sequence
 // This is necessary because axe-core is not designed to run in parallel
 const queue: (() => Promise<void>)[] = [];
@@ -92,6 +130,8 @@ export const run = async (input: A11yParameters = DEFAULT_PARAMETERS, storyId: s
 
   axe.configure(configWithDefault);
 
+  const optionsWithDisabledRules = mergeDisabledRulesIntoRunOptions(options, configWithDefault);
+
   return new Promise<AxeResults>((resolve, reject) => {
     const highlightsRoot = document?.getElementById('storybook-highlights-root');
     if (highlightsRoot) {
@@ -100,7 +140,7 @@ export const run = async (input: A11yParameters = DEFAULT_PARAMETERS, storyId: s
 
     const task = async () => {
       try {
-        const result = await axe.run(context, options);
+        const result = await axe.run(context, optionsWithDisabledRules);
         const resultWithLinks = withLinkPaths(result, storyId);
         resolve(resultWithLinks);
       } catch (error) {