Merge branch 'develop' into wip/runtime-localization

* develop:
  feat(imports): add `doT` template engine (#1024)
  doc: ensure client is closed
  doc: fix comment
  doc: fix "parity" typo
  doc: ensure user starts chrome
  chore(package): auto-format *.ts files (#1029)
  build: replace babel-preset-es2015 with babel-preset-env (#1027)
  chore: remove `.jshintrc` files (#1028)
  chore: add `.npmrc` (#1026)
  chore: upgrade Prettier and run the formatter (#1030)
  doc(examples): add simple CDP example
  ci: Speed up builds by caching node_modules (#1025)

.babelrc

@@ -1,6 +1,6 @@
 {
   "presets": [
-    "es2015"
+    "env"
   ],
   "plugins": [
     "transform-object-rest-spread"

.npmrc

@@ -0,0 +1,2 @@
+package-lock=false
+registry=https://registry.npmjs.org

build/tasks/generate-imports.js

@@ -78,6 +78,9 @@ module.exports = grunt => {
 						writeLibrary(libName, factory);
 					});
 				} else if (global) {
+					// The global variable exposed by the library. This is not necessarily the same as "libName".
+					const libraryGlobal = global;
+
 					// We wrap the library's source code in an IFFE which voids
 					// existing globals (module, define, process, etc.) forces and
 					// forces it to export a global.
@@ -94,18 +97,18 @@ module.exports = grunt => {
 
 							// If there was a global prior to our script, make sure we
 							// "save" it (think "$.noConflict()").
-							var __old_global__ = global["${global}"];
+							var __old_global__ = global["${libraryGlobal}"];
 
 							${sourceCode}
 
 							// Preserve a reference to the library and remove it from
 							// the global scope.
-							var lib = global["${global}"];
-							delete global["${global}"];
+							var lib = global["${libraryGlobal}"];
+							delete global["${libraryGlobal}"];
 
 							// Reset a previous global when applicable.
 							if (__old_global__) {
-								global["${global}"] = __old_global__;
+								global["${libraryGlobal}"] = __old_global__;
 							}
 
 							// Return the library to populate "axe.imports".

circle.yml

@@ -3,11 +3,15 @@ jobs:
   build:
     docker:
       - image: circleci/node:6.12.3-browsers
+    working_directory: ~/axe-core
     steps:
       - checkout
-      - run:
-          name: install-npm
-          command: npm install
-      - run:
-          name: test
-          command: npm test
+      - restore_cache:
+          keys:
+            - npm-deps-{{ checksum "package.json" }}
+      - run: npm install
+      - save_cache:
+          key: npm-deps-{{ checksum "package.json" }}
+          paths:
+            - node_modules
+      - run: npm test

doc/examples/chrome-debugging-protocol/.eslintrc

@@ -0,0 +1,8 @@
+{
+  "env": {
+    "es6": true
+  },
+  "parserOptions": {
+    "ecmaVersion": 8
+  }
+}

doc/examples/chrome-debugging-protocol/.npmrc

@@ -0,0 +1 @@
+package-lock=false

doc/examples/chrome-debugging-protocol/README.md

@@ -0,0 +1,13 @@
+# axe-chrome-debugging-protocol-example
+
+This (very minimal) example demonstrates how to use `axe-core` with the [Chrome Debugging Protocol](https://chromedevtools.github.io/devtools-protocol/).
+
+The example does not have feature parity with [`axe-webdriverjs`](https://github.com/dequelabs/axe-webdriverjs), and does not run on `<iframe>`s.
+
+## To run the example
+
+- Ensure Node v8+ is installed and on `PATH`
+- Move to the `doc/examples/chrome-debugging-protocol` directory
+- Run `npm install`
+- Run `google-chrome --headless --remote-debugging-port=9222`. If you don't have a `google-chrome` binary, you can alias one with `alias google-chrome='/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome'` on OSX.
+- Run `node axe-cdp.js http://www.deque.com` to run `axe-core` via Puppeteer against http://www.deque.com and output results to the terminal

doc/examples/chrome-debugging-protocol/axe-cdp.js

@@ -0,0 +1,81 @@
+const CDP = require('chrome-remote-interface');
+const axeCore = require('axe-core');
+const assert = require('assert');
+const { parse: parseURL } = require('url');
+
+// Cheap URL validation
+const isValidURL = input => {
+	const u = parseURL(input);
+	return u.protocol && u.host;
+};
+
+const example = async url => {
+	// eslint-disable-next-line new-cap
+	const client = await CDP();
+	const { Runtime: runtime, Page: page } = client;
+
+	let results;
+
+	try {
+		await page.enable();
+		await runtime.enable();
+
+		await page.navigate({ url });
+
+		// This function is injected into the browser and is responsible for
+		// running `axe-core`.
+		const browserCode = () => {
+			/* eslint-env browser */
+			return new Promise((resolve, reject) => {
+				const axe = window.axe;
+				if (!axe) {
+					throw new Error('Unable to find axe-core');
+				}
+
+				// Finally, run axe-core
+				axe
+					.run()
+					// For some reason, when resolving with an object, CDP ignores
+					// its value (`results.result.value` is undefined). By
+					// `JSON.stringify()`ing it, we can `JSON.parse()` it later on
+					// and return a valid results set.
+					.then(results => JSON.stringify(results))
+					.then(resolve)
+					.catch(reject);
+			});
+		};
+
+		// Inject axe-core
+		await runtime.evaluate({
+			expression: axeCore.source
+		});
+
+		// Run axe-core
+		const ret = await runtime.evaluate({
+			expression: `(${browserCode})()`,
+			awaitPromise: true
+		});
+
+		// re-parse
+		results = JSON.parse(ret.result.value);
+	} catch (err) {
+		// Ensure we close the client before exiting the fn
+		client.close();
+		throw err;
+	}
+	client.close();
+	return results;
+};
+
+// node axe-cdp.js <url>
+const url = process.argv[2];
+assert(isValidURL(url), 'Invalid URL');
+
+example(url)
+	.then(results => {
+		console.log(results);
+	})
+	.catch(err => {
+		console.error('Error running axe-core:', err.message);
+		process.exit(1);
+	});

doc/examples/chrome-debugging-protocol/package.json

@@ -0,0 +1,8 @@
+{
+  "name": "axe-cdp",
+  "private": true,
+  "dependencies": {
+    "axe-core": "^3.0.3",
+    "chrome-remote-interface": "^0.26.0"
+  }
+}