Skip to content

Commit

Permalink
Merge pull request #774 from dequelabs/runoly-fix
Browse files Browse the repository at this point in the history 
feat: Make options.runOnly more forgiving about plurality
  • Loading branch information
@WilcoFiers
WilcoFiers authored Mar 16, 2018
2 parents df498d9 + 180eba2 commit dc0241b
Show file tree
Hide file tree
Showing 3 changed files with 253 additions and 149 deletions.
240 changes: 124 additions & 116 deletions doc/API.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -119,10 +119,10 @@ In this example, we pass in the WCAG 2 A and AA tags into `axe.getRules` to retr

```javascript
[
{ ruleId: "area-alt", description: "Checks the <area> elements of image…" },
{ ruleId: "aria-allowed-attr", description: "Checks all attributes that start…" },
{ ruleId: "aria-required-attr", description: "Checks all elements that contain…" },
…
{ ruleId: "area-alt", description: "Checks the <area> elements of image…" },
{ ruleId: "aria-allowed-attr", description: "Checks all attributes that start…" },
{ ruleId: "aria-required-attr", description: "Checks all elements that contain…" },
…
]
```

Expand Down Expand Up @@ -152,34 +152,34 @@ axe.configure({
#### Parameters

* `configurationOptions` - Options object; where the valid name, value pairs are:
* `branding` - mixed(optional) Used to set the branding of the helpUrls
* `brand` - string(optional) sets the brand string - default "axe"
* `application` - string(optional) sets the application string - default "axeAPI"
* `reporter` - Used to set the output format that the axe.run function will pass to the callback function
* `v1` to use the previous version's format: `axe.configure({ reporter: "v1" });`
* `v2` to use the current version's format: `axe.configure({ reporter: "v2" });`
* `checks` - Used to add checks to the list of checks used by rules, or to override the properties of existing checks
* The checks attribute is an array of check objects
* Each check object can contain the following attributes
* `id` - string(required). This uniquely identifies the check. If the check already exists, this will result in any supplied check properties being overridden. The properties below that are marked required if new are optional when the check is being overridden.
* `evaluate` - function(required for new). This is the function that implements the check's functionality.
* `after` - function(optional). This is the function that gets called for checks that operate on a page-level basis, to process the results from the iframes.
* `options` - mixed(optional). This is the options structure that is passed to the evaluate function and is intended to be used to configure checks. It is the most common property that is intended to be overridden for existing checks.
* `enabled` - boolean(optional, default `true`). This is used to indicate whether the check is on or off by default. Checks that are off are not evaluated, even when included in a rule. Overriding this is a common way to disable a particular check across multiple rules.
* `rules` - Used to add rules to the existing set of rules, or to override the properties of existing rules
* The rules attribute is an Array of rule objects
* each rule object can contain the following attributes
* `id` - string(required). This uniquely identifies the rule. If the rule already exists, it will be overridden with any of the attributes supplied. The attributes below that are marked required, are only required for new rules.
* `selector` - string(optional, default `*`). A CSS selector used to identify the elements that are passed into the rule for evaluation.
* `excludeHidden` - boolean(optional, default `true`). This indicates whether elements that are hidden from all users are to be passed into the rule for evaluation.
* `enabled` - boolean(optional, default `true`). Whether the rule is turned on. This is a common attribute for overriding.
* `pageLevel` - boolean(optional, default `false`). When set to true, this rule is only applied when the entire page is tested. Results from nodes on different frames are combined into a single result. See [page level rules](#page-level-rules).
* `any` - array(optional, default `[]`). This is the list of checks that must all "pass" or else there is a violation.
* `all` - array(optional, default `[]`). This is the list of checks that, if any "fails", will generate a violation.
* `none` - array(optional, default `[]`). This is a list of the checks that, if none "pass", will generate a violation.
* `tags` - array(optional, default `[]`). A list if the tags that "classify" the rule. In practice, you must supply some valid tags or the default evaluation will not invoke the rule. The convention is to include the standard (WCAG 2 and/or section 508), the WCAG 2 level, Section 508 paragraph, and the WCAG 2 success criteria. Tags are constructed by converting all letters to lower case, removing spaces and periods and concatinating the result. E.g. WCAG 2 A success criteria 1.1.1 would become ["wcag2a", "wcag111"]
* `matches` - string(optional, default `*`). A filtering CSS selector that will exclude elements that do not match the CSS selector.
* `disableOtherRules` - Disables all rules not included in the `rules` property.
* `branding` - mixed(optional) Used to set the branding of the helpUrls
* `brand` - string(optional) sets the brand string - default "axe"
* `application` - string(optional) sets the application string - default "axeAPI"
* `reporter` - Used to set the output format that the axe.run function will pass to the callback function
* `v1` to use the previous version's format: `axe.configure({ reporter: "v1" });`
* `v2` to use the current version's format: `axe.configure({ reporter: "v2" });`
* `checks` - Used to add checks to the list of checks used by rules, or to override the properties of existing checks
* The checks attribute is an array of check objects
* Each check object can contain the following attributes
* `id` - string(required). This uniquely identifies the check. If the check already exists, this will result in any supplied check properties being overridden. The properties below that are marked required if new are optional when the check is being overridden.
* `evaluate` - function(required for new). This is the function that implements the check's functionality.
* `after` - function(optional). This is the function that gets called for checks that operate on a page-level basis, to process the results from the iframes.
* `options` - mixed(optional). This is the options structure that is passed to the evaluate function and is intended to be used to configure checks. It is the most common property that is intended to be overridden for existing checks.
* `enabled` - boolean(optional, default `true`). This is used to indicate whether the check is on or off by default. Checks that are off are not evaluated, even when included in a rule. Overriding this is a common way to disable a particular check across multiple rules.
* `rules` - Used to add rules to the existing set of rules, or to override the properties of existing rules
* The rules attribute is an Array of rule objects
* each rule object can contain the following attributes
* `id` - string(required). This uniquely identifies the rule. If the rule already exists, it will be overridden with any of the attributes supplied. The attributes below that are marked required, are only required for new rules.
* `selector` - string(optional, default `*`). A CSS selector used to identify the elements that are passed into the rule for evaluation.
* `excludeHidden` - boolean(optional, default `true`). This indicates whether elements that are hidden from all users are to be passed into the rule for evaluation.
* `enabled` - boolean(optional, default `true`). Whether the rule is turned on. This is a common attribute for overriding.
* `pageLevel` - boolean(optional, default `false`). When set to true, this rule is only applied when the entire page is tested. Results from nodes on different frames are combined into a single result. See [page level rules](#page-level-rules).
* `any` - array(optional, default `[]`). This is the list of checks that must all "pass" or else there is a violation.
* `all` - array(optional, default `[]`). This is the list of checks that, if any "fails", will generate a violation.
* `none` - array(optional, default `[]`). This is a list of the checks that, if none "pass", will generate a violation.
* `tags` - array(optional, default `[]`). A list if the tags that "classify" the rule. In practice, you must supply some valid tags or the default evaluation will not invoke the rule. The convention is to include the standard (WCAG 2 and/or section 508), the WCAG 2 level, Section 508 paragraph, and the WCAG 2 success criteria. Tags are constructed by converting all letters to lower case, removing spaces and periods and concatinating the result. E.g. WCAG 2 A success criteria 1.1.1 would become ["wcag2a", "wcag111"]
* `matches` - string(optional, default `*`). A filtering CSS selector that will exclude elements that do not match the CSS selector.
* `disableOtherRules` - Disables all rules not included in the `rules` property.

**Returns:** Nothing

Expand Down Expand Up @@ -255,10 +255,10 @@ The include exclude object is a JSON object with two attributes: include and exc

* A node, or
* An array of arrays of CSS selectors
* If the nested array contains a single string, that string is the CSS selector
* If the nested array contains multiple strings
* The last string is the final CSS selector
* All other's are the nested structure of iframes inside the document
* If the nested array contains a single string, that string is the CSS selector
* If the nested array contains multiple strings
* The last string is the final CSS selector
* All other's are the nested structure of iframes inside the document

In most cases, the component arrays will contain only one CSS selector. Multiple CSS selectors are only required if you want to include or exclude regions of a page that are inside iframes (or iframes within iframes within iframes). In this case, the first n-1 selectors are selectors that select the iframe(s) and the nth selector, selects the region(s) within the iframe.

Expand All @@ -268,53 +268,53 @@ In most cases, the component arrays will contain only one CSS selector. Multiple

```javascript
{
include: $fixture[0],
exclude: $fixture[0].firstChild
include: $fixture[0],
exclude: $fixture[0].firstChild
}
```
2. Include the element with the ID of `fix` but exclude any `div`s within it

```javascript
{
include: [['#fix']],
exclude: [['#fix div']]
include: [['#fix']],
exclude: [['#fix div']]
}
```
3. Include the whole document except any structures whose parent contains the class `exclude1` or `exclude2`

```javascript
{
exclude: [['.exclude1'], ['.exclude2']]
exclude: [['.exclude1'], ['.exclude2']]
}
```
4. Include the element with the ID of `fix`, within the iframe with id `frame`

```javascript
{
include: [['#frame', '#fix']]
}
```
```javascript
{
include: [['#frame', '#fix']]
}
```
5. Include the element with the ID of `fix`, within the iframe with id `frame2`, within the iframe with id `frame1`

```javascript
{
include: [['#frame1', '#frame2', '#fix']]
}
```
```javascript
{
include: [['#frame1', '#frame2', '#fix']]
}
```
6. Include the following:
* The element with the ID of `fix`, within the iframe with id `frame2`, within the iframe with id `frame1`
* The element with id `header`
* All links
* The element with the ID of `fix`, within the iframe with id `frame2`, within the iframe with id `frame1`
* The element with id `header`
* All links

```javascript
{
include: [
['#header'],
['a'],
['#frame1', '#frame2', '#fix']
]
}
```
```javascript
{
include: [
['#header'],
['a'],
['#frame1', '#frame2', '#fix']
]
}
```


##### Options Parameter
Expand Down Expand Up @@ -358,9 +358,9 @@ Additionally, there are a number or properties that allow configuration of diffe

```javascript
{
runOnly: {
type: "tag",
values: ["wcag2a"]
runOnly: {
type: "tag",
values: ["wcag2a"]
}
}
```
Expand All @@ -369,10 +369,18 @@ Additionally, there are a number or properties that allow configuration of diffe

```javascript
{
runOnly: {
type: "tag",
values: ["wcag2a", "wcag2aa"]
}
runOnly: {
type: "tag",
values: ["wcag2a", "wcag2aa"]
}
}
```

Alternatively, runOnly can be passed an array of tags:

```javascript
{
runOnly: ["wcag2a", "wcag2aa"]
}
```

Expand All @@ -382,10 +390,10 @@ Additionally, there are a number or properties that allow configuration of diffe

```javascript
{
runOnly: {
type: "rule",
values: [ "ruleId1", "ruleId2", "ruleId3" ]
}
runOnly: {
type: "rule",
values: [ "ruleId1", "ruleId2", "ruleId3" ]
}
}
```

Expand All @@ -396,10 +404,10 @@ Additionally, there are a number or properties that allow configuration of diffe
The default operation for axe.run is to run all WCAG 2.0 Level A and Level AA rules. If certain rules should be disabled from being run, specify `options` as:
```javascript
{
"rules": {
"color-contrast": { enabled: false },
"valid-lang": { enabled: false }
}
"rules": {
"color-contrast": { enabled: false },
"valid-lang": { enabled: false }
}
}
```

Expand All @@ -410,14 +418,14 @@ Additionally, there are a number or properties that allow configuration of diffe
By combining runOnly with type: tags and the rules option, a modified set can be defined. This lets you include rules with unspecified tags, and exclude rules that do have the specified tag(s).
```javascript
{
runOnly: {
type: "tag",
values: ["wcag2a"]
},
"rules": {
"color-contrast": { enabled: true },
"valid-lang": { enabled: false }
}
runOnly: {
type: "tag",
values: ["wcag2a"]
},
"rules": {
"color-contrast": { enabled: true },
"valid-lang": { enabled: false }
}
}
```

Expand All @@ -428,13 +436,13 @@ Additionally, there are a number or properties that allow configuration of diffe
Similar to scope, the runOnly option can accept an object with an 'include' and 'exclude' property. Only those checks that match an included tag will run, except those that share a tag from the exclude list.
```javascript
{
runOnly: {
type: 'tags',
values: {
include: ['wcag2a', 'wcag2aa'],
exclude: ['experimental']
}
}
runOnly: {
type: 'tags',
values: {
include: ['wcag2a', 'wcag2aa'],
exclude: ['experimental']
}
}
}
```

Expand Down Expand Up @@ -524,33 +532,33 @@ In this example, we will pass the selector for the entire document, pass no opti

```javascript
axe.run(document, function(err, results) {
if (err) throw err;
console.log(results);
if (err) throw err;
console.log(results);
});
```

###### `passes`

* `passes[0]`
...
* `help` - `"Elements must have sufficient color contrast"`
* `helpUrl` - `"https://dequeuniversity.com/courses/html-css/visual-layout/color-contrast"`
* `id` - `"color-contrast"`
* `nodes`
* `target[0]` - `"#js_off-canvas-wrap > .inner-wrap >.kinja-title.proxima.js_kinja-title-desktop"`
...
* `help` - `"Elements must have sufficient color contrast"`
* `helpUrl` - `"https://dequeuniversity.com/courses/html-css/visual-layout/color-contrast"`
* `id` - `"color-contrast"`
* `nodes`
* `target[0]` - `"#js_off-canvas-wrap > .inner-wrap >.kinja-title.proxima.js_kinja-title-desktop"`

* `passes[1]`
...
...

###### `violations`

* `violations[0]`
* `help` - `"<button> elements must have alternate text"`
* `helpUrl` - `"https://dequeuniversity.com/courses/html-css/forms/form-labels#id84_example_button"`
* `id` - `"button-name"`
* `nodes`
* `target[0]` - `"post_5919997 > .row.content-wrapper > .column > span > iframe"`
* `target[1]` - `"#u_0_1 > .pluginConnectButton > .pluginButtonImage > button"`
* `help` - `"<button> elements must have alternate text"`
* `helpUrl` - `"https://dequeuniversity.com/courses/html-css/forms/form-labels#id84_example_button"`
* `id` - `"button-name"`
* `nodes`
* `target[0]` - `"post_5919997 > .row.content-wrapper > .column > span > iframe"`
* `target[1]` - `"#u_0_1 > .pluginConnectButton > .pluginButtonImage > button"`

* `violations[1]` ...

Expand Down Expand Up @@ -580,13 +588,13 @@ In this example, we pass the selector for the entire document, enable two additi

```javascript
axe.run(document, {
rules: {
"heading-order": { enabled: true },
"label-title-only": { enabled: true }
}
rules: {
"heading-order": { enabled: true },
"label-title-only": { enabled: true }
}
}, function(err, results) {
if (err) throw err;
console.log(results);
if (err) throw err;
console.log(results);
});
```

Expand Down Expand Up @@ -622,7 +630,7 @@ Call each plugin's cleanup function. See [implementing a plugin](plugins.md).
The signature is:

```
axe.cleanup(resolve, reject)
axe.cleanup(resolve, reject)
```

`resolve` and `reject` are functions that will be invoked on success or failure respectively.
Expand Down Expand Up @@ -737,7 +745,7 @@ An approach you can take to reducing the time is use the `resultTypes` option. B

```
{
resultTypes: ['violations']
resultTypes: ['violations']
}
```

Expand Down
Loading

0 comments on commit dc0241b

Please sign in to comment.