Skip to content

Latest commit

 

History

History
73 lines (49 loc) · 4.66 KB

RulesOverview.md

File metadata and controls

73 lines (49 loc) · 4.66 KB
Raw
 ## Rules

Rules are the automated accessibility tests run by Axe.Windows. Each rule is independent of any other and contains all information about itself.

For an overview of the Rules projects, please see the "Accessibility rules" section in Overview of Axe.Windows

Anatomy of a rule

Rules have three basic components

  • RuleInfo
    • ID: a unique value from the RuleId enumeration (used for telemetry and for rules to be run individually)
    • Description: a short description (fewer than 80 characters) of the standards violation (e.g., "The Name property must not be null")
    • HowToFix: an in-depth description of the standards violation and suggested remediation(s)
    • Standard: a value from the A11yCriteriaId enumeration which maps the given rule to a documented standard
    • ErrorCode: an EvaluationCode that reflects the severity of failures of this rule
    • PropertyID: an optional property id (e.g., PropertyType.UIA_ControlTypePropertyId) used to link a rule to a property-platform-based snippet with extended information about the rule
    • FrameworkIssueLink: an optional URL that exists only for rules which fail due to known framework issues. The referenced page provides more detailed information about how to investigate or resolve this issue
  • Condition: a Condition object which determines under what circumstances the rule is run (see below)
  • PassesTest: a method which determines if the test passes or is in violation of a standard

Values for RuleInfo.ErrorCode

The RuleInfo.ErrorCode must be set to one of the following supported values:

EvaluationCode Description
Error if the violation represents an unambiguous accessibility issue and can be conclusively determined by the tool
Warning if the violation represents an unambiguous accessibility issue but cannot be conclusively determined by the tool
NeedsReview if the violation highlights possible accessibility issues that need to be reviewed and verified by a human

Inheritance

All rules must inherit from the Axe.Windows.Rules.Rule base class. Rules are discovered through reflection; when your class inherits from Rule, it is added to the set of rules tested by Axe.Windows.

Conventions

One test per rule

A rule represents a single, self-contained test. For example, NameIsNotNull, NameIsNotEmpty, and NameIsNotWhiteSpace all test the value of the Name property in similar ways; but they are split into separate rules. This increases the specificity of the feedback given to the user and makes it possible to change the evaluation code or applicability (Condition) of each rule individually without unintentionally affecting other rules.

The PassesTest method

The PassesTest method of a rule returns false only when a violation of a standard is identified. When this occurs, the severity indicated by RuleInfo.ErrorCode will be reflected in the accessibility test results.

Use conditions in the PassesTest method

Using conditions (described below) makes it possible to represent the evaluation logic both as code and as a string that can be understood by a user. Please see the "Future" section of this document for more details.

Conditions

Conditions are classses used to represent the properties, patterns, and values of an element in a grammatical form that is reusable, self-describing, and easy to read. All conditions must inherit from the Axe.Windows.Rules.Condition base class. Conditions have the following features:

  • A condition evaluates to true or false via its Matches method.
  • A condition has an associated text description. Descriptions can be assigned via the index operator, e.g., Button["Button"]
  • Conditions can be combined using operators:
operator description example
& logical and Button & Name.IsNotEmpty
| logical or Button & Checkbox
~ unary logical not ~IsContentElement
- binary logical not Button - IsKeyboardFocusable
/ hierarchical relationship parent / child

When conditions are combined using operators, so too are there associated descriptions, e.g., (Button & IsKeyboardFocusable) = "Button and IsKeyboardFocusable". Using this mechanism, all conditions can be written as text strings and used as documentation for the rules.

There are many ready-made conditions you can use from the Axe.Windows.Rules.PropertyConditions namespace.

Rule documentation file

All PR's that modify rules should update the docs/RulesDescription.md file. This file is auto-generated by the tool built in the RulesMD project.