[Bug]: addon-a11y "config.rules" being overridden when "options.runOnly" is present

[basher]

Describe the bug

Ref: see this comment in issue 34613

I've managed to setup a working implementation of Vitest a11y testing in my (unsupported) Storybook/HTML repo.

In the comment referenced above, I've had to implement a temporary workaround to enable me to disable a couple of Axe rules that are failing when they should not be - snippet from my .storybook/preview.js:

a11y: {
    // 'todo' - show a11y violations in the test UI only
    // 'error' - fail CI on a11y violations
    // 'off' - skip a11y checks entirely
    test: 'error',
    context: 'body',
    config: {},
    options: {
        runOnly: ['wcag2a', 'wcag2aa', 'wcag21a', 'wcag21aa', 'best-practice', 'wcag22a', 'wcag22aa'],
        rules: {
            'target-size': { enabled: false },
            'region': { enabled: false },
        },
    },
},

The issues I'm having are two-fold:

1. I've had to move my disabled rules from config.rules into options.rules so they're in the same axe.run() call as runOnly. This points to a bug in the addon where disabled rules from config should be forwarded into the options.rules passed to axe.run() when runOnly is present.
2. I should not have to disable either rule:
   (a) region should already be ignored in a Storybook context as components are often rendered standalone, not inside landmark regions.
   (b) target-size is failing in CLI only for a number of components, but passing from the Storybook UI (as well as passing with 3 different browser devtools a11y checkers - AxeCore, ARC Toolkit, IBM Equal Access).

Furthermore, one of the failing components passes tests with no additional rule overrides in my simple reproduction repo, which only contains 1 story.

Reproduction link

https://github.com/basher/Web-UI-Boilerplate/tree/master

Reproduction steps

1. npm run test-storybook from the repro link above. 96 tests run. All pass.
2. Comment out the 2 rules overrides in .storybook/preview.js, and region / target-size tests fail for a large number of components.
3. npm run test-storybook from the minimal repo, which only contains 1 story. Tests run. All pass. No rules overrides necessary.

System

Storybook Environment Info:
│

│  System:
│  OS: Windows 10 10.0.19045
│  CPU: (4) x64 Intel(R) Core(TM) i7-6500U CPU @ 2.50GHz
│  Binaries:
│  Node: 22.19.0 - C:\Program Files\nodejs\node.EXE
│  Yarn: 1.22.22 - C:\Users\kev\AppData\Roaming\npm\yarn.CMD
│  npm: 10.9.3 - C:\Program Files\nodejs\npm.CMD <----- active
│  Browsers:
│  Chrome: 147.0.7727.102
│  Edge: Chromium (140.0.3485.94)
│  Firefox: 150.0 - C:\Program Files (x86)\Mozilla Firefox\firefox.exe
│  npmPackages:
│  @storybook/addon-a11y: ^10.3.5 => 10.3.5
│  @storybook/addon-docs: ^10.3.5 => 10.3.5
│  @storybook/addon-vitest: ^10.3.5 => 10.3.5
│  @storybook/html-vite: ^10.3.5 => 10.3.5
│  storybook: ^10.3.5 => 10.3.5

Additional context

No response

[dosubot]

Thanks for the detailed writeup and reproduction, @basher. This does look like a legitimate bug.

Looking at the addon source, the issue is clear: axe.configure(config) and axe.run(context, options) are called separately with no merging between them [1]. When options.runOnly specifies tags like wcag22aa, axe-core can re-enable rules matching those tags — overriding what was disabled via axe.configure(). The addon doesn't forward disabled rules from config.rules into options.rules to prevent this.

This also explains why the region rule fires despite the addon disabling it by default — the default disable goes into axe.configure(), but runOnly in axe.run() can override it.

Your workaround (putting disabled rules in options.rules alongside runOnly) is correct — when both are in the same axe.run() call, axe-core respects the disabled state.

The fix would be in a11yRunner.ts: before calling axe.run(), the addon should merge any disabled rules from configWithDefault.rules into the options.rules object when options.runOnly is present. This would ensure axe.configure() disables aren't silently overridden.

On the target-size false failures in CLI but not in the Storybook UI — this is likely related to the Vitest rendering environment producing a slightly different layout (no Storybook wrappers, different viewport handling), which can affect how axe-core measures touch target sizes. This is a separate concern from the config merging bug but compounds the problem since you can't work around it by disabling the rule via config.rules.

To reply, just mention @dosu.

---

Share context across your team and agents. Try Dosu.