From d9699bb2f81bf4c1afc0e488ba1fd1732def4b2d Mon Sep 17 00:00:00 2001
From: Grzegorz Ziolkowski <grzegorz@gziolo.pl>
Date: Fri, 11 Jan 2019 19:09:37 +0000
Subject: [PATCH] Docs: Add documentation for jest-puppeteer-axe package

---
 packages/jest-puppeteer-axe/README.md    | 47 ++++++++++++++++++++++++
 packages/jest-puppeteer-axe/src/index.js | 22 +++++++++++
 2 files changed, 69 insertions(+)

diff --git a/packages/jest-puppeteer-axe/README.md b/packages/jest-puppeteer-axe/README.md
index 4071c0b3b101f1..b5e20cda390eb8 100644
--- a/packages/jest-puppeteer-axe/README.md
+++ b/packages/jest-puppeteer-axe/README.md
@@ -2,6 +2,8 @@
 
 [Axe](https://www.deque.com/axe/) (the Accessibility Engine) API integration with [Jest](https://jestjs.io/) and [Puppeteer](https://pptr.dev/).
 
+Defines Jest async matcher to check whether a given Puppeteer's page instance is accessible.
+
 ## Installation
 
 Install the module
@@ -10,4 +12,49 @@ Install the module
 npm install @wordpress/jest-puppeteer-axe --save-dev
 ```
 
+### Setup
+
+The simplest setup is to use Jest's `setupTestFrameworkScriptFile` config option:
+
+```js
+"jest": {
+  "setupTestFrameworkScriptFile": "./node_modules/@wordpress/jest-puppeteer-axe/build/index.js"
+},
+```
+
+If your project already has a script file which sets up the test framework, you will need the following import statement:
+
+```js
+import '@wordpress/jest-puppeteer-axe';
+```
+
+## Usage
+
+In your Jest test suite add the following code to the test's body:
+
+```js
+test( 'checks accessibility of the test page', async () => {
+	// First, run some code which loads the content of the page.
+	loadTestPage();
+	
+	await expect( page ).toBeAccessible();
+} );
+```
+
+It is also possible to pass optional Axe API options to perform customized check:
+- `include` - CSS selector to to add the list of elements to include in analysis.
+- `exclude` - CSS selector to to add the list of elements to exclude from analysis.
+
+```js
+test( 'checks accessibility of the test component excluding some button', async () => {
+	// First, run some code which loads the content of the page.
+	loadPageWithTestComponent();
+	
+	await expect( page ).toBeAccessible( {
+		include: '.test-component',
+		exclude: '.some-button',
+	} );
+} );
+```
+
 <br/><br/><p align="center"><img src="https://s.w.org/style/images/codeispoetry.png?1" alt="Code is Poetry." /></p>
diff --git a/packages/jest-puppeteer-axe/src/index.js b/packages/jest-puppeteer-axe/src/index.js
index 1d99017e40137e..4333aae72c97ca 100644
--- a/packages/jest-puppeteer-axe/src/index.js
+++ b/packages/jest-puppeteer-axe/src/index.js
@@ -3,6 +3,13 @@
  */
 import AxePuppeteer from 'axe-puppeteer';
 
+/**
+ * Formats the list of violations object returned by Axe analysis.
+ *
+ * @param {Object} violations The object with the errors found by Axe.
+ *
+ * @return {string} The user friendly message to display when the matcher fails.
+ */
 function formatViolations( violations ) {
 	return violations.map( ( { help, id, nodes } ) => {
 		let output = `Rule: ${ id } (${ help })\n` +
@@ -37,6 +44,21 @@ function formatViolations( violations ) {
 	} ).join( '\n' );
 }
 
+/**
+ * Defines async matcher to check whether a given Puppeteer's page instance is accessible.
+ * It is possible to pass optional Axe API options to perform customized check.
+ *
+ * @see https://github.com/dequelabs/axe-puppeteer
+ *
+ * @param {Page}    page             Puppeteer's page instance.
+ * @param {?Object} params           Optional Axe API options.
+ * @param {?string} params.include   CSS selector to add to the list of elements
+ *                                   to include in analysis.
+ * @param {?string} params.exclude   CSS selector to add to the list of elements
+ *                                   to exclude from analysis.
+ *
+ * @return {Object} A matcher object with two keys `pass` and `message`.
+ */
 async function toBeAccessible( page, { include, exclude } = {} ) {
 	const axe = new AxePuppeteer( page );