pa11y-ci-reporter-runner 0.5.0 → 0.6.0

package/README.md

@@ -19,9 +19,10 @@ Pa11y CI Reporter Runner exports a factory function that creates a reporter runn
 - `options`: Optional [reporter options](https://github.com/pa11y/pa11y-ci#reporter-options).
 - `config`: Optional Pa11y CI configuration file that produces the Pa11y CI JSON results.
 
-The reporter runner currently has one function:
+The reporter runner has two functions:
 
-- `runAll`: Simulates Pa11y CI running the complete analysis from the provided JSON results file, calling all associated reporter functions (`beforeAll`, `begin` and `results`/`error` for each URL, `afterAll`).
+- `runAll`: Simulates Pa11y CI running the complete analysis from the provided JSON results file, calling all associated reporter functions (`beforeAll`, `begin` and `results`/`error` for each URL, `afterAll`). Once a run has been completed the runner must be reset before running again.
+- `reset`: Resets the runner to the initial state.
 
 A complete example is provided below:
 

package/index.js

@@ -1,7 +1,7 @@
 'use strict';
 
 /**
- * Pa11y CI Reporter Runner allows a pa11y-ci reporter to be run
+ * Pa11y CI Reporter Runner allows a Pa11y CI reporter to be run
  * from a JSON results file without using pa11y-ci.
  *
  * @module pa11y-ci-reporter-runner
@@ -9,9 +9,17 @@
 
 const fs = require('fs');
 const formatter = require('./lib/formatter');
-const reporterBuilder = require('./lib/reporterBuilder');
+const reporterBuilder = require('./lib/reporter-builder');
 const createConfig = require('./lib/config');
+const { serviceFactory } = require('./lib/pa11yci-service');
 
+/**
+ * Loads the Pa11y CI results from JSON file.
+ *
+ * @private
+ * @param   {string} fileName Pa11y CI JSON results file name.
+ * @returns {object}          Pa11y CI results.
+ */
 const loadPa11yciResults = fileName => {
     if (typeof fileName !== 'string') {
         throw new TypeError('fileName must be a string');
@@ -21,20 +29,17 @@ const loadPa11yciResults = fileName => {
         const results = JSON.parse(fs.readFileSync(fileName, 'utf8'));
         return formatter.convertJsonToResultsObject(results);
     }
-    catch (err) {
-        throw new Error(`Error loading results file - ${err.message}`);
+    catch (error) {
+        throw new Error(`Error loading results file - ${error.message}`);
     }
 };
 
-const isError = results => results.length === 1 && results[0] instanceof Error;
-
 /**
  * Pa11y CI configuration allows config.urls entries to be either url strings
  * or object with url and other configuration, so this return a list of just
  * the url strings.
  *
  * @private
- * @static
  * @param   {object[]} values The urls array from configuration.
  * @returns {string[]}        Array of URL strings.
  */
@@ -55,13 +60,12 @@ const getUrlList = values => {
 };
 
 /**
- * Compares URLs in Pa1y CI results and configuration files to ensure
+ * Compares URLs in Pa11y CI results and configuration files to ensure
  * consistency (i.e. The same URLs are in both lists, although they
  * may not be in the same order). URLs in config are only checked if
  * provided. If specified and inconsistent, throws error.
  *
  * @private
- * @static
  * @param   {object} results Pa11y CI JSON results file.
  * @param   {object} config  Pa11y CI configuration.
  */
@@ -78,6 +82,15 @@ const validateUrls = (results, config) => {
     }
 };
 
+/**
+ * Check if the given Pa11y results are an execution error.
+ *
+ * @private
+ * @param   {object}  results Pa11y results for a single URL.
+ * @returns {boolean}         True if the results are an execution error.
+ */
+const isError = results => results.length === 1 && results[0] instanceof Error;
+
 /**
  * Factory to create a pa11y-ci reporter runner that can execute
  * a reporter with the specified pa11y-ci JSON results file.
@@ -90,6 +103,7 @@ const validateUrls = (results, config) => {
  * @param   {object} config          The Pa11y CI configuration.
  * @returns {object}                 A Pa11y CI reporter runner.
  */
+// eslint-disable-next-line max-lines-per-function
 const createRunner = (resultsFileName, reporterName, options = {}, config = {}) => {
     const pa11yciResults = loadPa11yciResults(resultsFileName);
 
@@ -97,27 +111,85 @@ const createRunner = (resultsFileName, reporterName, options = {}, config = {})
 
     const pa11yciConfig = createConfig(config);
     const reporter = reporterBuilder.buildReporter(reporterName, options, pa11yciConfig.defaults);
+    const urls = config.urls || Object.keys(pa11yciResults.results);
+
+    /**
+     * Implements the runner beforeAll event, calling reporter.beforeAll.
+     *
+     * @private
+     */
+    const beforeAll = async () => {
+        await reporter.beforeAll(urls);
+    };
 
-    const runAll = async () => {
-        await reporter.beforeAll(config.urls || Object.keys(pa11yciResults.results));
-
-        for (const url of Object.keys(pa11yciResults.results)) {
-            await reporter.begin(url);
-
-            const urlResults = pa11yciResults.results[url];
-            const urlConfig = pa11yciConfig.getConfigForUrl(url);
-            if (isError(urlResults)) {
-                await reporter.error(urlResults[0], url, urlConfig);
-            }
-            else {
-                await reporter.results(formatter.getPa11yResultsFromPa11yCiResults(url, pa11yciResults), urlConfig);
-            }
-        }
+    /**
+     * Implements the runner beginUrl event, calling reporter.begin.
+     *
+     * @private
+     * @param {string} url The url being analyzed.
+     */
+    const beginUrl = async (url) => {
+        await reporter.begin(url);
+    };
 
+    /**
+     * Implements the runner urlResults event, calling reporter.results or
+     * reporter.error as appropriate based on the results.
+     *
+     * @private
+     * @param {string} url The url being analyzed.
+     */
+    const urlResults = async (url) => {
+        const results = pa11yciResults.results[url];
+        const urlConfig = pa11yciConfig.getConfigForUrl(url);
+        await (isError(results)
+            ? reporter.error(results[0], url, urlConfig)
+            : reporter.results(formatter.getPa11yResultsFromPa11yCiResults(url, pa11yciResults), urlConfig));
+    };
+
+    /**
+     * Implements the runner afterAll event, calling reporter.afterAll.
+     *
+     * @private
+     */
+    const afterAll = async () => {
         await reporter.afterAll(pa11yciResults, pa11yciConfig.defaults);
     };
 
+    // Collection of runner actions to be passed to the state service.
+    const actions = {
+        beforeAll,
+        beginUrl,
+        urlResults,
+        afterAll
+    };
+
+    // URLs for the service is always the array of result URLs since they
+    // are used to retrieve the results.
+    const service = serviceFactory(Object.keys(pa11yciResults.results), actions);
+
+    /**
+     * Resets the runner to the initial state.
+     *
+     * @public
+     * @instance
+     */
+    const reset = async () => {
+        await service.reset();
+    };
+
+    /**
+     * Executes the entire Pa11y CI sequence, calling all reporter functions.
+     *
+     * @public
+     * @instance
+     */
+    const runAll = async () => {
+        await service.runAll();
+    };
+
     return {
+        reset,
         runAll
     };
 };

package/lib/config.js

@@ -20,7 +20,7 @@ const normalizeConfig = (config) => {
 };
 
 /**
- * Factory function that returns a config object for managing PA11y CI
+ * Factory function that returns a config object for managing Pa11y CI
  * configuration including defaults and determining the consolidated
  * configuration for each URL.
  *

package/lib/formatter.js

@@ -6,6 +6,9 @@
  * @module formatter
  */
 
+const isError = issues => issues.length === 1 && Object.keys(issues[0]).length === 1
+    && issues[0].message;
+
 /**
  * Converts Pa11y CI JSON output to an equivalent Pa11y CI object,
  * allowing JSON result files to be used for reporter interface
@@ -25,13 +28,7 @@ const convertJsonToResultsObject = jsonResults => {
 
     for (const url of Object.keys(jsonResults.results)) {
         const issues = jsonResults.results[url];
-        let formattedIssues;
-        if (issues.length === 1 && Object.keys(issues[0]).length === 1 && issues[0].message) {
-            formattedIssues = [new Error(issues[0].message)];
-        }
-        else {
-            formattedIssues = issues;
-        }
+        const formattedIssues = isError(issues) ? [new Error(issues[0].message)] : issues;
         results.results[url] = formattedIssues;
     }
 
@@ -63,4 +60,3 @@ const getPa11yResultsFromPa11yCiResults = (url, results) => {
 
 module.exports.convertJsonToResultsObject = convertJsonToResultsObject;
 module.exports.getPa11yResultsFromPa11yCiResults = getPa11yResultsFromPa11yCiResults;
-

package/lib/pa11yci-machine.js

@@ -0,0 +1,68 @@
+'use strict';
+
+const { createMachine, assign } = require('xstate');
+
+const pa11yciMachine = createMachine(
+    {
+        id: 'pa11yci-runner',
+        initial: 'init',
+        context: {
+            urlIndex: 0,
+            urls: []
+        },
+        states: {
+            init: {
+                entry: 'setInitialUrlIndex',
+                on: {
+                    NEXT: { target: 'beforeAll' }
+                }
+            },
+            beforeAll: {
+                on: {
+                    NEXT: [
+                        { target: 'beginUrl', cond: 'hasUrls' },
+                        { target: 'afterAll' }
+                    ],
+                    RESET: { target: 'init' }
+                }
+            },
+            beginUrl: {
+                on: {
+                    NEXT: { target: 'urlResults' },
+                    RESET: { target: 'init' }
+                }
+            },
+            urlResults: {
+                on: {
+                    NEXT: [
+                        { target: 'afterAll', cond: 'isLastUrl' },
+                        { target: 'beginUrl', actions: 'incrementUrl' }
+                    ],
+                    RESET: { target: 'init' }
+                }
+            },
+            afterAll: {
+                on: {
+                    RESET: { target: 'init' }
+                }
+            }
+        }
+    },
+    {
+        actions: {
+            incrementUrl: assign({
+                urlIndex: (context) => context.urlIndex + 1
+            }),
+            setInitialUrlIndex: assign({
+                urlIndex: () => 0
+            })
+        },
+        guards: {
+            hasUrls: (context) => context.urls.length > 0,
+            isLastUrl: (context) =>
+                context.urlIndex === context.urls.length - 1
+        }
+    }
+);
+
+module.exports = pa11yciMachine;

package/lib/pa11yci-service.js

@@ -0,0 +1,139 @@
+'use strict';
+
+const { interpret } = require('xstate');
+const machine = require('./pa11yci-machine');
+
+const RunnerStates = Object.freeze({
+    beforeAll: 'beforeAll',
+    beginUrl: 'beginUrl',
+    urlResults: 'urlResults',
+    afterAll: 'afterAll'
+});
+const finalState = RunnerStates.afterAll;
+
+/**
+ * Gets the initial pa11yci-runner state machine context given an array of URLs.
+ *
+ * @private
+ * @param   {Array}  urls Array of URLs.
+ * @returns {object}      The initial state machine context.
+ */
+const getInitialContext = urls => ({
+    urlIndex: 0,
+    urls
+});
+
+/**
+ * Checks the state to determine whether it has an associated URL.
+ *
+ * @private
+ * @param   {RunnerStates} state The state to check.
+ * @returns {boolean}            True if the state has an associated url.
+ */
+const hasUrl = state => state === RunnerStates.beginUrl || state === RunnerStates.urlResults;
+
+/**
+ * Factory function that return a pa11yci-runner service.
+ *
+ * @public
+ * @static
+ * @param   {Array}  urls    Array of URLs.
+ * @param   {object} actions Actions object with functions to execute for each event.
+ * @returns {object}         A pa11yci-runner service.
+ */
+// eslint-disable-next-line max-lines-per-function
+const serviceFactory = (urls, actions) => {
+    let pendingCommand;
+    const currentContext = {
+        state: undefined,
+        url: undefined
+    };
+
+    // Create service from pa11yci-machine with context, setup
+    // transition event handler, and start service
+    const service = interpret(machine.withContext(getInitialContext(urls)));
+    service.onTransition(async (state) => {
+        // Save the current state and url for use in manual transitions.
+        // The state machine only increments the url index, so use that
+        // to get the url from the original urls array.
+        currentContext.state = state.value;
+        currentContext.url = hasUrl(currentContext.state)
+            ? urls[state.context.urlIndex] : undefined;
+
+        if (pendingCommand) {
+            // Do not take any action in init state
+            if (currentContext.state !== 'init') {
+                await actions[currentContext.state](currentContext.url);
+            }
+            pendingCommand.resolve();
+            pendingCommand = undefined;
+        }
+    });
+    service.start();
+
+    /**
+     * Sends the NEXT event to the pa11yci-runner service. Resolves when
+     * the next state has been reached and the reporter event raised.
+     *
+     * @private
+     * @returns {Promise<void>} Promise that indicates a pending state change.
+     */
+    const next = () => {
+        return new Promise((resolve, reject) => {
+            pendingCommand = { resolve, reject };
+            service.send({ type: 'NEXT' });
+        });
+    };
+
+    /**
+     * Sends the RESET event to the pa11yci-runner service. Resolves when
+     * the next state has been reached and the reporter event raised.
+     *
+     * @private
+     * @returns {Promise<void>} Promise that indicates a pending state change.
+     */
+    const resetInternal = () => {
+        return new Promise((resolve, reject) => {
+            pendingCommand = { resolve, reject };
+            service.send({ type: 'RESET' });
+        });
+    };
+
+    /**
+     * Resets the service to the init state.
+     *
+     * @public
+     * @instance
+     */
+    const reset = async () => {
+        await resetInternal();
+    };
+
+    /**
+     * Executes the entire Pa11y CI sequence, calling all reporter functions.
+     *
+     * @public
+     * @instance
+     */
+    const runAll = async () => {
+        if (currentContext.state === finalState) {
+            throw new Error(`runner must be reset before executing any other functions from the ${finalState} state`);
+        }
+
+        // Since this runs the entire sequence, send the NEXT event
+        // until the final state is reached.
+        while (currentContext.state !== finalState) {
+            // eslint-disable-next-line node/callback-return -- not a callback
+            await next();
+        }
+    };
+
+    return {
+        reset,
+        runAll
+    };
+};
+
+module.exports = {
+    serviceFactory
+};

package/lib/{reporterBuilder.js → reporter-builder.js}

@@ -27,6 +27,7 @@ const loadReporter = reporterName => {
  * @param   {object} config          The Pa11y CI configuration.
  * @returns {object}                 The reporter object.
  */
+// eslint-disable-next-line sonarjs/cognitive-complexity -- allow < 10
 const buildReporter = (reporterName, options, config) => {
     if (typeof reporterName !== 'string') {
         throw new TypeError('reporterName must be a string');
@@ -37,15 +38,15 @@ const buildReporter = (reporterName, options, config) => {
         if (typeof reporter === 'function') {
             reporter = reporter(options, config);
         }
-        reporterMethods.forEach(method => {
+        for (const method of reporterMethods) {
             if (typeof reporter[method] !== 'function') {
                 reporter[method] = noop;
             }
-        });
+        }
         return reporter;
     }
-    catch (err) {
-        throw new Error(`Error loading reporter: ${err.message}`);
+    catch (error) {
+        throw new Error(`Error loading reporter: ${error.message}`);
     }
 };
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pa11y-ci-reporter-runner",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Pa11y CI Reporter Runner is designed to facilitate testing of Pa11y CI reporters. Given a Pa11y CI JSON results file and optional configuration it simulates the Pa11y CI calls to the reporter.",
   "main": "index.js",
   "scripts": {
@@ -35,14 +35,15 @@
   },
   "homepage": "https://gitlab.com/gitlab-ci-utils/pa11y-ci-reporter-runner#readme",
   "devDependencies": {
-    "@aarongoldenthal/eslint-config-standard": "^11.0.0",
-    "eslint": "^8.8.0",
-    "jest": "^27.4.7",
+    "@aarongoldenthal/eslint-config-standard": "^12.0.2",
+    "eslint": "^8.9.0",
+    "jest": "^27.5.1",
     "jest-junit": "^13.0.0",
-    "markdownlint-cli": "^0.30.0",
+    "markdownlint-cli": "^0.31.1",
     "pa11y-ci-reporter-cli-summary": "^1.0.1"
   },
   "dependencies": {
-    "lodash": "^4.17.21"
+    "lodash": "^4.17.21",
+    "xstate": "^4.30.2"
   }
 }