Merge branch 'develop' into isValidRole-abstracts

axe.d.ts

@@ -2,126 +2,125 @@
 // Project: https://github.com/dequelabs/axe-core
 // Definitions by: Marcy Sutton <https://github.com/marcysutton>
 
-declare module axe {
+declare namespace axe {
+	type ImpactValue = 'minor' | 'moderate' | 'serious' | 'critical';
 
-	type ImpactValue = "minor" | "moderate" | "serious" | "critical";
+	type TagValue = 'wcag2a' | 'wcag2aa' | 'section508' | 'best-practice';
 
-	type TagValue = "wcag2a" | "wcag2aa" | "section508" | "best-practice";
+	type ReporterVersion = 'v1' | 'v2';
 
-	type ReporterVersion = "v1" | "v2";
+	type RunOnlyType = 'rule' | 'rules' | 'tag' | 'tags';
 
-	type RunOnlyType = "rule" | "rules" | "tag" | "tags";	
-
-	type resultGroups = "inapplicable" | "passes" | "incomplete" | "violations";
+	type resultGroups = 'inapplicable' | 'passes' | 'incomplete' | 'violations';
 
 	type RunOnlyObject = {
-		include?: string[] | string[][],
-		exclude?: string[] | string[][]
-	}
+		include?: string[] | string[][];
+		exclude?: string[] | string[][];
+	};
 
 	type RunCallback = (error: Error, results: AxeResults) => void;
 
 	type ElementContext = Node | string | RunOnlyObject;
 
 	interface RunOnly {
-		type: RunOnlyType,
-		values?: TagValue[] | string[]
+		type: RunOnlyType;
+		values?: TagValue[] | string[] | RunOnlyObject;
 	}
 	interface RunOptions {
-		runOnly?: RunOnly,
-		rules?: Object,
-		iframes?: boolean,
-		elementRef?: boolean,
-		selectors?: boolean,
-		resultTypes?: resultGroups[],
+		runOnly?: RunOnly;
+		rules?: Object;
+		iframes?: boolean;
+		elementRef?: boolean;
+		selectors?: boolean;
+		resultTypes?: resultGroups[];
 	}
 	interface AxeResults {
-		url: string,
-		timestamp: string,
-		passes: Result[],
-		violations: Result[],
-		incomplete: Result[],
-		inapplicable: Result[]
+		url: string;
+		timestamp: string;
+		passes: Result[];
+		violations: Result[];
+		incomplete: Result[];
+		inapplicable: Result[];
 	}
 	interface Result {
-		description: string,
-		help: string,
-		helpUrl: string,
-		id: string,
-		impact: ImpactValue,
-		tags: TagValue[],
-		nodes: NodeResult[]
+		description: string;
+		help: string;
+		helpUrl: string;
+		id: string;
+		impact: ImpactValue;
+		tags: TagValue[];
+		nodes: NodeResult[];
 	}
 	interface NodeResult {
-		html: string,
-		impact: ImpactValue,
-		target: string[],
-		any: CheckResult[],
-		all: CheckResult[],
-		none: CheckResult[],
-		failureSummary?: string
+		html: string;
+		impact: ImpactValue;
+		target: string[];
+		any: CheckResult[];
+		all: CheckResult[];
+		none: CheckResult[];
+		failureSummary?: string;
 	}
 	interface CheckResult {
-		id: string,
-		impact: string,
-		message: string,
-		data: any,
-		relatedNodes?: RelatedNode[]
+		id: string;
+		impact: string;
+		message: string;
+		data: any;
+		relatedNodes?: RelatedNode[];
 	}
 	interface RelatedNode {
-		target: string[],
-		html: string
+		target: string[];
+		html: string;
 	}
 	interface Spec {
 		branding?: {
-			brand: string,
-			application: string
-		},
-		reporter?: ReporterVersion,
-		checks?: Check[],
-		rules?: Rule[]
+			brand: string;
+			application: string;
+		};
+		reporter?: ReporterVersion;
+		checks?: Check[];
+		rules?: Rule[];
 	}
 	interface Check {
-		id: string,
-		evaluate: Function | string,
-		after?: Function | string,
-		options?: any,
-		matches?: string,
-		enabled?: boolean
+		id: string;
+		evaluate: Function | string;
+		after?: Function | string;
+		options?: any;
+		matches?: string;
+		enabled?: boolean;
 	}
 	interface Rule {
-		id: string,
-		selector?: string,
-		excludeHidden?: boolean,
-		enabled?: boolean,
-		pageLevel?: boolean,
-		any?: string[],
-		all?: string[],
-		none?: string[],
-		tags?: string[],
-		matches?: string
+		id: string;
+		selector?: string;
+		excludeHidden?: boolean;
+		enabled?: boolean;
+		pageLevel?: boolean;
+		any?: string[];
+		all?: string[];
+		none?: string[];
+		tags?: string[];
+		matches?: string;
 	}
 	interface AxePlugin {
-		id: string,
-		run(...args: any[]): any,
+		id: string;
+		run(...args: any[]): any;
 		commands: {
-			id: string,
-			callback(...args: any[]): void
-		}[],
-		cleanup?(callback: Function): void
+			id: string;
+			callback(...args: any[]): void;
+		}[];
+		cleanup?(callback: Function): void;
 	}
 
-	let plugins: any
+	let plugins: any;
 
 	/**
 	 * Source string to use as an injected script in Selenium
 	 */
-	let source: string
+	let source: string;
 
 	/**
 	 * Object for aXe Results
 	 */
-	var AxeResults: AxeResults
+	var AxeResults: AxeResults;
 
 	/**
 	 * Runs a number of rules against the provided HTML page and returns the resulting issue list
@@ -131,44 +130,50 @@ declare module axe {
 	 * @param   {RunCallback}    callback Optional The function to invoke when analysis is complete.
 	 * @returns {Promise<AxeResults>|void} If the callback was not defined, aXe will return a Promise.
 	 */
-	function run(context?: ElementContext): Promise<AxeResults>
-	function run(options: RunOptions): Promise<AxeResults>
-	function run(callback: (error: Error, results: AxeResults) => void): void
-	function run(context: ElementContext, callback: RunCallback): void
-	function run(options: RunOptions, callback: RunCallback): void
-	function run(context: ElementContext, options: RunOptions): Promise<AxeResults>
-	function run(context: ElementContext, options: RunOptions, callback: RunCallback): void
+	function run(context?: ElementContext): Promise<AxeResults>;
+	function run(options: RunOptions): Promise<AxeResults>;
+	function run(callback: (error: Error, results: AxeResults) => void): void;
+	function run(context: ElementContext, callback: RunCallback): void;
+	function run(options: RunOptions, callback: RunCallback): void;
+	function run(
+		context: ElementContext,
+		options: RunOptions
+	): Promise<AxeResults>;
+	function run(
+		context: ElementContext,
+		options: RunOptions,
+		callback: RunCallback
+	): void;
 
 	/**
 	 * Method for configuring the data format used by aXe. Helpful for adding new
 	 * rules, which must be registered with the library to execute.
 	 * @param  {Spec}       Spec Object with valid `branding`, `reporter`, `checks` and `rules` data
 	 */
-	function configure(spec: Spec): void
+	function configure(spec: Spec): void;
 
 	/**
 	 * Searches and returns rules that contain a tag in the list of tags.
 	 * @param  {Array}  tags  Optional array of tags
 	 * @return {Array}  Array of rules
 	 */
-	function getRules(tags?: string[]): Object[]
+	function getRules(tags?: string[]): Object[];
 
 	/**
 	 * Restores the default axe configuration
 	 */
-	function reset(): void
+	function reset(): void;
 
 	/**
 	 * Function to register a plugin configuration in document and its subframes
 	 * @param  {Object}    plugin    A plugin configuration object
 	 */
-	function registerPlugin(plugin: AxePlugin): void
+	function registerPlugin(plugin: AxePlugin): void;
 
 	/**
 	 * Function to clean up plugin configuration in document and its subframes
 	 */
-	function cleanup(): void
-
+	function cleanup(): void;
 }
 
 export = axe;

doc/examples/puppeteer/.eslintrc

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

doc/examples/puppeteer/.npmrc

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

doc/examples/puppeteer/README.md

@@ -0,0 +1,12 @@
+# axe-puppeteer-example
+
+This (very minimal) example demonstrates how to use `axe-core` with [Puppeteer](https://github.com/GoogleChrome/puppeteer).
+
+The example does not have feature pairty 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/puppeteer` directory
+* Run `npm install`
+* Run `node axe-puppeteer.js http://www.deque.com` to run `axe-core` via Puppeteer against http://www.deque.com and output results to the terminal

doc/examples/puppeteer/axe-puppeteer.js

@@ -0,0 +1,60 @@
+const puppeteer = require('puppeteer');
+const axeCore = require('axe-core');
+const { parse: parseURL } = require('url');
+const assert = require('assert');
+
+// Cheap URL validation
+const isValidURL = input => {
+	const u = parseURL(input);
+	return u.protocol && u.host;
+};
+
+// node axe-puppeteer.js <url>
+const url = process.argv[2];
+assert(isValidURL(url), 'Invalid URL');
+
+const main = async url => {
+	let browser;
+	let results;
+	try {
+		// Setup Puppeteer
+		browser = await puppeteer.launch();
+
+		// Get new page
+		const page = await browser.newPage();
+		await page.goto(url);
+
+		// Inject and run axe-core
+		const handle = await page.evaluateHandle(`
+			// Inject axe source code
+			${axeCore.source}
+			// Run axe
+			axe.run()
+		`);
+
+		// Get the results from `axe.run()`.
+		results = await handle.jsonValue();
+		// Destroy the handle & return axe results.
+		await handle.dispose();
+	} catch (err) {
+		// Ensure we close the puppeteer connection when possible
+		if (browser) {
+			await browser.close();
+		}
+
+		// Re-throw
+		throw err;
+	}
+
+	await browser.close();
+	return results;
+};
+
+main(url)
+	.then(results => {
+		console.log(results);
+	})
+	.catch(err => {
+		console.error('Error running axe-core:', err.message);
+		process.exit(1);
+	});

doc/examples/puppeteer/package.json

@@ -0,0 +1,10 @@
+{
+  "name": "axe-puppeteer",
+  "version": "0.0.0",
+  "private": true,
+  "main": "axe-puppeteer.js",
+  "dependencies": {
+    "axe-core": "^3.0.3",
+    "puppeteer": "^1.6.0"
+  }
+}

package.json

@@ -56,14 +56,15 @@
   },
   "scripts": {
     "build": "grunt",
-    "test": "grunt test",
+		"test-dts": "tsc",
+    "test": "npm run test-dts && grunt test",
     "test-fast": "grunt test-fast",
     "version": "echo \"use 'npm run release' to bump axe-core version\" && exit 1",
     "prepublishOnly": "grunt build",
     "postinstall": "node build/utils/postinstall.js",
     "release": "standard-version -a",
     "sri-update": "grunt build && node build/sri-update && git add sri-history.json",
-    "fmt": "prettier --write *.js '{build,doc,lib,test}/**/*.js'",
+    "fmt": "prettier --write  *.js, **/*.ts '{build,doc,lib,test}/**/*.js'",
     "precommit": "lint-staged"
   },
   "devDependencies": {
@@ -106,6 +107,7 @@
     "selenium-webdriver": "~3.6.0",
     "sri-toolbox": "^0.2.0",
     "standard-version": "^4.2.0",
+    "typescript": "^2.9.2",
     "uglify-js": "^3.4.4"
   },
   "dependencies": {},