govuk_publishing_components 18.1.0 → 18.1.1

data/node_modules/axe-core/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

data/node_modules/axe-core/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);
+	});

data/node_modules/axe-core/doc/examples/chrome-debugging-protocol/package.json

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

data/node_modules/axe-core/doc/examples/html-handlebars.md

@@ -0,0 +1,164 @@
+# Turning violation nodes into readable HTML
+
+The violations returns a list of rules that had failures. Each rule has a list of nodes that failed the rule. Each node may have failed for one or more reasons. This information is encoded in a set of structures that can be somewhat difficult to comprehend. This code shows how to turn a list of violations into a table and then for each node in a rule's nodes list, how to generate a summary of the reason(s) that rule failed.
+
+The example uses handlebars templates but can be easily adapted to other formats
+
+## The JavaScript
+
+```js
+function helperItemIterator(items, template) {
+	var out = '';
+	if (items) {
+		for (var i = 0; i < items.length; i++) {
+			out += template(items[i]);
+		}
+	}
+	return out;
+}
+Handlebars.registerHelper('violations', function(items) {
+	return helperItemIterator(items, compiledRowTemplate);
+});
+Handlebars.registerHelper('related', function(items) {
+	return helperItemIterator(items, compiledRelatedNodeTemplate);
+});
+Handlebars.registerHelper('reasons', function(items) {
+	return helperItemIterator(items, compiledFailureTemplate);
+});
+
+// Setup handlebars templates
+
+compiledRowTemplate = Handlebars.compile(rowTemplate.innerHTML);
+compiledTableTemplate = Handlebars.compile(tableTemplate.innerHTML);
+compiledRelatedListTemplate = Handlebars.compile(relatedListTemplate.innerHTML);
+compiledRelatedNodeTemplate = Handlebars.compile(relatedNodeTemplate.innerHTML);
+compiledFailureTemplate = Handlebars.compile(failureTemplate.innerHTML);
+compiledReasonsTemplate = Handlebars.compile(reasonsTemplate.innerHTML);
+
+function messageFromRelatedNodes(relatedNodes) {
+	var retVal = '';
+	if (relatedNodes.length) {
+		var list = relatedNodes.map(function(node) {
+			return {
+				targetArrayString: JSON.stringify(node.target),
+				targetString: node.target.join(' ')
+			};
+		});
+		retVal += compiledRelatedListTemplate({ relatedNodeList: list });
+	}
+	return retVal;
+}
+
+function messagesFromArray(nodes) {
+	var list = nodes.map(function(failure) {
+		return {
+			message: failure.message.replace(/</gi, '&lt;').replace(/>/gi, '&gt;'),
+			relatedNodesMessage: messageFromRelatedNodes(failure.relatedNodes)
+		};
+	});
+	return compiledReasonsTemplate({ reasonsList: list });
+}
+
+function summary(node) {
+	var retVal = '';
+	if (node.any.length) {
+		retVal += '<h3 class="error-title">Fix any of the following</h3>';
+		retVal += messagesFromArray(node.any);
+	}
+
+	var all = node.all.concat(node.none);
+	if (all.length) {
+		retVal += '<h3 class="error-title">Fix all of the following</h3>';
+		retVal += messagesFromArray(all);
+	}
+	return retVal;
+}
+
+/*
+ * This code will generate a table of the rules that failed including counts and links to the Deque University help
+ * for each rule.
+ *
+ * When used, you should attach click handlers to the anchors in order to generate the details for each of the
+ * violations for each rule.
+ */
+
+if (results.violations.length) {
+	var violations = results.violations.map(function(rule, i) {
+		return {
+			impact: rule.impact,
+			help: rule.help.replace(/</gi, '&lt;').replace(/>/gi, '&gt;'),
+			bestpractice: rule.tags.indexOf('best-practice') !== -1,
+			helpUrl: rule.helpUrl,
+			count: rule.nodes.length,
+			index: i
+		};
+	});
+
+	html = compiledTableTemplate({ violationList: violations });
+}
+
+/*
+ * To generate the human readable summary, call the `summary` function with the node. This will return HTML for that node.
+ */
+
+reasonHtml = summary(node);
+```
+
+## The Handlebars Templates
+
+```handlebars
+<script id="rowTemplate" type="text/x-handlebars-template">
+<tr>
+  <th scope="row" class="help">
+    <a href="javascript:;" class="rule" data-index="{{index}}">
+      {{{help}}}
+    </a>
+  </th>
+  <td scope="row">
+    <a target="_blank" href="{{helpUrl}}">?</a>
+  </td>
+  <td class="count">
+    {{count}}
+  </td>
+  <td class="impact">
+    {{impact}}
+  </td>
+</tr>
+</script>
+<script id="tableTemplate" type="text/x-handlebars-template">
+<table>
+  <tr>
+  <th scope="col">Description</th>
+  <th scope="col">Info</th>
+  <th scope="col">Count</th>
+  <th scope="col">Impact</th>
+  </tr>
+  {{#violations violationList}}{{/violations}}
+</table>
+</script>
+<script id="relatedListTemplate" type="text/x-handlebars-template">
+<ul>Related Nodes:
+  {{#related relatedNodeList}}{{/related}}
+</ul>
+</script>
+<script id="relatedNodeTemplate" type="text/x-handlebars-template">
+<li>
+  <a href="javascript:;" class="related-node" data-element="{{targetArrayString}}">
+    {{targetString}}
+  </a>
+</li>
+</script>
+<script id="reasonsTemplate" type="text/x-handlebars-template">
+<p class="summary">
+  <ul class="failure-message">
+    {{#reasons reasonsList}}{{/reasons}}
+  </ul>
+</p>
+</script>
+<script id="failureTemplate" type="text/x-handlebars-template">
+<li>
+  {{message}}
+  {{{relatedNodesMessage}}}
+</li>
+</script>
+```

data/node_modules/axe-core/doc/examples/jasmine/README.md

@@ -0,0 +1,37 @@
+# Jasmine README
+
+This example demonstrates how to use aXe with the Jasmine unit testing framework.
+
+The unit test is in `spec/a11y.js`, and has two test cases: One that shows the
+expected results from HTML with no errors, and one that shows the expected
+result from HTML with a single error.
+
+## To configure the example
+
+- Node must be installed; please follow the directions at http://www.nodejs.org
+  to install it.
+- `npm install -g grunt-cli` to install the Grunt task runner (may need to be
+  run with `sudo` on Unix or as Administrator on Windows)
+- Move to the `doc/examples/jasmine` directory
+- `npm install` to install dependencies
+
+## To run the example
+
+- Move to the `doc/examples/jasmine` directory
+- `grunt jasmine` to run Jasmine
+
+You should see output indicating that the tests ran successfully, with zero
+failures.
+
+## To modify the example
+
+To run the example on your own HTML, such as widgets or controls, insert the
+HTML into the document, retrieve the root element of your widget (with e.g.,
+`document.getElementById()`), and pass that as the first argument into a call
+to `axe.run`.
+
+The third argument to the `axe.run` call should be the function to test
+the results. The example is simply looking at the count of violations, but much
+more detailed information is available if desired. The aXe documentation
+should be consulted for more details on customizing and analyzing calls to
+`axe.run`.

data/node_modules/axe-core/doc/examples/jasmine/package.json

@@ -0,0 +1,20 @@
+{
+	"name": "axe-jasmine-example",
+	"description": "aXe Jasmine Example",
+	"version": "0.0.1",
+	"private": true,
+	"author": {
+		"name": "David Sturley",
+		"organization": "Deque Systems, Inc.",
+		"url": "http://deque.com/"
+	},
+	"dependencies": {},
+	"scripts": {
+		"test": "grunt jasmine"
+	},
+	"devDependencies": {
+		"axe-core": "^3.1.1",
+		"grunt": "~1.0.2",
+		"grunt-contrib-jasmine": "~2.0.0"
+	}
+}

data/node_modules/axe-core/doc/examples/jasmine/spec/a11y.js

@@ -0,0 +1,36 @@
+/* global describe, it, expect, axe, document */
+
+describe('axe', function() {
+	'use strict';
+
+	document
+		.getElementsByTagName('body')[0]
+		.insertAdjacentHTML(
+			'beforeend',
+			'<div id="working">' +
+				'<label for="has-label">Label for this text field.</label>' +
+				'<input type="text" id="has-label">' +
+				'</div>' +
+				'<div id="broken">' +
+				'<p>Not a label</p><input type="text" id="no-label">' +
+				'</div>'
+		);
+
+	it('should report that good HTML is good', function(done) {
+		var n = document.getElementById('working');
+		axe.run(n, function(err, result) {
+			expect(err).toBe(null);
+			expect(result.violations.length).toBe(0);
+			done();
+		});
+	});
+
+	it('should report that bad HTML is bad', function(done) {
+		var n = document.getElementById('broken');
+		axe.run(n, function(err, result) {
+			expect(err).toBe(null);
+			expect(result.violations.length).toBe(1);
+			done();
+		});
+	});
+});

data/node_modules/axe-core/doc/examples/jest_react/README.md

@@ -0,0 +1,41 @@
+# Jest + React README
+
+This example demonstrates how to use aXe to test React components using the
+Jest unit testing framework.
+
+The unit test is in `link.test.js`, and has one test cases, showing how to run
+axe-core in Jest (using JSDOM and Enzyme).
+
+## To configure the example
+
+- Node must be installed; please follow the directions at http://www.nodejs.org
+  to install it.
+- Move to the `doc/examples/jest_react` directory
+- `npm install` to install dependencies
+
+## To run the example
+
+- Move to the `doc/examples/jest_react` directory
+- `npm test` to run Jasmine
+
+You should see output indicating that the tests ran successfully, with zero
+failures.
+
+Note: to work better with JSDOM (which has limited support for necessary DOM APIs),
+the color-contrast and link-in-text-block rules have been disabled in this example.
+You can test for these rules more reliably using full browser DOM integration
+testing using [axe-webdriverjs](https://github.com/dequelabs/axe-webdriverjs).
+
+## To modify the example
+
+This example can be modified to test components in other test frameworks as well. To use axe-core with JSDOM (Like Jest does), you will need to ensure that JSDOM variables are made available on the global object. An easy way to do this is to use [jsdom-global](https://github.com/rstacruz/jsdom-global).
+
+For example, when running Mocha, you should require `jsdom-global/register`. The command for this is as follows:
+
+```sh
+mocha *.test.js --require jsdom-global/register
+```
+
+## Timeout Issues
+
+Axe-core is very fast for what it does, but when testing larger components, it may take a few seconds to complete. This is because axe will be running thousands of tests in a single call. When testing composite components, you may have to increase the timeout setting.

data/node_modules/axe-core/doc/examples/jest_react/link.js

@@ -0,0 +1,7 @@
+import React from 'react';
+
+export default class Link extends React.Component {
+	render() {
+		return <a href={this.props.page || '#'}>{this.props.children}</a>;
+	}
+}

data/node_modules/axe-core/doc/examples/jest_react/link.test.js

@@ -0,0 +1,24 @@
+import React from 'react';
+import axe from 'axe-core';
+import { mountToDoc } from './test-helpers';
+
+import Link from './Link';
+
+test('Link has no aXe violations', done => {
+	const linkComponent = mountToDoc(
+		<Link page="http://www.axe-core.org">aXe website</Link>
+	);
+	const linkNode = linkComponent.getDOMNode();
+
+	const config = {
+		rules: {
+			'color-contrast': { enabled: false },
+			'link-in-text-block': { enabled: false }
+		}
+	};
+	axe.run(linkNode, config, (err, { violations }) => {
+		expect(err).toBe(null);
+		expect(violations).toHaveLength(0);
+		done();
+	});
+});