feat(preload): cssom assets

doc/API.md

@@ -328,7 +328,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))
@@ -339,6 +339,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
 
@@ -460,6 +461,28 @@ 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 current set of values supported for `assets` is listed in the following table:
+
+| Asset Type | Description |
+|:-----------|:------------|
+| `cssom`    | This asset type preloads all CSS Stylesheets rulesets specified in the page. The stylessheets can be an external cross-domain resource, a relative stylesheet or an inline style with in the head tag of the document. If the stylesheet is an external cross-domain a network request is made. An object representing the CSS Rules from each stylesheet is made available to the checks evaluate function as `preloadedAssets` at run-time |
+
+The `timeout` attribute in the object configuration is `optional` and has a fallback default value (10000ms). The `timeout` is essential for any network dependent assets that are preloaded, where-in if a given request takes longer than the specified/ default value, the operation is aborted.
+
 ##### 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']), // overtime this array will grow with other preload asset types, this constant is to verify if a requested preload type by the user via the configuration is supported by axe.
+		preloadAssetsTimeout: 10000
 	};
 
 	definitions.forEach(function(definition) {

lib/core/utils/preload-cssom.js

@@ -0,0 +1,108 @@
+/**
+ * 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 {
+			if (sheet.cssRules) {
+				// accessing .cssRules throws for external (cross-domain) sheets, which is handled in the catch
+				sheet.isExternal = false; // isExternal is a flag to ascertain if a network request is necessary for cssom building
+				q.defer(resolve => resolve(sheet));
+			}
+		} catch (e) {
+			// external sheet -> make an xhr and q the response
+			q.defer((resolve, reject) => {
+				axe.imports
+					.axios({
+						method: 'get',
+						url: sheet.href,
+						timeout
+					})
+					.then(({ data }) => {
+						const sheet = getSheetFromTextFn(data, true); //second argument acts as > isExternal - true
+						resolve(sheet);
+					})
+					.catch(reject);
+			});
+		}
+	});
+
+	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({ timeout, treeRoot = axe._tree[0] }) {
+	const documents = getDocumentsFromTreeRoot(treeRoot);
+	const q = axe.utils.queue();
+
+	if (!documents.length) {
+		return q;
+	}
+
+	const dynamicDoc = document.implementation.createHTMLDocument();
+	function getSheetFromTextFn(cssText, isExternal) {
+		// create style node with css text
+		const style = dynamicDoc.createElement('style');
+		style.type = 'text/css';
+		style.appendChild(dynamicDoc.createTextNode(cssText));
+		// added style to temporary document
+		dynamicDoc.head.appendChild(style);
+		// add attribute to differentiate if it is a fetched sheet
+		style.sheet.isExternal = isExternal;
+		return style.sheet;
+	}
+
+	documents.forEach(doc => {
+		q.defer((resolve, reject) => {
+			loadCssom(doc, timeout, getSheetFromTextFn)
+				.then(resolve)
+				.catch(reject);
+		});
+	});
+
+	return q;
+}
+axe.utils.preloadCssom = preloadCssom;

lib/core/utils/preload.js

@@ -0,0 +1,116 @@
+/**
+ * Validated the preload object
+ * @param {Object | boolean} preload configuration object or boolean passed via the options parameter to axe.run
+ * @return {boolean}
+ * @private
+ */
+function isValidPreloadObject(preload) {
+	if (typeof preload !== 'object') {
+		return preload;
+	}
+	return (
+		typeof preload === 'object' &&
+		preload.hasOwnProperty('assets') &&
+		Array.isArray(preload.assets)
+	);
+}
+
+/**
+ * Returns a boolean which decides if preload is configured
+ * @param {Object} options run configuration options (or defaults) passed via axe.run
+ * @return {boolean}
+ */
+axe.utils.shouldPreload = function shouldPreload(options) {
+	return isValidPreloadObject(options.preload);
+};
+
+/**
+ * Constructs a configuration object representing the preload requested assets & timeout
+ * @param {Object} options run configuration options (or defaults) passed via axe.run
+ * @return {Object}
+ */
+axe.utils.getPreloadConfig = function getPreloadConfig(options) {
+	// default fallback configuration
+	const config = {
+		assets: axe.constants.preloadAssets,
+		timeout: axe.constants.preloadAssetsTimeout
+	};
+
+	// if type is boolean
+	if (typeof options.preload === 'boolean') {
+		return config;
+	}
+
+	// if type is object - ensure an array of assets to load is specified
+	if (!isValidPreloadObject(options.preload)) {
+		throw new Error(
+			'No assets configured for preload in aXe run configuration'
+		);
+	}
+
+	// check if requested assets to preload are valid items
+	const areRequestedAssetsValid = options.preload.assets.every(a =>
+		axe.constants.preloadAssets.includes(a.toLowerCase())
+	);
+
+	if (!areRequestedAssetsValid) {
+		throw new Error(
+			`Requested assets, not supported by aXe.` +
+				`Supported assets are: ${axe.constants.preloadAssets.join(', ')}.`
+		);
+	}
+
+	// unique assets to load, in case user had requested same asset type many times.
+	config.assets = axe.utils.uniqueArray(
+		options.preload.assets.map(a => a.toLowerCase()),
+		[]
+	);
+
+	if (
+		options.preload.timeout &&
+		typeof options.preload.timeout === 'number' &&
+		!Number.isNaN(options.preload.timeout)
+	) {
+		config.timeout = options.preload.timeout;
+	}
+	return config;
+};
+
+/**
+ * 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
+ */
+axe.utils.preload = 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 => {
+					const sheets = results[0];
+					resolve({
+						[asset]: sheets
+					});
+				})
+				.catch(reject);
+		});
+	});
+
+	return q;
+};

lib/rules/aria-hidden-body.json

@@ -16,4 +16,4 @@
     "aria-hidden-body"
   ],
   "none": []
-}
+}

test/core/utils/preload-cssom.js

@@ -0,0 +1,90 @@
+describe('axe.utils.preloadCssom unit tests', function() {
+	'use strict';
+
+	var args;
+
+	function addStyleToHead() {
+		var css = 'html {font-size: inherit;}';
+		var head = document.head || document.getElementsByTagName('head')[0];
+		var style = document.createElement('style');
+		style.id = 'preloadCssomTestHeadSheet';
+		style.type = 'text/css';
+		style.appendChild(document.createTextNode(css));
+		head.appendChild(style);
+	}
+
+	function removeStyleFromHead() {
+		var s = document.getElementById('preloadCssomTestHeadSheet');
+		if (s) {
+			s.parentNode.removeChild(s);
+		}
+	}
+
+	beforeEach(function() {
+		addStyleToHead();
+		args = {
+			asset: 'cssom',
+			timeout: 10000,
+			treeRoot: (axe._tree = axe.utils.getFlattenedTree(document))
+		};
+	});
+
+	afterEach(function() {
+		removeStyleFromHead();
+	});
+
+	it('should be a function', function() {
+		assert.isFunction(axe.utils.preloadCssom);
+	});
+
+	it('should return a queue', function() {
+		var actual = axe.utils.preloadCssom(args);
+		assert.isObject(actual);
+		assert.containsAllKeys(actual, ['then', 'defer', 'catch']);
+	});
+
+	it('should ensure result of cssom is an array of sheets', function(done) {
+		var actual = axe.utils.preloadCssom(args);
+		actual
+			.then(function(results) {
+				assert.lengthOf(results[0], 2); // returned from queue, hence the index look up
+				done();
+			})
+			.catch(function(error) {
+				done(error);
+			});
+	});
+
+	it('should fail if number of sheets returned does not match stylesheets defined in document', function(done) {
+		var actual = axe.utils.preloadCssom(args);
+		actual
+			.then(function(results) {
+				assert.isFalse(results[0].length <= 1); // returned from queue, hence the index look up
+				done();
+			})
+			.catch(function(error) {
+				done(error);
+			});
+	});
+
+	it('should ensure all returned stylesheet is defined and has property cssRules', function(done) {
+		var actual = axe.utils.preloadCssom(args);
+		actual
+			.then(function(results) {
+				var sheets = results[0];
+				sheets.forEach(function(s) {
+					assert.isDefined(s);
+					assert.property(s, 'cssRules');
+				});
+				done();
+			})
+			.catch(function(error) {
+				done(error);
+			});
+	});
+
+	/**
+	 * NOTE: document.styleSheets does not recognise dynamically injected stylesheets after load via beforeEach/ before, so tests for disabled and external stylesheets are done in integration
+	 * Refer Directory: ./test/full/preload-cssom/**.*
+	 */
+});