Merge pull request #267 from ember-a11y/drewlee/options

Provide conditional usage for 'setupMiddlewareReporter'

.eslintrc.js

@@ -30,6 +30,7 @@ module.exports = {
         'ember-cli-build.js',
         'index.js',
         'setup-middleware.js',
+        'cli-options-filter.js',
         'node-tests/setup-middleware-test.js',
         'testem.js',
         'blueprints/*/index.js',

README.md

@@ -260,7 +260,7 @@ test('Some test case', async function (assert) {
 ### Force Running audits
 
 `ember-a11y-testing` allows you to force audits if `enableA11yAudit` is set as a query param
-on the test page. This is useful if you want to conditionally run accessibility audits, such
+on the test page or the `ENABLE_A11Y_AUDIT` environment variable is provided. This is useful if you want to conditionally run accessibility audits, such
 as during nightly build jobs.
 
 To do so, import and use `shouldForceAudit` from `ember-a11y-testing`, as shown below.
@@ -349,6 +349,28 @@ setupMiddlewareReporter();
 start();
 ```
 
+A helper function is available to use the middleware reporter conditionally, allowing interoperability between the default reporter and the middleware reporter. Import `useMiddlewareReporter` and apply as a check around the `setupMiddlewareReporter` function in `tests/test-helper.js`. The middleware reporter will now only be invoked when `enableA11yMiddlewareReporter` is set as a query param on the test page or the `ENABLE_A11Y_MIDDLEWARE_REPORTER` environment variable is provided.
+
+```js
+import Application from 'my-app/app';
+import config from 'my-app/config/environment';
+import { setApplication } from '@ember/test-helpers';
+import { start } from 'ember-qunit';
+import { setupMiddlewareReporter, useMiddlewareReporter } from 'ember-a11y-testing/test-support';
+
+setApplication(Application.create(config.APP));
+
+if (useMiddlewareReporter()) {
+  // Only runs if `enableA11yMiddlewareReporter` is set in URL
+  setupMiddlewareReporter();
+}
+
+start();
+```
+
+Note, as a convenience, `useMiddlewareReporter` automatically forces audits, thus explicitly specifying
+the `enableA11yAudit` query param or the `ENABLE_A11Y_AUDIT` environment variable is unnecessary.
+
 ### Development Usage
 
 While this addon previously included a number of components that would aid in identifying axe violations during development, those have been deprecated in favor of other, industry standard tools such as:

addon-test-support/cli-options.ts

@@ -0,0 +1,2 @@
+export const ENABLE_A11Y_MIDDLEWARE_REPORTER = false;
+export const ENABLE_A11Y_AUDIT = false;

addon-test-support/index.ts

@@ -2,6 +2,7 @@ export { default as a11yAudit } from './audit';
 export { default as a11yAuditIf } from './audit-if';
 export { setRunOptions, getRunOptions } from './run-options';
 export { setEnableA11yAudit, shouldForceAudit } from './should-force-audit';
+export { useMiddlewareReporter } from './use-middleware-reporter';
 export {
   setupGlobalA11yHooks,
   teardownGlobalA11yHooks,

addon-test-support/setup-middleware-reporter.ts

@@ -8,6 +8,7 @@ import {
 import { AxeResults, Result } from 'axe-core';
 import { setCustomReporter } from './reporter';
 import { DEBUG } from '@glimmer/env';
+import { setEnableA11yAudit } from './should-force-audit';
 
 export interface TestMetadata {
   testName?: string;
@@ -111,6 +112,8 @@ export function pushTestResult() {
 export function setupMiddlewareReporter() {
   setCustomReporter(middlewareReporter);
 
+  setEnableA11yAudit(true);
+
   QUnit.testDone(pushTestResult);
 
   QUnit.done(async function () {

addon-test-support/should-force-audit.ts

@@ -1,3 +1,5 @@
+import { ENABLE_A11Y_AUDIT } from './cli-options';
+
 export function setEnableA11yAudit(enabled: boolean = false) {
   const url = new URL(window.location.href, document.baseURI);
 
@@ -14,13 +16,14 @@ export function setEnableA11yAudit(enabled: boolean = false) {
 
 /**
  * Forces running audits. This functionality is enabled by
- * the presence of an `enableA11yAudit` query parameter passed to the test suite.
+ * the presence of an `enableA11yAudit` query parameter passed to the test suite
+ * or the `ENABLE_A11Y_AUDIT` environment variable.
  *
  * If used with `setupGlobalA11yHooks` and the query param enabled, this will override
  * any `InvocationStrategy` passed to that function and force the audit.
  */
 export function shouldForceAudit() {
   const url = new URL(window.location.href, document.baseURI);
 
-  return url.searchParams.get('enableA11yAudit') !== null;
+  return ENABLE_A11Y_AUDIT || url.searchParams.get('enableA11yAudit') !== null;
 }

addon-test-support/use-middleware-reporter.ts

@@ -0,0 +1,15 @@
+import { ENABLE_A11Y_MIDDLEWARE_REPORTER } from './cli-options';
+
+/**
+ * Utility to determine whether to use the middleware reporter. This functionality is
+ * enabled by the presence of the `enableA11yMiddlewareReporter` query parameter passed
+ * to the test suite or the `ENABLE_A11Y_MIDDLEWARE_REPORTER` environmental variable.
+ */
+export function useMiddlewareReporter() {
+  const url = new URL(window.location.href, document.baseURI);
+
+  return (
+    ENABLE_A11Y_MIDDLEWARE_REPORTER ||
+    url.searchParams.get('enableA11yMiddlewareReporter') !== null
+  );
+}

cli-options-filter.js

@@ -0,0 +1,41 @@
+'use strict';
+
+const Filter = require('broccoli-persistent-filter');
+
+const enableMiddlewareReporter =
+  process.env.ENABLE_A11Y_MIDDLEWARE_REPORTER === 'true';
+const enableA11yAudit = process.env.ENABLE_A11Y_AUDIT === 'true';
+
+const replacementToken = '$1 true';
+
+class CliOptionsFilter extends Filter {
+  constructor() {
+    super(...arguments);
+  }
+
+  /**
+   * If `ENABLE_A11Y_MIDDLEWARE_REPORTER=true` or `ENABLE_A11Y_AUDIT=true` environmental
+   * variables are specified, overwrite the corresponding values in `test-support/cli-options`
+   * at build-time to make them accessible in the browser environment.
+   * @override
+   */
+  processString(contents) {
+    if (enableMiddlewareReporter) {
+      contents = contents.replace(
+        /(ENABLE_A11Y_MIDDLEWARE_REPORTER = )false/,
+        replacementToken
+      );
+    }
+
+    if (enableA11yAudit) {
+      contents = contents.replace(
+        /(ENABLE_A11Y_AUDIT = )false/,
+        replacementToken
+      );
+    }
+
+    return contents;
+  }
+}
+
+module.exports = CliOptionsFilter;

index.js

@@ -5,6 +5,7 @@ const fs = require('fs');
 const VersionChecker = require('ember-cli-version-checker');
 const validatePeerDependencies = require('validate-peer-dependencies');
 const setupMiddleware = require('./setup-middleware');
+const CliOptionsFilter = require('./cli-options-filter');
 
 // The different types/area for which we have content for.
 const ALLOWED_CONTENT_FOR = ['test-head-footer'];
@@ -74,4 +75,15 @@ module.exports = {
       root: this.project.root,
     });
   },
+
+  /**
+   * Allow the option to enable a11y audit and middelware reporter using environmental
+   * variables. If set, environmental variable values are exposed to the browser
+   * environment via `test-support/cli-options`.
+   * @override
+   */
+  treeForAddonTestSupport(tree) {
+    const processedTree = new CliOptionsFilter(tree);
+    return this._super.treeForAddonTestSupport.call(this, processedTree);
+  },
 };

package.json

@@ -33,6 +33,7 @@
     "@ember/test-waiters": "^2.4.3",
     "axe-core": "^4.1.4",
     "body-parser": "^1.19.0",
+    "broccoli-persistent-filter": "^3.1.2",
     "date-and-time": "^1.0.0",
     "ember-auto-import": "^1.11.2",
     "ember-cli-babel": "^7.26.3",