feat(preload): cssom assets

doc/API.md

@@ -324,7 +324,7 @@ The options parameter is flexible way to configure how `axe.run` operates. The d
 Additionally, there are a number or properties that allow configuration of different options:
 
 | Property        | Default | Description                |
-|-----------------|:-------:|:----------------------------:|
+|-----------------|:-------|:----------------------------|
 | `runOnly`       | n/a     | Limit which rules are executed, based on names or tags
 | `rules`         | n/a     | Allow customizing a rule's properties (including { enable: false })
 | `reporter`      | `v1`    | Which reporter to use (see [Configuration](#api-name-axeconfigure))
@@ -335,6 +335,7 @@ Additionally, there are a number or properties that allow configuration of diffe
 | `elementRef`    | `false` | Return element references in addition to the target
 | `restoreScroll` | `false` | Scrolls elements back to before axe started
 | `frameWaitTime` | `60000` | How long (in milliseconds) axe waits for a response from embedded frames before timing out
+| `preload`       | `false` | Any additional assets (eg: cssom) to preload before running rules. [See here for configuration details](#preload-configuration-details)
 
 ###### Options Parameter Examples
 
@@ -456,6 +457,24 @@ Additionally, there are a number or properties that allow configuration of diffe
   ```
   This example will process all of the "violations", "incomplete", and "inapplicable" result types. Since "passes" was not specified, it will only process the first pass for each rule, if one exists. As a result, the results object's `passes` array will have a length of either `0` or `1`. On a series of extremely large pages, this would improve performance considerably.
 
+###### <a id='preload-configuration-details'></a> Preload Configuration in Options Parameter
+
+The preload attribute in options parameter accepts a `boolean` or an `object` where an array of assets can be specified. 
+
+1. Specifying a `boolean`
+
+```js
+preload: true
+```
+
+2. Specifying an `object`
+```js
+preload: { assets: ['cssom'], timeout: 50000 }
+```
+The `assets` attribute expects an array of preload(able) constraints to be fetched.
+
+The `timeout` attribute in the object configuration is `optional` and has a fallback default value. The `timeout` is essential for any network dependent assets that are preloaded.
+
 ##### Callback Parameter
 
 The callback parameter is a function that will be called when the asynchronous `axe.run` function completes. The callback function is passed two parameters. The first parameter will be an error thrown inside of aXe if axe.run could not complete. If axe completed correctly the first parameter will be null, and the second parameter will be the results object.

lib/checks/aria/aria-hidden-body.json

@@ -8,4 +8,4 @@
       "fail": "aria-hidden=true should not be present on the document body"
     }
   }
-}
+} 

lib/core/constants.js

@@ -31,7 +31,9 @@
 		results: [],
 		resultGroups: [],
 		resultGroupMap: {},
-		impact: Object.freeze(['minor', 'moderate', 'serious', 'critical'])
+		impact: Object.freeze(['minor', 'moderate', 'serious', 'critical']),
+		preloadAssets: Object.freeze(['cssom']),
+		preloadAssetsTimeout: 10000
 	};
 
 	definitions.forEach(function(definition) {

lib/core/utils/preload-cssom.js

@@ -0,0 +1,120 @@
+/**
+ * Returns a then(able) queue of CSSStyleSheet(s)
+ * @param {Object} ownerDocument document object to be inspected for stylesheets
+ * @param {number} timeout on network request for stylesheet that need to be externally fetched
+ * @param {Function} getSheetFromTextFn a utility function to generate a style sheet from text
+ * @return {Object} queue
+ * @private
+ */
+function loadCssom(ownerDocument, timeout, getSheetFromTextFn) {
+	const q = axe.utils.queue();
+
+	Array.from(ownerDocument.styleSheets).forEach(sheet => {
+		if (sheet.disabled) {
+			return;
+		}
+
+		try {
+			// attempt to resolve if sheet is relative/ same domain
+			sheet.cssRules && q.defer(resolve => resolve(sheet));
+		} catch (e) {
+			const deferredSheet = (resolve, reject) => {
+				axe.utils
+					.xhrQ({
+						url: sheet.href,
+						timeout
+					})
+					.then(xhrResponse => {
+						if (
+							xhrResponse &&
+							Array.isArray(xhrResponse) &&
+							xhrResponse.length
+						) {
+							xhrResponse.forEach(r => {
+								const text = r.responseText ? r.responseText : r.response;
+								const href = r.responseURL;
+								const sheet = getSheetFromTextFn(text, href);
+								resolve(sheet);
+							});
+						}
+					})
+					.catch(reject);
+			};
+			// external sheet -> make an xhr and q the response
+			q.defer(deferredSheet);
+		}
+	});
+
+	return q;
+}
+
+/**
+ * Returns an array of documents with a given root node/ tree
+ * @param {Object} treeRoot - the DOM tree to be inspected
+ * @return {Array} documents
+ * @private
+ */
+function getDocumentsFromTreeRoot(treeRoot) {
+	let ids = [];
+	const documents = axe.utils
+		.querySelectorAllFilter(treeRoot, '*', node => {
+			if (ids.includes(node.shadowId)) {
+				return false;
+			}
+			ids.push(node.shadowId);
+			return true;
+		})
+		.map(node => {
+			return node.actualNode.ownerDocument;
+		});
+	return documents;
+}
+
+/**
+ * @method preloadCssom
+ * @memberof axe.utils
+ * @instance
+ * @param {Object} object argument which is a composite object, with attributes asset, timeout, treeRoot(optional), resolve & reject
+ * asset - type of asset being loaded, in this case cssom
+ * timeout - timeout for any network calls made
+ * treeRoot - the DOM tree to be inspected
+ * resolve/ reject - promise chainable methods
+ * @return {Object}
+ */
+function preloadCssom({ asset, timeout, treeRoot = axe._tree[0] }) {
+	const documents = getDocumentsFromTreeRoot(treeRoot);
+	const q = axe.utils.queue();
+
+	if (!documents.length) {
+		return q;
+	}
+
+	const getSheetFromTextFn = (function() {
+		let htmlHead = document.implementation.createHTMLDocument().head;
+		return (cssText, href) => {
+			// create style node with css text
+			let style = document.createElement('style');
+			style.type = 'text/css';
+			style.href = href;
+			style.appendChild(document.createTextNode(cssText));
+			// added style to temporary document
+			htmlHead.appendChild(style);
+			return style.sheet;
+		};
+	})(); // invoke immediately
+
+	documents.forEach(doc => {
+		q.defer((resolve, reject) => {
+			loadCssom(doc, timeout, getSheetFromTextFn)
+				.then(sheets =>
+					resolve({
+						[asset]: sheets
+					})
+				)
+				.catch(reject);
+		});
+	});
+
+	return q;
+}
+axe.utils.preloadCssom = preloadCssom;

lib/core/utils/preload.js

@@ -0,0 +1,136 @@
+/**
+ * Validated the preload object
+ * @param {Object | boolean} preload configuration object or boolean passed via the options parameter to axe.run
+ * @return {boolean}
+ * @private
+ */
+function isPreloadValidObject(preload) {
+	return (
+		typeof preload === 'object' &&
+		preload.hasOwnProperty('assets') &&
+		Array.isArray(preload.assets) &&
+		preload.assets.length
+	);
+}
+
+/**
+ * Returns a boolean which decides if preload is configured
+ * @param {Object} options run configuration options (or defaults) passed via axe.run
+ * @return {boolean}
+ */
+function shouldPreload(options) {
+	if (!options) {
+		return false;
+	}
+
+	if (!options.preload) {
+		return false;
+	}
+
+	if (typeof options.preload === typeof true) {
+		return options.preload;
+	}
+
+	if (isPreloadValidObject(options.preload)) {
+		return true;
+	}
+
+	return false;
+}
+axe.utils.shouldPreload = shouldPreload;
+
+/**
+ * Constructs a configuration object representing the preload requested assets & timeout
+ * @param {Object} options run configuration options (or defaults) passed via axe.run
+ * @return {Object}
+ */
+function getPreloadConfig(options) {
+	// default fallback configuration
+	let out = {
+		assets: axe.constants.preloadAssets,
+		timeout: axe.constants.preloadAssetsTimeout
+	};
+
+	// if type is boolean
+	if (typeof options.preload === typeof true) {
+		return out;
+	}
+
+	// if type is object - ensure an array of assets to load is specified
+	if (isPreloadValidObject(options.preload)) {
+		const requestedAssets = [];
+		options.preload.assets.forEach(asset => {
+			const a = asset.toLowerCase();
+			if (axe.constants.preloadAssets.includes(a)) {
+				// unique assets to load, in case user had requested same asset type many times.
+				if (!requestedAssets.includes(a)) {
+					requestedAssets.push(a);
+				}
+				return a;
+			} else {
+				const e =
+					`Requested asset: ${a}, not supported by aXe.` +
+					`Supported assets are: ${axe.constants.preloadAssets
+						.map(_ => _)
+						.join(', ')}.`;
+				throw new Error(e);
+			}
+		});
+		out.assets = requestedAssets;
+
+		if (options.preload.timeout) {
+			if (
+				typeof options.preload.timeout === 'number' &&
+				!Number.isNaN(options.preload.timeout)
+			) {
+				out.timeout = options.preload.timeout;
+			} else {
+				throw new Error(`preload timeout specified is not of type number`);
+			}
+		}
+
+		return out;
+	} else {
+		throw new Error(
+			'No assets configured for preload in aXe run configuration'
+		);
+	}
+}
+axe.utils.getPreloadConfig = getPreloadConfig;
+
+/**
+ * Returns a then(able) queue with results of all requested preload(able) assets. Eg: ['cssom'].
+ * If preload is set to false, returns an empty queue.
+ * @param {Object} options run configuration options (or defaults) passed via axe.run
+ * @return {Object} queue
+ */
+function preload(options) {
+	const preloadFunctionsMap = {
+		cssom: axe.utils.preloadCssom
+	};
+
+	const q = axe.utils.queue();
+
+	const shouldPreload = axe.utils.shouldPreload(options);
+	if (!shouldPreload) {
+		return q;
+	}
+
+	const preloadConfig = axe.utils.getPreloadConfig(options);
+
+	preloadConfig.assets.forEach(asset => {
+		q.defer((resolve, reject) => {
+			preloadFunctionsMap[asset]({
+				asset,
+				timeout: preloadConfig.timeout
+			})
+				.then(results => {
+					resolve(results[0]);
+				})
+				.catch(reject);
+		});
+	});
+
+	return q;
+}
+axe.utils.preload = preload;

lib/core/utils/xhr-q.js

@@ -0,0 +1,73 @@
+/**
+ * Returns a then(able) queue of XHR's
+ * @param {Object} config configuration for XMLHttpRequest
+ * @return {Object}
+ */
+axe.utils.xhrQ = (config) => {
+	'use strict';
+
+	const request = new XMLHttpRequest(); // IE7+ friendly
+
+	const q = axe.utils.queue();
+
+	q.defer((resolve, reject) => {
+		// wire up timeout
+		request.timeout = config.timeout;
+
+		// listen for timeout
+		request.ontimeout = () => {
+			reject({
+				status: request.status,
+				statusText: request.statusText
+			});
+		}
+
+		// monitor ready state
+		request.onreadystatechange = () => {
+			// request is not complete.
+			if (request.readyState !== 4) {
+				return;
+			}
+			// process the response
+			if (request.status >= 200 && request.status <= 300) {
+				// success
+				resolve(request);
+			} else {
+				// failure
+				reject({
+					status: request.status,
+					statusText: request.statusText
+				});
+			}
+		};
+
+		// setup request
+		request.open(config.method || 'GET', config.url, true);
+
+		// add headers if any
+		if (config.headers) {
+			Object
+				.keys(config.headers)
+				.forEach((k) => {
+					request
+						.setRequestHeader(k, config.headers[k]);
+				});
+		}
+
+		// enumerate and construct params
+		let params = config.params;
+		if (params &&
+			typeof params === 'object') {
+			params = Object.keys(params)
+				.map((k) => {
+					return `${encodeURIComponent(k)}=${encodeURIComponent(params[k])}`;
+				})
+				.join('&');
+		}
+
+		// send 
+		request.send(params);
+	});
+
+	return q;
+}