pa11y-ci-reporter-runner 1.0.0 → 2.0.1

package/README.md

@@ -1,6 +1,6 @@
 # Pa11y CI Reporter Runner
 
-Pa11y CI Reporter Runner is designed to facilitate testing of [Pa11y CI reporters](https://github.com/pa11y/pa11y-ci#write-a-custom-reporter). Given a Pa11y CI JSON results file and optional configuration it simulates the Pa11y CI calls to the reporter, including proper transformation of results and configuration data. Functionally, it's an emulation of the Pa11y CI side of the reporter interface with explicit control over execution of each step.
+Pa11y CI Reporter Runner is designed to facilitate testing of [Pa11y CI reporters](https://github.com/pa11y/pa11y-ci#write-a-custom-reporter). Given a Pa11y CI JSON results file and optional configuration it performs the Pa11y CI calls to the reporter, including proper transformation of results and configuration data. Functionally, it's an emulation of the Pa11y CI side of the reporter interface with explicit control over execution of each step.
 
 ## Installation
 
@@ -12,7 +12,7 @@ npm install pa11y-ci-reporter-runner
 
 ## Usage
 
-Pa11y CI Reporter Runner exports a factory function that creates a reporter runner. This function has four arguments:
+Pa11y CI Reporter Runner exports a factory function `createRunner` that creates a reporter runner. This function takes four arguments:
 
 - `resultsFileName`: Path to a Pa11y CI JSON results file.
 - `reporterName`: Name of the reporter to execute. Can be an npm module (e.g. `pa11y-ci-reporter-html`) or a path to a reporter file.
@@ -62,7 +62,7 @@ The reporter runner has five control functions:
   - `targetState`: The target state of the runner (any state above except `init`, or any valid value of the `RunnerStates` enum).
   - `targetUrl`: An optional target URL. If no URL is specified, the runner will stop at the first instance of the target state.
 - `runUntilNext(targetState, targetUrl)`: Provides the same functionality as `runUntil`, but execution ends at the state prior to the target state/URL, so that the target will execute if `runNext()` is subsequently called.
-- `reset()`: Resets the runner to the `init` state. This can be sent from any state.
+- `reset()`: Resets the runner to the `init` state and re-initializes the reporter. This can be sent from any state.
 
 These command are all asynchronous and must be completed before another is sent, otherwise an error will be thrown. In addition, once a run has been completed and the runner is in the `afterAll` state it must be `reset` before accepting any run command.
 
@@ -71,46 +71,59 @@ These command are all asynchronous and must be completed before another is sent,
 A complete example is provided below:
 
 ```js
-const { createRunner, RunnerStates } = require("pa11y-ci-reporter-runner");
+const { createRunner, RunnerStates } = require('pa11y-ci-reporter-runner');
 
-const resultsFileName = "pa11yci-results.json";
-const reporterName = "../test-reporter.js";
-const reporterOptions = { "isSomething": true };
+const resultsFileName = 'pa11yci-results.json';
+const reporterName = '../test-reporter.js';
+const reporterOptions = { isSomething: true };
 const config = {
-    defaults: {
-        timeout: 30000,
-    },
-    urls: [
-        "http://localhost:8080/page1-with-errors.html",
-        "http://localhost:8080/page1-no-errors.html",
-        {
-            url: "https://pa11y.org/timed-out.html",
-            timeout: 50,
-        },
-    ],
+  defaults: {
+    timeout: 30000
+  },
+  urls: [
+    'http://localhost:8080/page1-with-errors.html',
+    'http://localhost:8080/page1-no-errors.html',
+    {
+      url: 'https://pa11y.org/timed-out.html',
+      timeout: 50
+    }
+  ]
 };
 
 test('test all reporter functions', async () => {
-    const runner = createRunner(resultsFileName, reporterName, reporterOptions, config);
+  const runner = createRunner(
+    resultsFileName,
+    reporterName,
+    reporterOptions,
+    config
+  );
 
-    await runner.runAll();
+  await runner.runAll();
 
-    // Test reporter results
+  // Test reporter results
 });
 
 test('test reporter at urlResults state', async () => {
-    const runner = createRunner(resultsFileName, reporterName, reporterOptions, config);
-
-    await runner.runUntil(RunnerStates.beginUrl, 'http://localhost:8080/page1-no-errors.html');
-    let currentState = runner.getCurrentState();
-    // { state: "beginUrl", url: "http://localhost:8080/page1-no-errors.html" }
-    const nextState = runner.getNextState();
-    // { state: "urlResults", url: "http://localhost:8080/page1-no-errors.html" }
-    await runner.runNext();
-    currentState = runner.getCurrentState();
-    // { state: "urlResults", url: "http://localhost:8080/page1-no-errors.html" }
-
-    // Test reporter results
+  const runner = createRunner(
+    resultsFileName,
+    reporterName,
+    reporterOptions,
+    config
+  );
+
+  await runner.runUntil(
+    RunnerStates.beginUrl,
+    'http://localhost:8080/page1-no-errors.html'
+  );
+  let currentState = runner.getCurrentState();
+  // { state: "beginUrl", url: "http://localhost:8080/page1-no-errors.html" }
+  const nextState = runner.getNextState();
+  // { state: "urlResults", url: "http://localhost:8080/page1-no-errors.html" }
+  await runner.runNext();
+  currentState = runner.getCurrentState();
+  // { state: "urlResults", url: "http://localhost:8080/page1-no-errors.html" }
+
+  // Test reporter results
 });
 ```
 

package/index.js

@@ -1,3 +1,4 @@
+/* eslint-disable max-lines */
 'use strict';
 
 /**
@@ -21,7 +22,7 @@ const RunnerStates = require('./lib/runner-states');
  * @param   {string} fileName Pa11y CI JSON results file name.
  * @returns {object}          Pa11y CI results.
  */
-const loadPa11yciResults = fileName => {
+const loadPa11yciResults = (fileName) => {
     if (typeof fileName !== 'string') {
         throw new TypeError('fileName must be a string');
     }
@@ -29,8 +30,7 @@ const loadPa11yciResults = fileName => {
     try {
         const results = JSON.parse(fs.readFileSync(fileName, 'utf8'));
         return formatter.convertJsonToResultsObject(results);
-    }
-    catch (error) {
+    } catch (error) {
         throw new Error(`Error loading results file - ${error.message}`);
     }
 };
@@ -44,16 +44,14 @@ const loadPa11yciResults = fileName => {
  * @param   {object[]} values The urls array from configuration.
  * @returns {string[]}        Array of URL strings.
  */
-const getUrlList = values => {
+const getUrlList = (values) => {
     const result = [];
     for (const value of values) {
         if (typeof value === 'string') {
             result.push(value);
-        }
-        else if (typeof value.url === 'string') {
+        } else if (typeof value.url === 'string') {
             result.push(value.url);
-        }
-        else {
+        } else {
             throw new TypeError('invalid url element');
         }
     }
@@ -77,9 +75,13 @@ const validateUrls = (results, config) => {
     }
     const resultUrls = Object.keys(results.results);
     const configUrls = getUrlList(config.urls);
-    if (resultUrls.length !== configUrls.length ||
-        JSON.stringify(resultUrls.sort()) !== JSON.stringify(configUrls.sort())) {
-        throw new TypeError('config.urls is specified and does not match results');
+    if (
+        resultUrls.length !== configUrls.length ||
+        JSON.stringify(resultUrls.sort()) !== JSON.stringify(configUrls.sort())
+    ) {
+        throw new TypeError(
+            'config.urls is specified and does not match results'
+        );
     }
 };
 
@@ -90,7 +92,8 @@ const validateUrls = (results, config) => {
  * @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;
+const isError = (results) =>
+    results.length === 1 && results[0] instanceof Error;
 
 /**
  * Factory to create a pa11y-ci reporter runner that can execute
@@ -105,15 +108,34 @@ const isError = results => results.length === 1 && results[0] instanceof Error;
  * @returns {object}                 A Pa11y CI reporter runner.
  */
 // eslint-disable-next-line max-lines-per-function
-const createRunner = (resultsFileName, reporterName, options = {}, config = {}) => {
+const createRunner = (
+    resultsFileName,
+    reporterName,
+    options = {},
+    config = {}
+) => {
     const pa11yciResults = loadPa11yciResults(resultsFileName);
-
     validateUrls(pa11yciResults, config);
-
     const pa11yciConfig = createConfig(config);
-    const reporter = reporterBuilder.buildReporter(reporterName, options, pa11yciConfig.defaults);
     const urls = config.urls || Object.keys(pa11yciResults.results);
 
+    /**
+     * Create a new reporter with the given options and config
+     * (encapsulated as a function for consistency).
+     *
+     * @private
+     * @returns {object} The reporter associated with the runner.
+     */
+    const getReporter = () =>
+        reporterBuilder.buildReporter(
+            reporterName,
+            options,
+            pa11yciConfig.defaults
+        );
+
+    // Get the initial reporter
+    let reporter = getReporter();
+
     /**
      * Implements the runner beforeAll event, calling reporter.beforeAll.
      *
@@ -148,7 +170,13 @@ const createRunner = (resultsFileName, reporterName, options = {}, config = {})
         const urlConfig = pa11yciConfig.getConfigForUrl(url);
         await (isError(results)
             ? reporter.error(results[0], url, urlConfig)
-            : reporter.results(formatter.getPa11yResultsFromPa11yCiResults(url, pa11yciResults), urlConfig));
+            : reporter.results(
+                  formatter.getPa11yResultsFromPa11yCiResults(
+                      url,
+                      pa11yciResults
+                  ),
+                  urlConfig
+              ));
     };
 
     /**
@@ -171,10 +199,13 @@ const createRunner = (resultsFileName, reporterName, options = {}, config = {})
 
     // 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);
+    const service = serviceFactory(
+        Object.keys(pa11yciResults.results),
+        actions
+    );
 
     /**
-     * Resets the runner to the initial state.
+     * Resets the runner and reporter to the initial states.
      *
      * @async
      * @public
@@ -182,6 +213,7 @@ const createRunner = (resultsFileName, reporterName, options = {}, config = {})
      */
     const reset = async () => {
         await service.reset();
+        reporter = getReporter();
     };
 
     /**

package/lib/config.js

@@ -37,7 +37,9 @@ const configFactory = (config) => {
         }
 
         // Config URLs are validated against results, if specified, so will find a result.
-        const result = urls.find(urlObject => urlObject === url || urlObject.url === url);
+        const result = urls.find(
+            (urlObject) => urlObject === url || urlObject.url === url
+        );
         if (typeof result === 'string') {
             return defaults;
         }

package/lib/formatter.js

@@ -6,8 +6,10 @@
  * @module formatter
  */
 
-const isError = issues => issues.length === 1 && Object.keys(issues[0]).length === 1
-    && issues[0].message;
+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,
@@ -18,7 +20,7 @@ const isError = issues => issues.length === 1 && Object.keys(issues[0]).length =
  * @param   {object} jsonResults Pa11y CI JSON results.
  * @returns {object}             The equivalent Pa11y CI object.
  */
-const convertJsonToResultsObject = jsonResults => {
+const convertJsonToResultsObject = (jsonResults) => {
     const results = {
         total: jsonResults.total,
         passes: jsonResults.passes,
@@ -28,7 +30,9 @@ const convertJsonToResultsObject = jsonResults => {
 
     for (const url of Object.keys(jsonResults.results)) {
         const issues = jsonResults.results[url];
-        const formattedIssues = isError(issues) ? [new Error(issues[0].message)] : issues;
+        const formattedIssues = isError(issues)
+            ? [new Error(issues[0].message)]
+            : issues;
         results.results[url] = formattedIssues;
     }
 
@@ -59,4 +63,5 @@ const getPa11yResultsFromPa11yCiResults = (url, results) => {
 };
 
 module.exports.convertJsonToResultsObject = convertJsonToResultsObject;
-module.exports.getPa11yResultsFromPa11yCiResults = getPa11yResultsFromPa11yCiResults;
+module.exports.getPa11yResultsFromPa11yCiResults =
+    getPa11yResultsFromPa11yCiResults;

package/lib/pa11yci-machine.js

@@ -1,6 +1,5 @@
 'use strict';
 
-
 /**
  * State machine for pa11yci.
  *
@@ -69,8 +68,7 @@ const pa11yciMachine = createMachine(
         },
         guards: {
             hasUrls: (context) => context.urls.length > 0,
-            isLastUrl: (context) =>
-                context.urlIndex === context.urls.length - 1
+            isLastUrl: (context) => context.urlIndex === context.urls.length - 1
         }
     }
 );

package/lib/pa11yci-service.js

@@ -45,7 +45,7 @@ const StateTypes = Object.freeze({
  * @param   {Array}  urls Array of URLs.
  * @returns {object}      The initial state machine context.
  */
-const getInitialContext = urls => ({
+const getInitialContext = (urls) => ({
     urlIndex: 0,
     urls
 });
@@ -57,7 +57,8 @@ const getInitialContext = urls => ({
  * @param   {string}  state The state to check.
  * @returns {boolean}       True if the state has an associated url.
  */
-const hasUrl = state => state === RunnerStates.beginUrl || state === RunnerStates.urlResults;
+const hasUrl = (state) =>
+    state === RunnerStates.beginUrl || state === RunnerStates.urlResults;
 
 /**
  * Gets the URL for the given machine state.
@@ -66,8 +67,10 @@ const hasUrl = state => state === RunnerStates.beginUrl || state === RunnerState
  * @param   {object} machineState The machine state to check against.
  * @returns {string}              The current URL for the machine state.
  */
-const getUrlForState = machineState => hasUrl(machineState.value)
-    ? machineState.context.urls[machineState.context.urlIndex] : undefined;
+const getUrlForState = (machineState) =>
+    hasUrl(machineState.value)
+        ? machineState.context.urls[machineState.context.urlIndex]
+        : undefined;
 
 /**
  * Validates that the given state is a valid RunnerStates value. Throws if not.
@@ -92,8 +95,10 @@ const validateRunnerState = (state) => {
  * @returns {boolean}                    True if the context matches the target, otherwise false.
  */
 const isAtTarget = (machineState, targetState, targetUrl) => {
-    return machineState.value === targetState &&
-        (!targetUrl || getUrlForState(machineState) === targetUrl);
+    return (
+        machineState.value === targetState &&
+        (!targetUrl || getUrlForState(machineState) === targetUrl)
+    );
 };
 
 /**
@@ -103,7 +108,7 @@ const isAtTarget = (machineState, targetState, targetUrl) => {
  * @param   {object} machineState The machine state.
  * @returns {object}              The machine state summary.
  */
-const getStateSummary = machineState => ({
+const getStateSummary = (machineState) => ({
     state: machineState.value,
     url: getUrlForState(machineState)
 });
@@ -135,10 +140,14 @@ const serviceFactory = (urls, actions) => {
      */
     const validateCommandAllowed = () => {
         if (pendingCommand) {
-            throw new Error('runner cannot accept a command while another command is pending, await previous command');
+            throw new Error(
+                'runner cannot accept a command while another command is pending, await previous command'
+            );
         }
         if (currentState.value === finalState) {
-            throw new Error(`runner must be reset before executing any other functions from the ${finalState} state`);
+            throw new Error(
+                `runner must be reset before executing any other functions from the ${finalState} state`
+            );
         }
     };
 
@@ -165,10 +174,12 @@ const serviceFactory = (urls, actions) => {
             // Check next state and save for reference (machine.transition
             // is a pure function, so only retrieves the state)
             if (currentState.value !== finalState) {
-                nextState = machine.transition(currentState, MachineEvents.NEXT);
+                nextState = machine.transition(
+                    currentState,
+                    MachineEvents.NEXT
+                );
             }
-        }
-        finally {
+        } finally {
             // Ensure pending command is reset in all cases, including on error
             pendingCommand = false;
         }
@@ -206,7 +217,8 @@ const serviceFactory = (urls, actions) => {
      * @param   {StateTypes} stateType The state type.
      * @returns {object}               The state object for teh given type.
      */
-    const getState = stateType => stateType === StateTypes.current ? currentState : nextState;
+    const getState = (stateType) =>
+        stateType === StateTypes.current ? currentState : nextState;
 
     /**
      * Common function for executing runUntil and runUntilNext using the
@@ -226,8 +238,10 @@ const serviceFactory = (urls, actions) => {
         validateRunnerState(targetState);
 
         // Run until target or final state is achieved
-        while (!isAtTarget(getState(stateType), targetState, targetUrl)
-            && (getState(stateType)).value !== finalState) {
+        while (
+            !isAtTarget(getState(stateType), targetState, targetUrl) &&
+            getState(stateType).value !== finalState
+        ) {
             await sendEvent(MachineEvents.NEXT);
         }
 
@@ -235,7 +249,9 @@ const serviceFactory = (urls, actions) => {
         // not in the results and throw to indicate the command failed.
         if (!isAtTarget(getState(stateType), targetState, targetUrl)) {
             const urlString = targetUrl ? ` for targetUrl "${targetUrl}"` : '';
-            throw new Error(`targetState "${targetState}"${urlString} was not found`);
+            throw new Error(
+                `targetState "${targetState}"${urlString} was not found`
+            );
         }
     };
 

package/lib/reporter-builder.js

@@ -5,12 +5,11 @@ const path = require('path');
 const reporterMethods = ['beforeAll', 'begin', 'results', 'error', 'afterAll'];
 const noop = () => {};
 
-const loadReporter = reporterName => {
+const loadReporter = (reporterName) => {
     try {
         // eslint-disable-next-line node/global-require
         return require(reporterName);
-    }
-    catch {
+    } catch {
         // eslint-disable-next-line node/global-require
         return require(path.resolve(process.cwd(), reporterName));
     }
@@ -44,8 +43,7 @@ const buildReporter = (reporterName, options, config) => {
             }
         }
         return reporter;
-    }
-    catch (error) {
+    } catch (error) {
         throw new Error(`Error loading reporter: ${error.message}`);
     }
 };

package/package.json

@@ -1,14 +1,17 @@
 {
   "name": "pa11y-ci-reporter-runner",
-  "version": "1.0.0",
+  "version": "2.0.1",
   "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": {
-    "test": "jest --ci",
+    "hooks-pre-commit": "npm run lint && npm run prettier-check",
+    "hooks-pre-push": "npm audit --audit-level=critical && npm test",
+    "lint": "npm run lint-js && npm run lint-md",
     "lint-js": "eslint .",
     "lint-md": "markdownlint **/*.md --ignore node_modules --ignore Archive",
-    "lint": "npm run lint-js && npm run lint-md",
-    "push": "npm run lint && npm audit --audit-level=high && npm test"
+    "prettier-check": "prettier --check .",
+    "prettier-fix": "prettier --write .",
+    "test": "jest --ci"
   },
   "repository": {
     "type": "git",
@@ -24,7 +27,7 @@
   "author": "Aaron Goldenthal <npm@aarongoldenthal.com>",
   "license": "MIT",
   "engines": {
-    "node": "^12.20.0 || ^14.15.0 || >=16.0.0"
+    "node": "^14.15.0 || ^16.13.0 || >=18.0.0"
   },
   "files": [
     "index.js",
@@ -33,17 +36,18 @@
   "bugs": {
     "url": "https://gitlab.com/gitlab-ci-utils/pa11y-ci-reporter-runner/issues"
   },
-  "homepage": "https://gitlab.com/gitlab-ci-utils/pa11y-ci-reporter-runner#readme",
+  "homepage": "https://gitlab.com/gitlab-ci-utils/pa11y-ci-reporter-runner",
   "devDependencies": {
-    "@aarongoldenthal/eslint-config-standard": "^12.0.2",
-    "eslint": "^8.11.0",
-    "jest": "^27.5.1",
-    "jest-junit": "^13.0.0",
-    "markdownlint-cli": "^0.31.1",
-    "pa11y-ci-reporter-cli-summary": "^1.0.1"
+    "@aarongoldenthal/eslint-config-standard": "^15.0.0",
+    "eslint": "^8.21.0",
+    "jest": "^28.1.3",
+    "jest-junit": "^14.0.0",
+    "markdownlint-cli": "^0.32.1",
+    "pa11y-ci-reporter-cli-summary": "^2.0.0",
+    "prettier": "^2.7.1"
   },
   "dependencies": {
     "lodash": "^4.17.21",
-    "xstate": "^4.30.6"
+    "xstate": "^4.33.0"
   }
 }