doc(examples): add simple CDP example (#1032)

This patch adds an example of using axe-core with the Chrome Debugging Protocol. The example is very minimal and does not include all of axe-webdriverjs's features.

## Reviewer checks

**Required fields, to be filled out by PR reviewer(s)**
- [x] Follows the commit message policy, appropriate for next version
- [x] Has documentation updated, a DU ticket, or requires no documentation change
- [x] Includes new tests, or was unnecessary
- [x] Code is reviewed for security by: @isner

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"
+  }
+}