refactor: make element spec processing more cosistent

lib/core/base/rule.js

@@ -258,7 +258,7 @@ Rule.prototype.run = function run(context, options = {}, resolve, reject) {
         .then(results => {
           const result = getResult(results);
           if (result) {
-            result.node = new DqElement(node, options);
+            result.node = new DqElement(node, options).toJSON();
             ruleResult.nodes.push(result);
 
             // mark rule as incomplete rather than failure for rules with reviewOnFail
@@ -327,7 +327,9 @@ Rule.prototype.runSync = function runSync(context, options = {}) {
 
     const result = getResult(results);
     if (result) {
-      result.node = node.actualNode ? new DqElement(node, options) : null;
+      result.node = node.actualNode
+        ? new DqElement(node, options).toJSON()
+        : null;
       ruleResult.nodes.push(result);
 
       // mark rule as incomplete rather than failure for rules with reviewOnFail

lib/core/public/run-partial.js

@@ -22,15 +22,14 @@ export default function runPartial(...args) {
   axe._selectorData = getSelectorData(contextObj.flatTree);
   axe._running = true;
 
+  // Even in the top frame, we don't support this with runPartial
+  options.elementRef = false;
+
   return (
     new Promise((res, rej) => {
       axe._audit.run(contextObj, options, res, rej);
     })
       .then(results => {
-        results = results.map(({ nodes, ...result }) => ({
-          nodes: nodes.map(serializeNode),
-          ...result
-        }));
         const frames = contextObj.frames.map(({ node }) => {
           return new DqElement(node, options).toJSON();
         });
@@ -50,16 +49,3 @@ export default function runPartial(...args) {
       })
   );
 }
-
-function serializeNode({ node, ...nodeResult }) {
-  nodeResult.node = node.toJSON();
-  for (const type of ['any', 'all', 'none']) {
-    nodeResult[type] = nodeResult[type].map(
-      ({ relatedNodes, ...checkResult }) => ({
-        ...checkResult,
-        relatedNodes: relatedNodes.map(node => node.toJSON())
-      })
-    );
-  }
-  return nodeResult;
-}

lib/core/utils/check-helper.js

@@ -43,8 +43,8 @@ function checkHelper(checkResult, options, resolve, reject) {
           node = node.actualNode;
         }
         if (node instanceof window.Node) {
-          const dqElm = new DqElement(node, options);
-          checkResult.relatedNodes.push(dqElm);
+          const nodeSpec = new DqElement(node, options).toJSON();
+          checkResult.relatedNodes.push(nodeSpec);
         }
       });
     }

lib/core/utils/collect-results-from-frames.js

@@ -19,6 +19,9 @@ export default function collectResultsFromFrames(
   resolve,
   reject
 ) {
+  // elementRefs can't be passed across frame boundaries
+  options = { ...options, elementRef: false };
+
   var q = queue();
   var frames = parentContent.frames;
 

lib/core/utils/dq-element.js

@@ -30,6 +30,7 @@ function getSource(element) {
  * "Serialized" `HTMLElement`. It will calculate the CSS selector,
  * grab the source (outerHTML) and offer an array for storing frame paths
  * @param {HTMLElement} element The element to serialize
+ * @param {Object} options Propagated from axe.run/etc
  * @param {Object} spec Properties to use in place of the element when instantiated on Elements from other frames
  */
 function DqElement(elm, options = {}, spec = {}) {
@@ -48,6 +49,8 @@ function DqElement(elm, options = {}, spec = {}) {
    */
   this.fromFrame = this.spec.selector?.length > 1;
 
+  this._includeElementInJson = options.elementRef;
+
   if (options.absolutePaths) {
     this._options = { toRoot: true };
   }
@@ -106,30 +109,71 @@ DqElement.prototype = {
     return this._element;
   },
 
+  /**
+   * Converts to a "spec", a form suitable for use with JSON.stringify
+   * (*not* to pre-stringified JSON)
+   * @returns {Object}
+   */
   toJSON() {
+    const spec = serializer.toSpec(this);
+    if (this._includeElementInJson) {
+      spec.element = this._element;
+    }
+    return spec;
+  }
+};
+
+DqElement.mergeSpecs = function mergeSpec(node, frame) {
+  // Parameter order reversed for backcompat
+  return serializer.mergeSpecs(frame, node);
+};
+
+/**
+ * The default handlers for DqElement.setSerializer. Custom serializers should
+ * produce output which at least the same properties that this would, usually
+ * by delegating to these defaults and then adding annotations on top.
+ */
+DqElement.defaultSerializer = {
+  toSpec: function toSpec(dqElm) {
+    return {
+      selector: dqElm.selector,
+      source: dqElm.source,
+      xpath: dqElm.xpath,
+      ancestry: dqElm.ancestry,
+      nodeIndexes: dqElm.nodeIndexes,
+      fromFrame: false
+    };
+  },
+  mergeSpecs: function mergeSpecs(parentFrame, child) {
     return {
-      selector: this.selector,
-      source: this.source,
-      xpath: this.xpath,
-      ancestry: this.ancestry,
-      nodeIndexes: this.nodeIndexes
+      ...child,
+      selector: [...parentFrame.selector, ...child.selector],
+      ancestry: [...parentFrame.ancestry, ...child.ancestry],
+      xpath: [...parentFrame.xpath, ...child.xpath],
+      nodeIndexes: [...parentFrame.nodeIndexes, ...child.nodeIndexes],
+      fromFrame: true
     };
   }
 };
 
-DqElement.fromFrame = function fromFrame(node, options, frame) {
-  const spec = DqElement.mergeSpecs(node, frame);
-  return new DqElement(frame.element, options, spec);
-};
+let serializer = DqElement.defaultSerializer;
 
-DqElement.mergeSpecs = function mergeSpec(node, frame) {
-  return {
-    ...node,
-    selector: [...frame.selector, ...node.selector],
-    ancestry: [...frame.ancestry, ...node.ancestry],
-    xpath: [...frame.xpath, ...node.xpath],
-    nodeIndexes: [...frame.nodeIndexes, ...node.nodeIndexes]
-  };
+/**
+ * @param {Object} newSerializer
+ * @property {Function} toSpec Converts a DqElement to a "spec", a form
+ * suitable for JSON.stringify to consume. Output must include all properites
+ * that DqElement.defaultSerializer would have. Will always be invoked from the
+ * input element's original page context.
+ * @property {Function} mergeSpecs Merges two specs (produced by toSpec) which
+ * represent element's parent frame and an element, respectively. Will
+ * *not* necessarily be invoked from *either* node's original page context.
+ * This operation must be associative, that is, these two expressions must
+ * produce the same result:
+ * - mergeSpecs(a, mergeSpecs(b, c))
+ * - mergeSpecs(mergeSpecs(a, b), c)
+ */
+DqElement.setSerializer = function setSerializer(newSerializer) {
+  serializer = { ...DqElement.defaultSerializer, ...newSerializer };
 };
 
 export default DqElement;

lib/core/utils/merge-results.js

@@ -6,17 +6,17 @@ import findBy from './find-by';
  * Adds the owning frame's CSS selector onto each instance of DqElement
  * @private
  * @param	{Array} resultSet `nodes` array on a `RuleResult`
- * @param	{HTMLElement} frameElement	The frame element
- * @param	{String} frameSelector		 Unique CSS selector for the frame
+ * @param {Object} options Propagated from axe.run/etc
+ * @param	{Object} frameSpec The spec describing the owning frame (see DqElement.toJSON())
  */
 function pushFrame(resultSet, options, frameSpec) {
   resultSet.forEach(res => {
-    res.node = DqElement.fromFrame(res.node, options, frameSpec);
+    res.node = DqElement.mergeSpecs(res.node, frameSpec);
     const checks = getAllChecks(res);
 
     checks.forEach(check => {
       check.relatedNodes = check.relatedNodes.map(node =>
-        DqElement.fromFrame(node, options, frameSpec)
+        DqElement.mergeSpecs(node, frameSpec)
       );
     });
   });
@@ -68,8 +68,10 @@ function normalizeResult(result) {
 /**
  * Merges one or more RuleResults (possibly from different frames) into one RuleResult
  * @private
- * @param	{Array} frameResults	Array of objects including the RuleResults as `results` and frame as `frame`
- * @return {Array}							The merged RuleResults; should only have one result per rule
+ * @param	{Array} frameResults Array of objects including the RuleResults as `results` and
+ * owning frame as either an Element `frameElement` or a spec `frameSpec` (see DqElement.toJSON)
+ * @param {Object} options Propagated from axe.run/etc
+ * @return {Array} The merged RuleResults; should only have one result per rule
  */
 function mergeResults(frameResults, options) {
   const mergedResult = [];
@@ -130,7 +132,7 @@ export default mergeResults;
 
 function getFrameSpec(frameResult, options) {
   if (frameResult.frameElement) {
-    return new DqElement(frameResult.frameElement, options);
+    return new DqElement(frameResult.frameElement, options).toJSON();
   } else if (frameResult.frameSpec) {
     return frameResult.frameSpec;
   }

test/core/base/audit.js

@@ -585,6 +585,8 @@ describe('Audit', function () {
         '<input aria-labelledby="monkeys">' +
         '<blink>FAIL ME</blink>';
 
+      axe.setup();
+
       a.run(
         { include: [axe.utils.getFlattenedTree(fixture)[0]] },
         {},
@@ -971,6 +973,7 @@ describe('Audit', function () {
           return true;
         }
       });
+      axe.setup();
 
       var preloadOptions = {
         preload: {

test/core/utils/dq-element.js

@@ -161,6 +161,10 @@ describe('DqElement', function () {
   });
 
   describe('toJSON', function () {
+    afterEach(() => {
+      DqElement.setSerializer(null);
+    });
+
     it('should only stringify selector and source', function () {
       var spec = {
         selector: 'foo > bar > joe',
@@ -171,8 +175,31 @@ describe('DqElement', function () {
       };
 
       var div = document.createElement('div');
-      var result = new DqElement(div, {}, spec);
-      assert.deepEqual(result.toJSON(), spec);
+      var dqElm = new DqElement(div, {}, spec);
+      assert.deepEqual(dqElm.toJSON(), spec);
+    });
+
+    it('can be hooked by setSerializer', function () {
+      var serializeNodeHook = sinon.spy(node => ({
+        ...DqElement.defaultSerializer.serializeNode(node),
+        hookAddition: 'new value'
+      }));
+      DqElement.setSerializer({ serializeNode: serializeNodeHook });
+
+      var spec = {
+        selector: 'foo > bar > joe',
+        source: '<joe aria-required="true">',
+        xpath: '/foo/bar/joe',
+        ancestry: 'foo > bar > joe',
+        nodeIndexes: [123, 456]
+      };
+      var div = document.createElement('div');
+      var dqElm = new DqElement(div, {}, spec);
+
+      var output = dqElm.toJSON();
+
+      assert.isTrue(serializeNodeHook.calledOnceWith(dqElm));
+      assert.propertyVal(output, 'hookAddition', 'new value');
     });
   });
 
@@ -199,12 +226,15 @@ describe('DqElement', function () {
       dqIframe = new DqElement(iframe, {}, iframeSpec);
     });
 
-    describe('.mergeSpecs', function () {
+    describe('DqElement.mergeSpecs', function () {
       var mainSpec, iframeSpec;
       beforeEach(function () {
         mainSpec = dqMain.toJSON();
         iframeSpec = dqIframe.toJSON();
       });
+      afterEach(function () {
+        DqElement.setSerializer(null);
+      });
 
       it('merges node and frame selectors', function () {
         var mergedSpec = DqElement.mergeSpecs(mainSpec, iframeSpec);
@@ -229,6 +259,19 @@ describe('DqElement', function () {
           mainSpec.nodeIndexes[0]
         ]);
       });
+
+      it('can be hooked by setSerializer', function () {
+        var mergeSpecsHook = sinon.spy((nodeSpec, frameSpec) => ({
+          ...DqElement.defaultSerializer.mergeSpecs(nodeSpec, frameSpec),
+          hookAddition: 'new value'
+        }));
+        DqElement.setSerializer({ mergeSpecs: mergeSpecsHook });
+
+        var mergedSpec = DqElement.mergeSpecs(mainSpec, iframeSpec);
+
+        assert.isTrue(mergeSpecsHook.calledOnceWith(mainSpec, iframeSpec));
+        assert.propertyVal(mergedSpec, 'hookAddition', 'new value');
+      });
     });
 
     describe('DqElement.fromFrame', function () {

test/integration/full/configure-options/configure-options.js

@@ -203,7 +203,7 @@ describe('Configure Options', function () {
       };
 
       var iframe = document.createElement('iframe');
-      iframe.src = '/test/mock/frames/context.html';
+      iframe.src = '/test/mock/frames/noHtml-config.html';
       iframe.onload = function () {
         axe.configure(config);
 

test/integration/full/serializer/custom-source-serializer.js

@@ -0,0 +1,13 @@
+const base = axe.utils.DqElement.defaultSerializer;
+axe.utils.DqElement.setSerializer({
+  toSpec: function toSpec(dqElm) {
+    const result = base.toSpec(dqElm);
+    result.source = dqElm.element.id;
+    return result;
+  },
+  mergeSpecs: function mergeSpecs(parentSpec, childSpec) {
+    const result = base.mergeSpecs(parentSpec, childSpec);
+    result.source = `${parentSpec.source} > ${childSpec.source}`;
+    return result;
+  }
+});

test/integration/full/serializer/frames/level1.html

@@ -0,0 +1,12 @@
+<!DOCTYPE html>
+<html id="level1" lang="INVALID">
+  <head>
+    <meta charset="utf8" />
+    <script src="/axe.js"></script>
+    <script src="../custom-source-serializer.js"></script>
+  </head>
+  <body>
+    <iframe id="frame2-a" src="level2-a.html"></iframe>
+    <iframe id="frame2-b" src="level2-b.html"></iframe>
+  </body>
+</html>

test/integration/full/serializer/frames/level2-a.html

@@ -0,0 +1,9 @@
+<!DOCTYPE html>
+<html id="level2-a" lang="INVALID">
+  <head>
+    <meta charset="utf8" />
+    <script src="/axe.js"></script>
+    <script src="../custom-source-serializer.js"></script>
+  </head>
+  <body></body>
+</html>

test/integration/full/serializer/frames/level2-b.html

@@ -0,0 +1,9 @@
+<!DOCTYPE html>
+<html id="level2-b" xml:lang="INVALID">
+  <head>
+    <meta charset="utf8" />
+    <script src="/axe.js"></script>
+    <script src="../custom-source-serializer.js"></script>
+  </head>
+  <body></body>
+</html>