Adds documentation and help comments

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` environmental 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` environmental 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` environmental 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/index.ts

@@ -2,7 +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 { shouldUseMiddlewareReporter } from './should-use-middleware-reporter';
+export { useMiddlewareReporter } from './use-middleware-reporter';
 export {
   setupGlobalA11yHooks,
   teardownGlobalA11yHooks,

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

@@ -16,7 +16,8 @@ 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` environmental variable.
  *
  * If used with `setupGlobalA11yHooks` and the query param enabled, this will override
  * any `InvocationStrategy` passed to that function and force the audit.

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

@@ -14,9 +14,9 @@ class CliOptionsFilter extends Filter {
   }
 
   /**
-   * If `ENABLE_A11Y_MIDDLEWARE_REPORTER=true` or `ENABLE_A11Y_AUDIT=true` env vars are set,
-   * overwrite the corresponding values in `test-support/cli-options` during build-time so
-   * they can be referenced in the browser environment.
+   * 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) {