Deprecate a11yAuditIf

README.md

@@ -142,21 +142,58 @@ only real difference is Acceptance tests get automatic async handling.
 
 #### Optionally Running a11yAudit
 
-Ember A11y Testing also provides an `a11yAuditIf` helper which will only run
-audits if `enableA11yAudit=true` is set as a query param on the test page. This
-is useful if you want to conditionally run accessibility audits, such as during
-nightly build jobs.
+Ember A11y Testing also allows you to run audits only if `enableA11yAudit`
+is set as a query param on the test page. This is useful if you want to conditionally
+run accessibility audits, such as during nightly build jobs.
+
+This addon used to include a specific API to conditionally invoke the audits: `a11yAuditIf`. This
+helper would need to be included to separately conditionally invoke the helper. As of `4.0.0`, this
+helper is now deprecated in favor of providing the primitives necessary for you to control conditional
+invocation of the audits yourself.
+
+To do so, import and use `shouldForceAudit` from `ember-a11y-testing`, as shown below.
 
 ```javascript
-import a11yAuditIf from 'ember-a11y-testing/test-support/audit-if';
+// `&enableA11yAudit` set in the URL
+import { a11yAudit, shouldForceAudit } from 'ember-a11y-testing/test-support';
 
 test('Some test case', await function(assert) {
   await visit('/');
-  await a11yAuditIf(); // Only runs when enableA11yAudit=true is in the URL
+
+  if (shouldForceAudit()) {
+    await a11yAudit();
+  }
   assert.ok(true, 'no a11y errors found!');
 });
 ```
 
+```javascript
+// No `enableA11yAudit` set in the URL
+import { a11yAudit, shouldForceAudit } from 'ember-a11y-testing/test-support';
+
+test('Some test case', await function(assert) {
+  await visit('/');
+
+  if (shouldForceAudit()) {
+    await a11yAudit();  // will not run
+  }
+  // ...
+});
+```
+
+You can also create your own app-level helper, which will mimic the same functionality that was provide
+by `a11yAuditIf`:
+
+```javascript
+export function a11yAuditIf(contextSelector, axeOptions) {
+  if (shouldForceAudit()) {
+    return a11yAudit(contextSelector, axeOptions);
+  }
+
+  return resolve(undefined, 'a11y audit not run');
+}
+```
+
 ### Development Usage
 
 Usage in development is restricted to applications using Ember 1.13 and up, as it

addon-test-support/audit-if.ts

@@ -1,6 +1,7 @@
+import { ElementContext, RunOptions } from 'axe-core';
 import { resolve } from 'rsvp';
+import { deprecate } from '@ember/debug';
 import a11yAudit from './audit';
-import { ElementContext, RunOptions } from 'axe-core';
 import { shouldForceAudit } from './should-force-audit';
 
 /**
@@ -13,6 +14,15 @@ export default function a11yAuditIf(
   contextSelector?: ElementContext | RunOptions | undefined,
   axeOptions?: RunOptions | undefined
 ): PromiseLike<void> {
+  deprecate(
+    "ember-a11y-testing's `a11yAuditIf` is deprecated. Please use a11yAudit when using the `enableA11yAudit` query param",
+    false,
+    {
+      id: 'ember-a11y-testing-deprecated-a11y-audit-if',
+      until: '5.0.0',
+    }
+  );
+
   if (shouldForceAudit()) {
     return a11yAudit(contextSelector, axeOptions);
   }

addon-test-support/setup-global-a11y-hooks.ts

@@ -1,8 +1,8 @@
 import { _registerHook, HookUnregister } from '@ember/test-helpers';
 import { InvocationStrategy } from './types';
 import { getRunOptions } from './run-options';
-import { shouldForceAudit } from './should-force-audit';
 import a11yAudit from './audit';
+import { shouldForceAudit } from './should-force-audit';
 
 let _unregisterHooks: HookUnregister[] = [];
 

tests/acceptance/a11y-audit-test.js → tests/acceptance/a11y-audit-test.ts

@@ -1,7 +1,7 @@
 import { module, test } from 'qunit';
 import { visit } from '@ember/test-helpers';
 import { setupApplicationTest } from 'ember-qunit';
-import { a11yAudit } from 'ember-a11y-testing/test-support';
+import { a11yAudit, setEnableA11yAudit } from 'ember-a11y-testing/test-support';
 
 const SELECTORS = {
   passingComponent: '[data-test-selector="violations-page__passing-component"]',
@@ -11,13 +11,21 @@ const SELECTORS = {
 module('Acceptance | a11y audit', function (hooks) {
   setupApplicationTest(hooks);
 
+  hooks.beforeEach(function () {
+    setEnableA11yAudit(true);
+  });
+
+  hooks.afterEach(function () {
+    setEnableA11yAudit(false);
+  });
+
   test('a11yAudit should catch violations as an async helper', async function (assert) {
     assert.expect(1);
 
     await visit('/');
 
     await assert.rejects(
-      a11yAudit(),
+      <Promise<any>>a11yAudit(),
       /The page should have no accessibility violations. Violations:/,
       'error message is correct'
     );
@@ -32,7 +40,7 @@ module('Acceptance | a11y audit', function (hooks) {
     assert.ok(true, 'a11yAudit should not have discovered any issues');
 
     await assert.rejects(
-      a11yAudit(SELECTORS.failingComponent),
+      <Promise<any>>a11yAudit(SELECTORS.failingComponent),
       /The page should have no accessibility violations. Violations:/,
       'error message is correct'
     );

tests/integration/helpers/a11y-audit-if-test.js → tests/integration/helpers/a11y-audit-if-test.ts

@@ -25,7 +25,7 @@ module('Integration | Helper | a11yAuditIf', function (hooks) {
       setEnableA11yAudit(true);
 
       await assert.rejects(
-        a11yAuditIf(this.element),
+        <Promise<any>>a11yAuditIf(this.element),
         /The page should have no accessibility violations. Violations:/,
         'error message is correct'
       );

tests/integration/helpers/a11y-audit-test.js → tests/integration/helpers/a11y-audit-test.ts

@@ -2,11 +2,19 @@ import { module, test } from 'qunit';
 import { setupRenderingTest } from 'ember-qunit';
 import { render } from '@ember/test-helpers';
 import hbs from 'htmlbars-inline-precompile';
-import { a11yAudit } from 'ember-a11y-testing/test-support';
+import { a11yAudit, setEnableA11yAudit } from 'ember-a11y-testing/test-support';
 
 module('Integration | Helper | a11yAudit', function (hooks) {
   setupRenderingTest(hooks);
 
+  hooks.beforeEach(function () {
+    setEnableA11yAudit(true);
+  });
+
+  hooks.afterEach(function () {
+    setEnableA11yAudit(false);
+  });
+
   test('a11yAudit runs successfully with element context', async function (assert) {
     await render(hbs`{{#axe-component}}{{/axe-component}}`);
     await a11yAudit(this.element);
@@ -17,7 +25,7 @@ module('Integration | Helper | a11yAudit', function (hooks) {
     await render(hbs`{{#axe-component}}<button></button>{{/axe-component}}`);
 
     await assert.rejects(
-      a11yAudit(this.element),
+      <Promise<any>>a11yAudit(this.element),
       /The page should have no accessibility violations. Violations:/,
       'error message is correct'
     );