testaro 26.5.0 → 27.0.1

package/CONTRIBUTING.md

@@ -82,15 +82,16 @@ You can copy and revise any of the existing JSON files in the `testaro` director
 - Assign an integer from 0 through 3 to `ordinalSeverity`.
 - If all instances of violations of the rule necessarily involve elements of the same type, assign its tag name (such as `"BUTTON"`) to `summaryTagName`.
 
+### Simplifiable rules
+
+More complex Testaro rules are implemented in JavaScript. Some rules are _simplifiable_. These can be implemented with JavaScript modules like the one for the `allSlanted` rule. To implement such a rule, you can copy an existing module and replace the 7 values of the `ruleData` object. The significant decisions here are about the values of the `selector` and `pruner` properties.
+
+The `selector` value is a CSS selector that identifies candidate elements for violation reporting. What makes this rule simplifiable, instead of simple, is that these elements may or may not be determined to violate the rule. Each of the elements identified by the selector must be further analyzed by the pruner. The pruner takes a Playwright locator as its argument and returns `true` if it finds that the element located by the locator violates the rule, or `false` if not.
+
+The `isDestructive` property should be set to `true` if your pruner modifies the page. Any pruner that calls the `isOperable()` function from the `operable` module does so.
+
 ### Complex rules
 
-More complex Testaro rules are implemented in JavaScript. You can use any of the existing JavaScript rules, or `data/template.js` file, as an example to begin with. Examples include:
-- `allSlanted`, `distortion`, `filter`, `lineHeight`, `miniText`, `zIndex`: violations based on element styles.
-- `focOp`, `opFoc`, `targetSize`: violations based on attributes
-- `linkTitle`: violations based on attributes and text content.
-- `linkAmb`, `pseudoP`, `radioSet`: violations based on relations among elements and text.
-- `hover`, `tabNav`: violations based on performing actions and observing page behavior.
-- `role`: violations based on data about standards.
-- `docType`, `title`: violations based on page properties.
+Even more complex Testaro rules require analysis that cannot fit into the simple or simplifiable category. You can begin with existing JavaScript rules, or the `data/template.js` file, as an example.
 
-Some utility functions in modules in the `procs` directory are available for support of new rules.
+Some utility functions in modules in the `procs` directory are available for support of new rules. Among these modules are `testaro` (used in many tests), `isInlineLink`, `operable`, and `visChange`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "testaro",
-  "version": "26.5.0",
+  "version": "27.0.1",
   "description": "Run 650 web accessibility tests from 8 tools and get a standardized report",
   "main": "index.js",
   "scripts": {

package/procs/testaro.js

@@ -14,7 +14,7 @@ const sampleMax = 100;
 // ########## FUNCTIONS
 
 // Initializes locators and a result.
-exports.init = async (page, locAllSelector, options = {}) => {
+const init = async (page, locAllSelector, options = {}) => {
   // Get locators for the specified elements.
   const locPop = page.locator(locAllSelector, options);
   const locPops = await locPop.all();
@@ -40,7 +40,7 @@ exports.init = async (page, locAllSelector, options = {}) => {
 };
 
 // Populates a result.
-exports.report = async (withItems, all, ruleID, whats, ordinalSeverity, tagName = '') => {
+const report = async (withItems, all, ruleID, whats, ordinalSeverity, tagName = '') => {
   const {locs, result} = all;
   const {data, totals, standardInstances} = result;
   // For each instance locator:
@@ -92,3 +92,41 @@ exports.report = async (withItems, all, ruleID, whats, ordinalSeverity, tagName
   // Return the result.
   return result;
 };
+// Performs a simplifiable test.
+const simplify = async (page, withItems, ruleData) => {
+  const {
+    ruleID, selector, pruner, isDestructive, complaints, ordinalSeverity, summaryTagName
+  } = ruleData;
+  // Initialize the locators and result.
+  const all = await init(page, selector);
+  // For each locator:
+  for (const loc of all.allLocs) {
+    // Get whether its element violates the rule.
+    const isBad = await pruner(loc);
+    // If it does:
+    if (isBad) {
+      // Add the locator to the array of violators.
+      all.locs.push(loc);
+    }
+  }
+  // Populate and return the result.
+  const whats = [
+    complaints.instance,
+    complaints.summary
+  ];
+  const testReport = await report(withItems, all, ruleID, whats, ordinalSeverity, summaryTagName);
+  // If the pruner modifies the page:
+  if (isDestructive) {
+    // Reload the page.
+    try {
+      await page.reload({timeout: 15000});
+    }
+    catch(error) {
+      console.log('ERROR: page reload timed out');
+    }
+  }
+  return testReport;
+};
+exports.init = init;
+exports.report = report;
+exports.simplify = simplify;

package/testaro/allCaps.js

@@ -8,18 +8,17 @@
 // ########## IMPORTS
 
 // Module to perform common operations.
-const {init, report} = require('../procs/testaro');
+const {simplify} = require('../procs/testaro');
 
 // ########## FUNCTIONS
 
 // Runs the test and returns the result.
 exports.reporter = async (page, withItems) => {
-  // Initialize the locators and result.
-  const all = await init(page, 'body *:not(style, script, svg)');
-  // For each locator:
-  for (const loc of all.allLocs) {
-    // Get whether its element violates the rule.
-    const isBad = await loc.evaluate(el => {
+  // Specify the rule.
+  const ruleData = {
+    ruleID: 'allCaps',
+    selector: 'body *:not(style, script, svg)',
+    pruner: async loc => await loc.evaluate(el => {
       const elText = Array
       .from(el.childNodes)
       .filter(node => node.nodeType === Node.TEXT_NODE)
@@ -37,14 +36,15 @@ exports.reporter = async (page, withItems) => {
         const transformStyle = elStyleDec.textTransform;
         return transformStyle === 'uppercase' && elText.length > 7;
       }
-    });
-    // If it does:
-    if (isBad) {
-      // Add the locator to the array of violators.
-      all.locs.push(loc);
-    }
-  }
-  // Populate and return the result.
-  const whats = ['Element contains all-capital text', 'Elements contain all-capital text'];
-  return await report(withItems, all, 'allCaps', whats, 0);
+    }),
+    isDestructive: false,
+    complaints: {
+      instance: 'Element contains all-capital text',
+      summary: 'Elements contain all-capital text'
+    },
+    ordinalSeverity: 0,
+    summaryTagName: ''
+  };
+  // Run the test and return the result.
+  return await simplify(page, withItems, ruleData);
 };

package/testaro/allSlanted.js

@@ -8,32 +8,29 @@
 // ########## IMPORTS
 
 // Module to perform common operations.
-const {init, report} = require('../procs/testaro');
+const {simplify} = require('../procs/testaro');
 
 // ########## FUNCTIONS
 
 // Runs the test and returns the result.
 exports.reporter = async (page, withItems) => {
-  // Initialize the locators and result.
-  const all = await init(page, 'body *:not(style, script, svg)');
-  // For each locator:
-  for (const loc of all.allLocs) {
-    // Get whether its element violates the rule.
-    const isBad = await loc.evaluate(el => {
+  // Specify the rule.
+  const ruleData = {
+    ruleID: 'allSlanted',
+    selector: 'body *:not(style, script, svg)',
+    pruner: async loc => await loc.evaluate(el => {
       const elStyleDec = window.getComputedStyle(el);
       const elText = el.textContent;
       return ['italic', 'oblique'].includes(elStyleDec.fontStyle) && elText.length > 39;
-    });
-    // If it does:
-    if (isBad) {
-      // Add the locator to the array of violators.
-      all.locs.push(loc);
-    }
-  }
-  // Populate and return the result.
-  const whats = [
-    'Element contains all-italic or all-oblique text',
-    'Elements contain all-italic or all-oblique text'
-  ];
-  return await report(withItems, all, 'allSlanted', whats, 0);
+    }),
+    isDestructive: false,
+    complaints: {
+      instance: 'Element contains all-italic or all-oblique text',
+      summary: 'Elements contain all-italic or all-oblique text'
+    },
+    ordinalSeverity: 0,
+    summaryTagName: ''
+  };
+  // Run the test and return the result.
+  return await simplify(page, withItems, ruleData);
 };

package/testaro/distortion.js

@@ -8,27 +8,30 @@
 // ########## IMPORTS
 
 // Module to perform common operations.
-const {init, report} = require('../procs/testaro');
+const {simplify} = require('../procs/testaro');
 
 // ########## FUNCTIONS
 
 // Runs the test and returns the result.
 exports.reporter = async (page, withItems) => {
-  // Initialize the locators and result.
-  const all = await init(page, 'body *');
-  // Get those that have distorting transform styles.
-  for (const loc of all.allLocs) {
-    const isDistorted = await loc.evaluate(el => {
+  // Specify the rule.
+  const ruleData = {
+    ruleID: 'distortion',
+    selector: 'body *',
+    pruner: async loc => await loc.evaluate(el => {
       const styleDec = window.getComputedStyle(el);
       const {transform} = styleDec;
       return transform
       && ['matrix', 'perspective', 'rotate', 'scale', 'skew'].some(key => transform.includes(key));
-    });
-    if (isDistorted) {
-      all.locs.push(loc);
-    }
-  }
-  // Populate the result.
-  const whats = ['Element distorts its text', 'Elements distort their texts'];
-  return await report(withItems, all, 'distortion', whats, 1);
+    }),
+    isDestructive: false,
+    complaints: {
+      instance: 'Element distorts its text',
+      summary: 'Elements distort their texts'
+    },
+    ordinalSeverity: 1,
+    summaryTagName: ''
+  };
+  // Run the test and return the result.
+  return await simplify(page, withItems, ruleData);
 };

package/testaro/filter.js

@@ -9,28 +9,28 @@
 // ########## IMPORTS
 
 // Module to perform common operations.
-const {init, report} = require('../procs/testaro');
+const {simplify} = require('../procs/testaro');
 
 // ########## FUNCTIONS
 
 // Runs the test and returns the result.
 exports.reporter = async (page, withItems) => {
-  // Initialize the locators and result.
-  const all = await init(page, 'body *');
-  // For each locator:
-  for (const loc of all.allLocs) {
-    // Get whether its element violates the rule.
-    const isBad = await loc.evaluate(el => {
+  // Specify the rule.
+  const ruleData = {
+    ruleID: 'filter',
+    selector: 'body *',
+    pruner: async loc => await loc.evaluate(el => {
       const styleDec = window.getComputedStyle(el);
       return styleDec.filter !== 'none';
-    });
-    // If it does:
-    if (isBad) {
-      // Add the locator to the array of violators.
-      all.locs.push(loc);
-    }
-  }
-  // Populate and return the result.
-  const whats = ['Element has a filter style', 'Elements have filter styles'];
-  return await report(withItems, all, 'filter', whats, 2);
+    }),
+    isDestructive: false,
+    complaints: {
+      instance: 'Element has a filter style',
+      summary: 'Elements have filter styles'
+    },
+    ordinalSeverity: 2,
+    summaryTagName: ''
+  };
+  // Run the test and return the result.
+  return await simplify(page, withItems, ruleData);
 };

package/testaro/linkTitle.js

@@ -4,8 +4,10 @@
   This test reports links with title attributes whose values the link text contains.
 */
 
+// ########## IMPORTS
+
 // Module to perform common operations.
-const {init, report} = require('../procs/testaro');
+const {simplify} = require('../procs/testaro');
 // Module to get locator data.
 const {getLocatorData} = require('../procs/getLocatorData');
 
@@ -13,24 +15,23 @@ const {getLocatorData} = require('../procs/getLocatorData');
 
 // Runs the test and returns the result.
 exports.reporter = async (page, withItems) => {
-  // Initialize the locators and result.
-  const all = await init(page, 'a[title]');
-  // For each locator:
-  for (const loc of all.allLocs) {
-    // Get whether its element violates the rule.
-    const elData = await getLocatorData(loc);
-    const title = await loc.getAttribute('title');
-    const isBad = elData.excerpt.toLowerCase().includes(title.toLowerCase());
-    // If it does:
-    if (isBad) {
-      // Add the locator to the array of violators.
-      all.locs.push(loc);
-    }
-  }
-  // Populate and return the result.
-  const whats = [
-    'Link has a title attribute that repeats link text content',
-    'Links have title attributes that repeat link text contents'
-  ];
-  return await report(withItems, all, 'linkTitle', whats, 0);
+  // Specify the rule.
+  const ruleData = {
+    ruleID: 'linkTitle',
+    selector: 'a[title]',
+    pruner: async loc => {
+      const elData = await getLocatorData(loc);
+      const title = await loc.getAttribute('title');
+      return elData.excerpt.toLowerCase().includes(title.toLowerCase());
+    },
+    isDestructive: false,
+    complaints: {
+      instance: 'Link has a title attribute that repeats link text content',
+      summary: 'Links have title attributes that repeat link text contents'
+    },
+    ordinalSeverity: 0,
+    summaryTagName: 'A'
+  };
+  // Run the test and return the result.
+  return await simplify(page, withItems, ruleData);
 };

package/testaro/linkUl.js

@@ -8,8 +8,10 @@
   merely to discover which passages are links.
 */
 
+// ########## IMPORTS
+
 // Module to perform common operations.
-const {init, report} = require('../procs/testaro');
+const {simplify} = require('../procs/testaro');
 // Module to classify links.
 const {isInlineLink} = require('../procs/isInlineLink');
 
@@ -17,27 +19,30 @@ const {isInlineLink} = require('../procs/isInlineLink');
 
 // Runs the test and returns the result.
 exports.reporter = async (page, withItems) => {
-  // Initialize the locators and result.
-  const all = await init(page, 'a');
-  // For each locator:
-  for (const loc of all.allLocs) {
-    // Get whether its element is underlined.
-    const isUnderlined = await loc.evaluate(el => {
-      const styleDec = window.getComputedStyle(el);
-      return styleDec.textDecorationLine === 'underline';
-    });
-    // If it is not:
-    if (! isUnderlined) {
-      // Get whether it is inline.
-      const isInline = await isInlineLink(loc);
-      // If it is:
-      if (isInline) {
-        // Add the locator to the array of violators.
-        all.locs.push(loc);
+  // Specify the rule.
+  const ruleData = {
+    ruleID: 'linkUl',
+    selector: 'a',
+    pruner: async loc => {
+      // Get whether each link is underlined.
+      const isUnderlined = await loc.evaluate(el => {
+        const styleDec = window.getComputedStyle(el);
+        return styleDec.textDecorationLine === 'underline';
+      });
+      // If it is not:
+      if (! isUnderlined) {
+        // Return whether it is a violator.
+        return await isInlineLink(loc);
       }
-    }
-  }
-  // Populate and return the result.
-  const whats = ['Link is inline but has no underline', 'Inline links are missing underlines'];
-  return await report(withItems, all, 'linkUl', whats, 1);
+    },
+    isDestructive: false,
+    complaints: {
+      instance: 'Link is inline but has no underline',
+      summary: 'Inline links are missing underlines'
+    },
+    ordinalSeverity: 1,
+    summaryTagName: 'A'
+  };
+  // Run the test and return the result.
+  return await simplify(page, withItems, ruleData);
 };

package/testaro/nonTable.js

@@ -4,19 +4,20 @@
   This test reports tables used for layout.
 */
 
+// ########## IMPORTS
+
 // Module to perform common operations.
-const {init, report} = require('../procs/testaro');
+const {simplify} = require('../procs/testaro');
 
 // ########## FUNCTIONS
 
 // Runs the test and returns the result.
 exports.reporter = async (page, withItems) => {
-  // Initialize the locators and result.
-  const all = await init(page, 'table');
-  // For each locator:
-  for (const loc of all.allLocs) {
-    // Get whether its element violates the rule.
-    const isBad = await loc.evaluate(el => {
+  // Specify the rule.
+  const ruleData = {
+    ruleID: 'nonTable',
+    selector: 'table',
+    pruner: async loc => await loc.evaluate(el => {
       const role = el.getAttribute('role');
       // If it contains another table:
       if (el.querySelector('table')) {
@@ -54,14 +55,15 @@ exports.reporter = async (page, withItems) => {
         // Return misuse.
         return true;
       }
-    });
-    // If it does:
-    if (isBad) {
-      // Add the locator to the array of violators.
-      all.locs.push(loc);
-    }
-  }
-  // Populate and return the result.
-  const whats = ['Table is misused to arrange content', 'Tables are misused to arrange content'];
-  return await report(withItems, all, 'nonTable', whats, 2, 'TABLE');
+    }),
+    isDestructive: false,
+    complaints: {
+      instance: 'Table is misused to arrange content',
+      summary: 'Tables are misused to arrange content'
+    },
+    ordinalSeverity: 2,
+    summaryTagName: 'TABLE'
+  };
+  // Run the test and return the result.
+  return await simplify(page, withItems, ruleData);
 };

package/validation/tests/jobs/adbID.json

@@ -66,16 +66,6 @@
           "=",
           "the World Wide Web"
         ],
-        [
-          "standardResult.instances.1.excerpt",
-          "=",
-          "Never"
-        ],
-        [
-          "standardResult.instances.2.excerpt",
-          "=",
-          "accessible"
-        ],
         [
           "standardResult.instances.1.tagName",
           "=",

package/validation/tests/jobs/linkTitle.json

@@ -112,6 +112,11 @@
           "standardResult.instances.0.what",
           "i",
           "Links have"
+        ],
+        [
+          "standardResult.instances.0.tagName",
+          "=",
+          "A"
         ]
       ],
       "rules": [

package/validation/tests/jobs/linkUl.json

@@ -170,6 +170,63 @@
         "y",
         "linkUl"
       ]
+    },
+    {
+      "type": "test",
+      "which": "testaro",
+      "withItems": false,
+      "stopOnFail": true,
+      "expect": [
+        [
+          "standardResult.totals.1",
+          "=",
+          6
+        ],
+        [
+          "standardResult.totals.2",
+          "=",
+          0
+        ],
+        [
+          "standardResult.instances.length",
+          "=",
+          1
+        ],
+        [
+          "standardResult.instances.0.ruleID",
+          "=",
+          "linkUl"
+        ],
+        [
+          "standardResult.instances.0.what",
+          "i",
+          "missing"
+        ],
+        [
+          "standardResult.instances.0.ordinalSeverity",
+          "=",
+          1
+        ],
+        [
+          "standardResult.instances.0.count",
+          "=",
+          6
+        ],
+        [
+          "standardResult.instances.0.tagName",
+          "=",
+          "A"
+        ],
+        [
+          "standardResult.instances.0.location.doc",
+          "=",
+          ""
+        ]
+      ],
+      "rules": [
+        "y",
+        "linkUl"
+      ]
     }
   ],
   "sources": {