feat(core): expose normalizeRunOptions by qazwsxedcrfvtgb1111 · Pull Request #4998 · dequelabs/axe-core

qazwsxedcrfvtgb1111 · 2026-01-27T23:46:48Z

Move normalizeOptions from axe._audit to axe.utils.normalizeRunOptions

Related to: https://github.com/dequelabs/axe-pro-ml-service/issues/1296

CLAassistant · 2026-01-27T23:46:55Z

All committers have signed the CLA.

Copilot

Pull request overview

Moves run options normalization/validation out of Audit#normalizeOptions and exposes it as axe.utils.normalizeRunOptions, updating call sites and typings accordingly.

Changes:

Added lib/core/utils/normalize-run-options.js and exported it via lib/core/utils/index.js.
Updated Audit#run and finishRun to call axe.utils.normalizeRunOptions.
Migrated/added tests for run options normalization and updated axe.d.ts to expose the new util.

Reviewed changes

Copilot reviewed 6 out of 7 changed files in this pull request and generated 10 comments.

Show a summary per file

File	Description
test/core/utils/normalize-run-options.js	New unit tests for `axe.utils.normalizeRunOptions` behavior.
test/core/base/audit.js	Updates Audit run tests to assert `axe.utils.normalizeRunOptions` is invoked; removes old `Audit#normalizeOptions` tests.
lib/core/utils/normalize-run-options.js	New implementation of the normalized run options helper in utils.
lib/core/utils/index.js	Exposes `normalizeRunOptions` on `axe.utils`.
lib/core/public/finish-run.js	Uses `axe.utils.normalizeRunOptions` instead of `axe._audit.normalizeOptions`.
lib/core/base/audit.js	Uses `axe.utils.normalizeRunOptions` instead of the removed instance method.
axe.d.ts	Adds typings for `NormalizedRunOptions` and `utils.normalizeRunOptions`.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-01-27T23:54:43Z

+  if (typeof options.rules === 'object') {
+    Object.keys(options.rules).forEach(ruleId => {
+      if (!ruleIds.includes(ruleId)) {
+        throw new Error('unknown rule `' + ruleId + '` in options.rules');
+      }
+    });


if (typeof options.rules === 'object') will also be true for null, and Object.keys(null) will throw a TypeError. Add an explicit null check (or stricter type check) so invalid rules values fail with a predictable error (or are treated as absent).

Copilot · 2026-01-27T23:54:43Z

@@ -0,0 +1,79 @@
+/**
+ * Ensure all rules that are expected to run exist
+ * @throws {Error} If any tag or rule specified in options is unknown


The JSDoc says this function throws if any tag is unknown, but unknown tags are only logged (errors are thrown for unknown rules). Update the docstring to reflect the actual behavior.

Suggested change

* @throws {Error} If any tag or rule specified in options is unknown

* @throws {Error} If any rule specified in options is unknown. Unknown tags are logged but do not cause an exception.

Copilot · 2026-01-27T23:54:44Z

+  it('returns the options object when it is valid', () => {
+    const opt = {
+      runOnly: {
+        type: 'rule',
+        values: ['positive1', 'positive2']
+      },
+      rules: {
+        negative1: { enabled: false }
+      }
+    };
+    assert(axe.utils.normalizeRunOptions(opt), opt);
+  });


assert(axe.utils.normalizeRunOptions(opt), opt); does not assert equality (the second argument is treated as a message). Use an equality assertion (e.g., strict/deep equality) so the test actually validates the returned options object.

Copilot · 2026-01-27T23:54:44Z

+  it('allows type: rules as an alternative to type: rule', () => {
+    const opt = {
+      runOnly: {
+        type: 'rules',
+        values: ['positive1', 'positive2']
+      }
+    };
+    assert(axe.utils.normalizeRunOptions(opt).runOnly.type, 'rule');
+  });


assert(axe.utils.normalizeRunOptions(opt).runOnly.type, 'rule'); only asserts that runOnly.type is truthy; it does not check that it equals 'rule'. Switch to an equality assertion so this test would fail if the type is wrong.

Copilot · 2026-01-27T23:54:44Z

+  it('allows type: tags as an alternative to type: tag', () => {
+    const opt = {
+      runOnly: {
+        type: 'tags',
+        values: ['positive']
+      }
+    };
+    assert(axe.utils.normalizeRunOptions(opt).runOnly.type, 'tag');
+  });


assert(axe.utils.normalizeRunOptions(opt).runOnly.type, 'tag'); only asserts that runOnly.type is truthy; it does not check that it equals 'tag'. Use an equality assertion here so the test actually validates the normalization.

Copilot · 2026-01-27T23:54:44Z

+      runOnly: {
+        type: 'tags',
+        values: ['unknwon-tag']
+      }


The test data uses the misspelling unknwon-tag. Consider changing this to unknown-tag to keep fixtures readable (it still represents an unknown tag).

Copilot · 2026-01-27T23:54:45Z

+export default function normalizeRunOptions(options) {
+  const tags = [];
+  const ruleIds = [];
+  axe._audit.rules.forEach(rule => {
+    ruleIds.push(rule.id);
+    rule.tags.forEach(tag => {
+      if (!tags.includes(tag)) {
+        tags.push(tag);
+      }
+    });
+  });
+  // Validate runOnly
+  if (['object', 'string'].includes(typeof options.runOnly)) {
+    if (typeof options.runOnly === 'string') {
+      options.runOnly = [options.runOnly];
+    }


normalizeRunOptions is exposed on axe.utils (and typed as accepting an optional argument), but the implementation will throw if called with undefined/null (it reads options.runOnly unconditionally). Consider defaulting options to {} (and/or throwing a clear TypeError) so the runtime behavior matches the public API contract.

Copilot · 2026-01-27T23:54:45Z

@@ -271,7 +271,7 @@ export default class Audit {
   * @param  {Function}  reject  Callback function to fire when audit experiences an error
   */
  run(context, options, resolve, reject) {


Audit#run now calls axe.utils.normalizeRunOptions(options), but normalizeRunOptions derives valid rule IDs/tags from axe._audit.rules (global), not from this.rules. If Audit is instantiated and used without also setting axe._audit to the same instance, option validation can be performed against the wrong rule set. Consider making normalizeRunOptions validate against the current Audit instance (e.g., by passing this/this.rules in, or otherwise avoiding the global dependency).

Suggested change

run(context, options, resolve, reject) {

run(context, options, resolve, reject) {

// Ensure normalizeRunOptions validates against this Audit instance's rules

axe._audit = this;

Made those changes

✅

straker · 2026-02-03T18:28:58Z

@qazwsxedcrfvtgb1111 LGTM. Just need you to sign the CLA before we can merge

## [4.12.0](v4.11.4...v4.12.0) (2026-06-01) ### Features - add gather-internals.js external script ([#5099](#5099)) ([c61d58b](c61d58b)), closes [#5080](#5080) - **aria-allowed/prohibited-attr, aria-required-parent/children:** partially support element internals role ([#5080](#5080)) ([417b48a](417b48a)), closes [#5039](#5039) [#4259](#4259) - **axe.externalAPIs:** add public api for setting elementInternal data ([#5105](#5105)) ([63bab8f](63bab8f)) - **core:** expose normalizeRunOptions ([#4998](#4998)) ([b8e6a59](b8e6a59)) - expose axe.resetLocale() to restore the default locale ([#5108](#5108)) ([c2b5292](c2b5292)), closes [#5107](#5107) - **getRules:** include rule enabled state in returned objects ([#5118](#5118)) ([75bf772](75bf772)), closes [#5116](#5116) - **list,listitem:** support element internals role ([#5119](#5119)) ([7d9d696](7d9d696)) - **new-rule:** check that aria-tab have an accessible name ([#5001](#5001)) ([0d4e4e7](0d4e4e7)), closes [#4842](#4842) - **rules:** deprecate landmark-complementary-is-top-level rules ([#4992](#4992)) ([9e09139](9e09139)), closes [#4950](#4950) - **utils:** add `getElementInternals` function ([#5077](#5077)) ([1c15f82](1c15f82)) ### Bug Fixes - **aria-allowed-attr:** restrict br and wbr elements to aria-hidden only ([#4974](#4974)) ([c6245e7](c6245e7)) - **aria-conditional-attr:** add support for radio ([#5100](#5100)) ([8223c98](8223c98)) - **aria-valid-attr-value:** handle multiple aria-errormessage IDs ([#4973](#4973)) ([0489e30](0489e30)) - **aria:** prevent getOwnedVirtual from returning duplicate nodes ([#4987](#4987)) ([48ca955](48ca955)), closes [#4840](#4840) - **commons/text:** exclude natively hidden elements from aria-labelledby accessible name ([#5076](#5076)) ([ea7202c](ea7202c)), closes [#4704](#4704) - **DqElement:** avoid calling constructors with cloneNode ([#5013](#5013)) ([0281fa1](0281fa1)) - **existing-rule:** aria-busy now shows an error message for a use with unallowed children ([#5017](#5017)) ([2067b87](2067b87)) - **helpUrl:** ensure axe.configure always updates the help URLs ([#5114](#5114)) ([c4f60ff](c4f60ff)) - **label-content-name-mismatch:** match visible text with aria-label and exclude invisible text ([#5096](#5096)) ([3a012a1](3a012a1)) - **locale:** ensure all subtags are correctly set ([#5112](#5112)) ([13005ed](13005ed)) - **scrollable-region-focusable:** clarify the issue is in safari ([#4995](#4995)) ([4ec5211](4ec5211)), closes [WebKit#190870](https://github.com/dequelabs/WebKit/issues/190870) [WebKit#277290](https://github.com/dequelabs/WebKit/issues/277290) - **scrollable-region-focusable:** do not fail scroll areas when all content is visible without scrolling ([#4993](#4993)) ([838707a](838707a)) - **target-size:** determine offset using clientRects if target is display:inline ([#5012](#5012)) ([a4b8091](a4b8091)) - **target-size:** ignore position: fixed elements that are offscreen when page is scrolled ([#5066](#5066)) ([1229a6e](1229a6e)), closes [#5065](#5065) - **target-size:** ignore widgets that are inline with other inline elements ([#5000](#5000)) ([a8dd81b](a8dd81b)) - **utils/getAncestry:** escape node name ([#5079](#5079)) ([d1fabaa](d1fabaa)), closes [#5078](#5078) - **utils:** Add null check to parseCrossOriginStylesheet, closes [#5074](#5074) ([#5075](#5075)) ([f12ef32](f12ef32)) - **utils:** update isShadowRoot to use spec-compliant custom element regex ([#5059](#5059)) ([edc6ce2](edc6ce2)), closes [#5030](#5030) This PR was opened by a robot 🤖 🎉

feat(core): expose normalizeRunOptions

5f4d7b7

qazwsxedcrfvtgb1111 requested a review from a team as a code owner January 27, 2026 23:46

Copilot AI review requested due to automatic review settings January 27, 2026 23:46

Copilot started reviewing on behalf of qazwsxedcrfvtgb1111 January 27, 2026 23:47 View session

Copilot AI reviewed Jan 27, 2026

View reviewed changes

straker previously requested changes Jan 28, 2026

View reviewed changes

Comment thread lib/core/base/audit.js Outdated

Comment thread lib/core/public/finish-run.js Outdated

Comment thread lib/core/utils/normalize-run-options.js Outdated

Comment thread test/core/base/audit.js Outdated

Comment thread test/core/utils/normalize-run-options.js Outdated

address pr comments

246ca8f

straker previously requested changes Feb 2, 2026

View reviewed changes

Comment thread lib/core/base/audit.js Outdated

move import

60e2239

qazwsxedcrfvtgb1111 requested a review from straker February 3, 2026 17:29

straker approved these changes Feb 3, 2026

View reviewed changes

WilcoFiers merged commit b8e6a59 into develop Feb 5, 2026
23 checks passed

WilcoFiers deleted the expose-normalize-run-options branch February 5, 2026 16:00

attest-team-ci mentioned this pull request Mar 30, 2026

chore(release): v4.12.0 #5047

Closed

attest-team-ci mentioned this pull request Jun 1, 2026

chore(release): v4.12.0 #5122

Merged

	* @throws {Error} If any tag or rule specified in options is unknown
	* @throws {Error} If any rule specified in options is unknown. Unknown tags are logged but do not cause an exception.

Uh oh!

Conversation

qazwsxedcrfvtgb1111 commented Jan 27, 2026

Uh oh!

CLAassistant commented Jan 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Jan 27, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 27, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 27, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 27, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 27, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 27, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 27, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 27, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

straker commented Feb 3, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

CLAassistant commented Jan 27, 2026 •

edited

Loading