Using Custom Rules

Overview of Custom Rules in the axe Expert extension

When you want to have the axe Expert tool analyze web pages and applications against rules that are specific to your organization's unique needs, it is possible to do so with the Custom Rules functionality on the Rules panel. Clicking the Rules link item in the axe Expert main menu (drop-down near the axe Expert Extension logo at top of left pane) causes a Rules panel to appear that offers an Add custom ruleset button for displaying a form on the right pane for submitting a set of custom rules. The simple form consists of two text entry fields and an action button that allow you to set up custom rules that can be selected for running in the automated engine when a loaded page is analyzed on the Analyze panel.

Just like analyzing a page with the axe Expert rulesets, results will display any violations of your custom rules that are found, along with the information you specified in the custom ruleset (Target, HTML source, remediation Summary, More Info help link, etc.). All of the other action options available with standard rules also apply to your custom rule violations (Inspect, Highlight, Export, Upload, etc.). There is a limit of five custom rulesets that are permitted at one time.

1. Add a ruleset button: In the Custom rulesets section of left pane of Rules panel, an +Add a ruleset command presents you with a form in the right pane for submitting a custom set of rules.
2. Name for Custom Rules (alphanumeric only): This will be the name of the ruleset that will appear in the Standards section of the Settings tab. It is important to both follow the conventions (alphanumeric, no spaces) and ensure the name will be meaningful and easily recognizable as a selection option.
3. Enter JSON rules.textareaInstructions: JavaScript Object Notation (JSON) is the text-based standard to which the content must conform to work with Firefox's HTML 2.0 browser extension. For more information, see the Example below.
4. SAVE AND USE RULESET button: Causes the custom rules to become a selectable option in the left sidebar pane menu of the Rules panel. For more information, see Select a Ruleset.

Custom Rule Example

The sample code that follows can serve as a working example of a properly formatted axe Expert Custom Rule JSON file.

{
  "checks": [
    {
      "id": "test",
      "options": ["test"],
      "evaluate": "function() { return false; }",
      "metadata": {
        "impact": "minor",
        "messages": {
          "pass": "how did you pass",
          "fail": "there is no way to pass"
        }
      }
    }
  ],
  "rules": [
    {
      "id": "test",
      "metadata": {
        "description": "Will always fail",
        "help": "There is no way to make this pass! It is for testing",
        "helpUrl": "https://foo.com/bar"
      },
      "selector": "html",
      "any": [],
      "all": ["test"],
      "none": [],
      "tags": ["wcag2aa"]
    }
  ]
}

Custom Rulesets from axe Monitor Projects: After signing in to axe Monitor and selecting a project, any custom rulesets associated with that project are automatically loaded into the Rules panel and made available for selection.

Submit custom rules

When you want to submit custom rules for future use into the axe Expert Extension, follow these simple steps. Submitting custom rules is done by specifying a name for the ruleset for future selection purposes, and pasting in the properly formatted JSON text file content into text entry fields, then clicking a button to save and use them.

To submit custom rules:

1. Open DevTools and select axe Expert. Select Rules from the main axe Expert menu.

2. In the left pane, select + Add a ruleset in the Custom Rulesets section of the menu. The Ruleset form displays in the right pane.

3. In the Name of Custom Rules field, enter the desired alphanumeric name with no spaces, as desired.

   This will appear in the Custom Rulesets section of the left pane of the Rules panel, so the name should be meaningful and easily recognizable for selection.

4. In the Enter JSON field, paste in the content of your custom rules .json text file from the virtual clipboard. Grab and drag the lower, right corner of the field to increase the viewable area, if desired.

5. Select SAVE AND USE RULESET.

   

   The name you entered appears in the Custom rulesets section in the left pane, and it appears at the top of the right pane, in the Ruleset: field. Additionally, buttons to either delete or use the ruleset appear at the bottom of the form in the right pane.

   In the right pane, select Analyze now.

   

   The custom ruleset name appears in the left sidebar Rules menu preceded by a checkmark to indicate it is the currently selected ruleset that will be used when performing analysis.

Analyze a page for Accessibility Rule Violations

Initiating an accessibility analysis in the axe Expert Extension is done by navigating to the Analyze panel and then clicking the Analyze button. The analysis process produces a message indicating the total number of accessibility rule violations found on the page, as well as a results section displaying identified rules violations and the total number of violations identified. Activating a row in the left results pane displays details in the main content pane to the right. This action also initializes the violation Previous and Next arrow buttons to appear at the top of the content pane allowing you to navigate from one violation to the next for any selected rule.

Analyze a page for rule violations:

1. With the axe Expert tab selected, select Analyze on the main menu on the left pane to the right of the axe Expert Extension logo. The Analyze panel appears.

2. In the content pane, activate ANALYZE. Depending on how you've docked the developer tools or resized your browser window, this is typically in the center of the left pane of the Analyze panel.

   The Analyze pane may temporarily display a status message that reads Analyzing...please wait until the analysis of the page against the selected ruleset is complete.

   Under the axe Expert Extension logo, the total number of violations found is displayed, along with the number of issues requiring manual review. Additionally, a show drop-down context menu and Run again link display to the right of the total counts. A two-column table displaying the short name of each rule with the right column displaying the number of violations found of each displays under the show drop-down context menu.

   

3. In the rules violated section (left pane), click on a rule row.

   

   The content pane at right is refreshed to display the first violation of that rule. Included in the content display are the Target, HTML, and Summary (How to Fix the Problem) sections of information, along with Inspect and Highlight links, a context menu (which includes options for Export, Scope, Upload and Download), and at the bottom, right a left-expanding arrow button to show the applicable Standards (rulesets) for the selected rule. For more detailed information about each component displayed in the rule violation content pane, refer to the descriptions in the overview provided in the Analyze topic. Violation navigation previous < and next > buttons appear at the top of the pane allowing you to navigate between the violations for the selected rule. Additionally, the relevant HTML containing the violation is automatically highlighted on the tested page.

4. Click Next (>) to navigate to the next violation of the currently selected rule, or select a different rule from the left violated rule results pane, as desired.

   

Remove a custom ruleset

Remove a Custom Ruleset from the Rules panel when you no longer need a set of custom rules. Select the rule to delete on the Rules panel and click a button to delete.

If you might want to re-use some of the content in a future custom ruleset, you may want to be sure you save the content from the JSON file prior to deletion, as this procedure results in a permanent, irreversible removal.

To remove a custom ruleset:

1. At the bottom of the options list in the Custom rulesets section in the left pane of the Rules panel, ensure the set you want to remove is checked (selected).
2. Click DELETE RULESET.

The set is removed from the left pane menu and is no longer available for selection.