Skip to content

Commit 7eb3d2d

Browse files
strakerGarbeechutchins25WilcoFiers
committed
fix(axe.d.ts): make enabled property of RuleMetadata optional (#5129)
This was an accidental breaking change if anyone uses `RuleMetadata` directly. --------- Co-authored-by: Jonathan Garbee <[email protected]> Co-authored-by: Chris Hutchins <[email protected]> Co-authored-by: Wilco Fiers <[email protected]>
1 parent 0feedd3 commit 7eb3d2d

5 files changed

Lines changed: 86 additions & 7 deletions

File tree

‎axe.d.ts‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -352,7 +352,7 @@ declare namespace axe {
352352
helpUrl: string;
353353
tags: string[];
354354
actIds?: string[];
355-
enabled: boolean;
355+
enabled?: boolean;
356356
}
357357
interface SerialDqElement {
358358
source: string;
@@ -623,7 +623,9 @@ declare namespace axe {
623623
* @param {Array} tags Optional array of tags
624624
* @return {Array} Array of rules
625625
*/
626-
function getRules(tags?: string[]): RuleMetadata[];
626+
function getRules(
627+
tags?: string[]
628+
): (Omit<RuleMetadata, 'enabled'> & { enabled: boolean })[];
627629

628630
/**
629631
* Restores the default axe configuration

‎doc/API.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -137,7 +137,7 @@ Returns a list of all rules with their ID and description
137137

138138
- `tags` - **optional** Array of tags used to filter returned rules. If omitted, it will return all rules. See [axe-core tags](#axe-core-tags).
139139

140-
**Returns:** Array of rules that match the input filter with each entry having a format of `{ruleId: <id>, description: <desc>, helpUrl: <url>, help: <help>, tags: <tags>, enabled: <boolean>}`. `enabled` is `true` for rules that run by default when `axe.run()` is called with no options, and `false` for rules that are disabled by default.
140+
**Returns:** Array of rules that match the input filter with each entry having a format of `{ruleId: <id>, description: <desc>, helpUrl: <url>, help: <help>, tags: <tags>, enabled: <boolean>}`. `enabled` is `true` for rules that run by default when `axe.run()` is called with no options, and `false` for rules that are disabled by default (i.e. experimental and deprecated rules).
141141

142142
#### Example 1
143143

‎lib/core/public/get-rules.js‎

Lines changed: 8 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -5,15 +5,17 @@
55
*/
66
function getRules(tags) {
77
tags = tags || [];
8+
const { rules, data, tagExclude } = axe._audit;
9+
810
const matchingRules = !tags.length
9-
? axe._audit.rules
10-
: axe._audit.rules.filter(item => {
11+
? rules
12+
: rules.filter(item => {
1113
return !!tags.filter(tag => {
1214
return item.tags.indexOf(tag) !== -1;
1315
}).length;
1416
});
1517

16-
const ruleData = axe._audit.data.rules || {};
18+
const ruleData = data.rules || {};
1719
return matchingRules.map(matchingRule => {
1820
const rd = ruleData[matchingRule.id] || {};
1921
return {
@@ -23,7 +25,9 @@ function getRules(tags) {
2325
helpUrl: rd.helpUrl,
2426
tags: matchingRule.tags,
2527
actIds: matchingRule.actIds,
26-
enabled: matchingRule.enabled
28+
enabled:
29+
matchingRule.enabled &&
30+
!matchingRule.tags.some(tag => tagExclude.includes(tag))
2731
};
2832
});
2933
}

‎test/core/public/get-rules.js‎

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -111,6 +111,60 @@ describe('axe.getRules', () => {
111111
assert.equal(retValue[1].enabled, false);
112112
});
113113

114+
it('should return false for experimental rules', () => {
115+
axe._load({
116+
messages: [],
117+
rules: [
118+
{
119+
id: 'awesomeRule3',
120+
selector: '',
121+
excludeHidden: false,
122+
any: [],
123+
tags: ['tag1', 'experimental']
124+
}
125+
],
126+
data: {
127+
rules: {
128+
awesomeRule3: {
129+
description: 'some interesting information',
130+
help: 'halp'
131+
}
132+
}
133+
}
134+
});
135+
136+
const retValue = axe.getRules();
137+
assert.lengthOf(retValue, 1);
138+
assert.equal(retValue[0].enabled, false);
139+
});
140+
141+
it('should return false for deprecated rules', () => {
142+
axe._load({
143+
messages: [],
144+
rules: [
145+
{
146+
id: 'awesomeRule3',
147+
selector: '',
148+
excludeHidden: false,
149+
any: [],
150+
tags: ['tag1', 'deprecated']
151+
}
152+
],
153+
data: {
154+
rules: {
155+
awesomeRule3: {
156+
description: 'some interesting information',
157+
help: 'halp'
158+
}
159+
}
160+
}
161+
});
162+
163+
const retValue = axe.getRules();
164+
assert.lengthOf(retValue, 1);
165+
assert.equal(retValue[0].enabled, false);
166+
});
167+
114168
it('should return all rules if given empty array', () => {
115169
const retValue = axe.getRules([]);
116170
assert.equal(retValue[0].ruleId, 'awesomeRule1');

‎typings/axe-core/axe-core-tests.ts‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -512,3 +512,22 @@ axe.commons.dom.isFocusable(document.body);
512512
axe.commons.dom.isNativelyFocusable(document.body);
513513
axe.commons.dom.getNodeGrid(document.body);
514514
axe.commons.text.accessibleText(document.body);
515+
516+
// Types
517+
/**
518+
* Validate the original structure for metadata persists in support.
519+
* Do not amend this structure with new properties. As all new properties
520+
* should be optional as to not break existing implementations.
521+
*/
522+
let metadata: axe.RuleMetadata;
523+
metadata = {
524+
ruleId: 'color-contrast',
525+
description: 'Check if colors pass WCAG contrast ratio',
526+
help: 'Colors must pass contrast ratios',
527+
helpUrl: 'https://help-url.com',
528+
tags: ['wcag2.1', 'other-tag']
529+
};
530+
// 'enabled' is optional in RuleMetadata but required for getRules return
531+
axe.getRules(['wcag2aa'])[0].enabled.toString();
532+
// @ts-expect-error 'actIds' is optional in RuleMetadata and getRules
533+
axe.getRules(['wcag2aa'])[0].actIds.toString();

0 commit comments

Comments
 (0)