Linting

client/src/includes/a11y-result.ts

@@ -73,7 +73,9 @@ export const getAxeConfiguration = (
 };
 
 /**
- * Custom rule for checking image alt text. Will be added via the Axe.configure() API
+ * Custom rule for checking image alt text. This rule checks if the alt text for images
+ * contains file extensions or URLs, which are considered poor quality alt text.
+ * The rule will be added via the Axe.configure() API.
  * https://github.com/dequelabs/axe-core/blob/master/doc/API.md#api-name-axeconfigure
  */
 export const checkImageAltText = (node: Element) => {
@@ -106,14 +108,16 @@ export const checkImageAltText = (node: Element) => {
 
 /**
  * Defines custom Axe rules, mapping each check to its corresponding JavaScript function.
+ * This object holds the custom checks that will be added to the Axe configuration.
  */
 const customChecks = {
   'check-image-alt-text': checkImageAltText,
   // Add other custom checks here
 };
 
 /**
- * Configures custom Axe rules.
+ * Configures custom Axe rules by integrating the custom checks with their corresponding
+ * JavaScript functions. It modifies the provided configuration to include these checks.
  */
 const addCustomChecks = (customConfig: Spec): Spec => {
   const modifiedChecks = customConfig?.checks?.map((check) => {
@@ -125,7 +129,6 @@ const addCustomChecks = (customConfig: Spec): Spec => {
     }
     return check;
   });
-
   return {
     ...customConfig,
     checks: modifiedChecks,
@@ -139,23 +142,25 @@ interface A11yReport {
 
 /**
  * Get accessibility testing results from Axe based on the configurable custom checks, context, and options.
+ * It integrates custom rules into the Axe configuration before running the tests.
  */
 export const getA11yReport = async (
   config: WagtailAxeConfiguration,
 ): Promise<A11yReport> => {
-  // Add custom checks for Axe if any. 'check-image-alt-text' is enabled by default
-  if (config.custom && config.custom.checks && config.custom.rules) {
-    axe.configure(addCustomChecks(config.custom));
+  let customConfig = config.custom;
+  // Apply custom configuration for Axe. Custom 'check-image-alt-text' is enabled by default
+  if (customConfig) {
+    if (customConfig.checks) {
+      customConfig = addCustomChecks(customConfig);
+    }
+    axe.configure(customConfig);
   }
-
   // Initialise Axe based on the context (whole page body by default) and options ('button-name', empty-heading', 'empty-table-header', 'frame-title', 'heading-order', 'input-button-name', 'link-name', 'p-as-heading', and a custom 'alt-text-quality' rules by default)
   const results = await axe.run(config.context, config.options);
-
   const a11yErrorsNumber = results.violations.reduce(
     (sum, violation) => sum + violation.nodes.length,
     0,
   );
-
   return {
     results,
     a11yErrorsNumber,

wagtail/admin/userbar.py

@@ -63,25 +63,35 @@ class AccessibilityItem(BaseItem):
     #: For more details, see `Axe documentation <https://github.com/dequelabs/axe-core/blob/master/doc/API.md#options-parameter-examples>`__.
     axe_rules = {}
 
-    # Spec object for axe.configure()
-    # If a rule is added, it's enabled by default, unless specificed "enabled: False"
-    axe_custom_rules = {
-        "checks": [
-            {
-                "id": "check-image-alt-text",
-            }
-        ],
-        "rules": [
-            {
-                "id": "alt-text-quality",
-                "impact": "serious",
-                "selector": "img[alt]",
-                "tags": ["best-practice"],
-                "any": ["check-image-alt-text"],
-                "enabled": True,  # Defaults to True
-            }
-        ],
-    }
+    #: A list used to add custom rules to the existing set of Axe rules, or to override the properties of existing Axe rules
+    #: For more details, see `Axe documentation <https://github.com/dequelabs/axe-core/blob/master/doc/API.md#api-name-axeconfigure>`__.
+    axe_custom_rules = []
+
+    #: A custom rule to check the quality of the Images alt texts. Added to the list of custom rules and enabled by default.
+    #: Should be used in conjunction with :attr:`_axe_custom_alt_text_check`
+    #: This rule ensures that alt texts doesn't contain antipatterns like file extensions. Returns zero false positives.
+    _axe_custom_alt_text_rule = [
+        {
+            "id": "alt-text-quality",
+            "impact": "serious",
+            "selector": "img[alt]",
+            "tags": ["best-practice"],
+            "any": ["check-image-alt-text"],
+            "enabled": True,  # If ommited, defaults to True
+        }
+    ]
+
+    #: A list used to add custom checks to the existing set of Axe checks, or to override the properties of existing Axe checks
+    #: For more details, see `Axe documentation <https://github.com/dequelabs/axe-core/blob/master/doc/API.md#api-name-axeconfigure>`__.
+    axe_custom_checks = []
+
+    #: A custom check for the custom Image alt text quality rule. Added to the list of custom checks and enabled by default.
+    #: Should be used in conjunction with :attr:`_axe_custom_alt_text_rule`
+    _axe_custom_alt_text_check = [
+        {
+            "id": "check-image-alt-text",
+        }
+    ]
 
     #: A dictionary that maps axe-core rule IDs to custom translatable strings
     #: to use as the error messages. If an enabled rule does not exist in this
@@ -129,8 +139,24 @@ def get_axe_rules(self, request):
         return self.axe_rules
 
     def get_axe_custom_rules(self, request):
-        """Returns if the custom 'Image alt text quality' rule is enabled."""
-        return self.axe_custom_rules
+        """Returns TODO return nothing if empty both rules and checks"""
+        return self.axe_custom_rules + self._axe_custom_alt_text_rule
+
+    def get_axe_custom_checks(self, request):
+        """Returns TODO return nothing if empty both rules and checks"""
+        return self.axe_custom_checks + self._axe_custom_alt_text_check
+
+    def get_axe_custom_config(self, request):
+        """Returns TODO return nothing if empty both rules and checks"""
+        custom_config = {
+            "rules": self.get_axe_custom_rules(request),
+            "checks": self.get_axe_custom_checks(request),
+        }
+
+        # If both the lists of custom rules and custom checks are empty, no custom configuration should be applied for Axe
+        if not custom_config["rules"] and not custom_config["checks"]:
+            custom_config = ""
+        return custom_config
 
     def get_axe_messages(self, request):
         """Returns a dictionary that maps axe-core rule IDs to custom translatable strings."""
@@ -171,7 +197,7 @@ def get_axe_configuration(self, request):
             "context": self.get_axe_context(request),
             "options": self.get_axe_options(request),
             "messages": self.get_axe_messages(request),
-            "custom": self.get_axe_custom_rules(request),
+            "custom": self.get_axe_custom_config(request),
         }
 
     def get_context_data(self, request):