For AI agents and LLMs: a machine-readable index is available at llms.txt. A plain-Markdown version of any documentation page is available by appending .md to its URL.
Skip to main content

Rule and Category Exclusion for Web Accessibility Automation

Rule and category exclusion lets you remove individual accessibility rules, or entire rule categories, from a web accessibility automation scan before it runs. Two capabilities control it, on Selenium and Playwright sessions, both on the TestMu AI cloud grid and on HyperExecute:

CapabilityTypeEffect
accessibility.excludeRulesarray of axe rule IDs, or a comma-separated stringEach named rule is removed from the effective rule set for the session
accessibility.excludeRuleCategoriesarray of category slugs, or a comma-separated stringEvery rule in each named category is removed from the effective rule set

Both are optional and can be combined. An excluded rule never runs: it is absent from the findings and from the score, the report says which rules ran and why the rest did not, and that snapshot is stored with the test so any result can be reproduced later. A session that sets neither capability behaves exactly as before.

When to use this​

Use exclusion when your team has a known, accepted deviation that should not fail every build, for example a design-system colour token whose contrast has been signed off, or a third-party widget you cannot change. Without exclusion the only options were to live with permanently failing builds, or to hide the finding in the report afterwards, which distorts the score and cannot be enforced in CI.

Exclusion is part of the scan configuration, so it is enforceable in CI and applies to every scan in the session, including scans triggered by accessibility.autoscan. To suppress a single finding after a scan has run, use Hide and Restore Issues instead.

note

This page covers automation capabilities. For the same controls in the DevTools extension and in scheduled scans, see Rule and Category Exclusion in DevTools and Scheduled Scans. For Appium mobile automation, see Rule and Category Exclusion for Mobile App Accessibility.

Prerequisites​

  • A Selenium or Playwright project running on the TestMu AI cloud grid or on HyperExecute, with accessibility enabled through accessibility: true. See Configure Accessibility Automation.
  • Scans triggered with the lambda-accessibility-scan hook, or automatically with accessibility.autoscan.

Rule IDs​

Web rule IDs are the standard axe-core rule IDs, passed as they are. Matching is case-insensitive. Examples:

RuleRule ID
Elements must meet minimum colour contrast ratio thresholdscolor-contrast
Images must have alternative textimage-alt
Form elements must have labelslabel
Required ARIA attributes must be providedaria-required-attr
Links must have discernible textlink-name
Links must be distinguishable without relying on colourlink-in-text-block

You can copy a rule ID straight out of a report or from the axe-core rule descriptions. Rules that axe-core marks as deprecated are not part of the catalog, because they never run. The Web Rule Repository maps rules to their WCAG success criteria.

The five AI-powered rules that TestMu AI adds on top of axe have their own IDs: alt-descriptive, alt-decorative-hidden, image-in-text, html-title-descriptive and html-lang-matches-visible-language. AI rules do not run on automation sessions, so these IDs are dropped at validation if they are passed in accessibility.excludeRules. They can be switched off in DevTools and in scheduled scans.

Category slugs​

Categories are axe-core's own rule categories, addressed by a lowercase, hyphenated slug. Every rule belongs to exactly one category. The web catalog has twelve:

CategorySlug
ARIAaria
Structure and Semanticsstructure-and-semantics
Text Alternativestext-alternatives
Keyboardkeyboard
Name Role Valuename-role-value
Tablestables
Formsforms
Languagelanguage
Time and Mediatime-and-media
Color Contrastcolor-contrast
Sensory and Visual Cuessensory-and-visual-cues
Parsingparsing

Matching is case-insensitive and tolerates spaces, so "Text Alternatives" is accepted as well as text-alternatives. How many rules a category removes from a given scan depends on the selected WCAG version and level and on the Best Practices toggle, because each of those narrows the set before any exclusion applies.

tip

color-contrast is both a rule ID and a category slug. The capability you put it in decides what it means: in accessibility.excludeRules it removes the single contrast-ratio rule, in accessibility.excludeRuleCategories it removes every rule in the Color Contrast category.

Examples​

Enable accessibility, target WCAG 2.1 AA, skip two specific rules, and skip the whole ARIA category.

"LT:Options": {
  "accessibility": true,
  "accessibility.wcagVersion": "wcag21aa",
  "accessibility.bestPractice": true,
  "accessibility.excludeRules": ["color-contrast", "image-alt"],
  "accessibility.excludeRuleCategories": "aria"
}

A comma-separated string is accepted wherever an array is, which is convenient in configuration files and CI variables:

"accessibility.excludeRules": "color-contrast,image-alt",
"accessibility.excludeRuleCategories": "aria,tables"

HyperExecute. Pass the same capabilities from your test code. They are read and validated by the same logic as on the cloud grid, so nothing in hyperexecute.yaml needs to change. See HyperExecute: Selenium accessibility automation.

How the effective rule set is resolved​

Exclusion is applied on top of the existing scan configuration. Every step only removes rules, so an exclusion can never add a rule back, and the first step that removes a rule is the reason recorded for it:

  1. WCAG version and level. Cumulative, as before: wcag21aa includes every WCAG 2.0 and 2.1 rule at level A or AA.
  2. Best Practices toggle. Best Practice rules are removed while accessibility.bestPractice is false. This is the only rule-level group toggle on web.
  3. Excluded categories. Every rule in a category named in accessibility.excludeRuleCategories is removed.
  4. Excluded rules. Every rule named in accessibility.excludeRules is removed.

Consequences of this order:

  • A rule named in excludeRules that also belongs to an excluded category is attributed to the category, and the duplicate entry is ignored without error.
  • A rule that is already outside the WCAG range and is also named in excludeRules is a silent no-op.
  • A Best Practice rule named in excludeRules while accessibility.bestPractice is false is attributed to the toggle, not to the exclusion.
note

accessibility.needsReview is not part of exclusion. It filters uncertain results after a rule has run, and a single rule can produce both a violation and a needs-review item in the same scan, so there is nothing rule-level to exclude. It never appears as a row in Applied Settings.

What happens at session creation​

Exclusions are validated when the session is created, before a browser is allocated. This applies on the cloud grid and on HyperExecute.

InputOutcome
Valid rule ID or category slugApplied
Unknown rule IDLogged and dropped; the session proceeds
Unknown category slugLogged and dropped; the session proceeds
AI rule ID passed on an automation sessionDropped; AI rules do not run on automation
Wrong type (a number, for example)The capability is ignored with a warning; the session proceeds
Every entry invalidThe scan runs with the full configured rule set
Exclusions remove every in-scope ruleSession creation is rejected. No test is created and no browser is allocated
Rule catalog temporarily unreachableThe lists are applied as written without validation; the scan still refuses to run against an empty rule set
Session is a real-device mobile browserRejected. The capabilities support desktop web and native Android and iOS apps only

A misspelled rule ID or category never fails your functional test. The scan runs with whatever exclusions were valid, and the session log records which entries were dropped and why.

Excluding every rule rejects the session​

If the exclusions leave nothing to evaluate, whether by naming every rule, excluding every category, or a mix of both, the session is refused at creation with an HTTP 400 error. The error surfaces at driver initialisation in your test, no test record is created, and no browser time is used. The message states how many rules were in scope and how many each list removed, in this form:

All <N> rules in scope for WCAG 2.1 AA were excluded by this configuration (<n> by category, <n> by rule).
Include at least one rule to run an accessibility scan. Remove a value from accessibility.excludeRuleCategories
or accessibility.excludeRules, or set accessibility=false to disable accessibility scanning for this session.

Remove at least one entry, or set accessibility to false if that session should not run an accessibility scan at all.

What to expect in results​

  • Filtered before execution. An excluded rule is switched off in axe before the scan runs. It is absent from the findings and from the score by construction, not filtered out of the results afterwards.
  • Score reflects the evaluated set. The accessibility score is computed only over the rules that ran.
  • Applied Settings on every web report. The Applied Settings popover, previously available only on mobile app reports, now appears on every web report. It groups the rules by category. An excluded category is greyed out, and an individually excluded rule is shown as Off.
  • Reproducible. Both lists are stored with the test and returned by the test-detail API, so any historical result can be reproduced. Merged reports fold in the lists of their source reports.

FAQ​

Can I exclude a rule for one page only? No. Exclusions apply to every scan in the session, including scans triggered by accessibility.autoscan. To suppress a single finding after the fact, use Hide and Restore Issues.

Is there an include list? No. Exclusion only removes rules. To run a narrower set, lower the WCAG target or switch off Best Practices, then exclude what remains.

Can I exclude a single element or selector rather than a rule? No. Exclusion works at rule and category level. Use Hide and Restore Issues for a specific element in a report.

Why does my exclusion not appear in the report? Check the session log for a dropped entry (a misspelled ID or slug), and check whether the rule was already removed by the WCAG range or the Best Practices toggle. A rule removed earlier in the resolution order is attributed to that step, not to the exclusion.

Do the capabilities work on Cypress or on real-device mobile browsers? This release supports Selenium and Playwright sessions on desktop browsers, on the cloud grid and on HyperExecute. Cypress is not part of this release. A session on a real-device mobile browser is rejected.

Do I need to change anything if I do not use exclusions? No. The capabilities are opt-in. A session that sets neither produces the same rule set as before.

Last updated on

Terminal First Testing With Kane CLI

Natural language browser & mobile app tests right from terminal.

×
Schedule Your Personal Demo
Kane CLI terminal

Help and Support

Related Articles

On this page