From 4a94f19c373d1ec1fafeda08f29e348a9ecbfbcd Mon Sep 17 00:00:00 2001 From: Steve Calvert Date: Fri, 28 Aug 2020 13:14:00 -0700 Subject: [PATCH 1/4] task: Deprecates a11yAuditIf in favor of a single API --- addon-test-support/audit-if.ts | 12 +++++++++++- addon-test-support/audit.ts | 10 +++++++++- addon-test-support/setup-global-a11y-hooks.ts | 3 +-- .../{a11y-audit-test.js => a11y-audit-test.ts} | 14 +++++++++++--- .../{violations-test.js => violations-test.ts} | 0 ...a11y-audit-if-test.js => a11y-audit-if-test.ts} | 2 +- .../{a11y-audit-test.js => a11y-audit-test.ts} | 12 ++++++++++-- 7 files changed, 43 insertions(+), 10 deletions(-) rename tests/acceptance/{a11y-audit-test.js => a11y-audit-test.ts} (91%) rename tests/acceptance/{violations-test.js => violations-test.ts} (100%) rename tests/integration/helpers/{a11y-audit-if-test.js => a11y-audit-if-test.ts} (95%) rename tests/integration/helpers/{a11y-audit-test.js => a11y-audit-test.ts} (85%) diff --git a/addon-test-support/audit-if.ts b/addon-test-support/audit-if.ts index 88cd6ef8..5d32f056 100644 --- a/addon-test-support/audit-if.ts +++ b/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 { + 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); } diff --git a/addon-test-support/audit.ts b/addon-test-support/audit.ts index bd919329..742f8518 100644 --- a/addon-test-support/audit.ts +++ b/addon-test-support/audit.ts @@ -1,5 +1,5 @@ import QUnit from 'qunit'; -import { Promise } from 'rsvp'; +import { Promise, resolve } from 'rsvp'; import { run, AxeResults, @@ -11,6 +11,7 @@ import config from 'ember-get-config'; import formatViolation from 'ember-a11y-testing/utils/format-violation'; import violationsHelper from 'ember-a11y-testing/utils/violations-helper'; import { mark, markEndAndMeasure } from './performance'; +import { shouldForceAudit } from './should-force-audit'; type MaybeElementContext = ElementContext | RunOptions | undefined; @@ -131,6 +132,13 @@ export default function a11yAudit( ): PromiseLike { mark('a11y_audit_start'); + if (!shouldForceAudit()) { + return resolve( + undefined, + 'a11yAudit is disabled. To enable, please use the `enableA11yAudit` query param.' + ); + } + let [context, options] = _normalizeRunParams(contextSelector, axeOptions); document.body.classList.add('axe-running'); diff --git a/addon-test-support/setup-global-a11y-hooks.ts b/addon-test-support/setup-global-a11y-hooks.ts index 54471c72..59fa0112 100644 --- a/addon-test-support/setup-global-a11y-hooks.ts +++ b/addon-test-support/setup-global-a11y-hooks.ts @@ -1,7 +1,6 @@ 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'; let _unregisterHooks: HookUnregister[] = []; @@ -18,7 +17,7 @@ export function setupGlobalA11yHooks( ) { ['visit', 'click', 'doubleClick', 'tap'].forEach((helperName) => { let hook = _registerHook(helperName, 'end', async () => { - if (shouldForceAudit() && shouldAudit(helperName, 'end')) { + if (shouldAudit(helperName, 'end')) { await audit(getRunOptions()); } }); diff --git a/tests/acceptance/a11y-audit-test.js b/tests/acceptance/a11y-audit-test.ts similarity index 91% rename from tests/acceptance/a11y-audit-test.js rename to tests/acceptance/a11y-audit-test.ts index ed4e2151..773593d6 100644 --- a/tests/acceptance/a11y-audit-test.js +++ b/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(), + >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), + >a11yAudit(SELECTORS.failingComponent), /The page should have no accessibility violations. Violations:/, 'error message is correct' ); diff --git a/tests/acceptance/violations-test.js b/tests/acceptance/violations-test.ts similarity index 100% rename from tests/acceptance/violations-test.js rename to tests/acceptance/violations-test.ts diff --git a/tests/integration/helpers/a11y-audit-if-test.js b/tests/integration/helpers/a11y-audit-if-test.ts similarity index 95% rename from tests/integration/helpers/a11y-audit-if-test.js rename to tests/integration/helpers/a11y-audit-if-test.ts index 66a9e180..2058bf4d 100644 --- a/tests/integration/helpers/a11y-audit-if-test.js +++ b/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), + >a11yAuditIf(this.element), /The page should have no accessibility violations. Violations:/, 'error message is correct' ); diff --git a/tests/integration/helpers/a11y-audit-test.js b/tests/integration/helpers/a11y-audit-test.ts similarity index 85% rename from tests/integration/helpers/a11y-audit-test.js rename to tests/integration/helpers/a11y-audit-test.ts index 4c5b184e..3b99e977 100644 --- a/tests/integration/helpers/a11y-audit-test.js +++ b/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}}{{/axe-component}}`); await assert.rejects( - a11yAudit(this.element), + >a11yAudit(this.element), /The page should have no accessibility violations. Violations:/, 'error message is correct' ); From 835e1b70230ceb55e56d132d62c82965a2eee5a3 Mon Sep 17 00:00:00 2001 From: Steve Calvert Date: Fri, 28 Aug 2020 13:34:19 -0700 Subject: [PATCH 2/4] Updating README to remove references to a11yAuditIf --- README.md | 23 +++++++++++++++++------ 1 file changed, 17 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 77296b3b..cf6799cf 100644 --- a/README.md +++ b/README.md @@ -142,17 +142,28 @@ 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=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. ```javascript -import a11yAuditIf from 'ember-a11y-testing/test-support/audit-if'; +// &enableA11yAudit=true set in the URL +import { a11yAudit } 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 + await a11yAudit(); + assert.ok(true, 'no a11y errors found!'); +}); +``` + +```javascript +// &enableA11yAudit=false set in the URL +import { a11yAudit } from 'ember-a11y-testing/test-support'; + +test('Some test case', await function(assert) { + await visit('/'); + await a11yAudit(); // will not run assert.ok(true, 'no a11y errors found!'); }); ``` From ee274fd07a7d6ac3cf453ca684a52eef634794ad Mon Sep 17 00:00:00 2001 From: Steve Calvert Date: Fri, 28 Aug 2020 14:35:09 -0700 Subject: [PATCH 3/4] Fixing incorrect documentation --- README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index cf6799cf..122e033a 100644 --- a/README.md +++ b/README.md @@ -147,7 +147,7 @@ is set as a query param on the test page. This is useful if you want to conditio run accessibility audits, such as during nightly build jobs. ```javascript -// &enableA11yAudit=true set in the URL +// `&enableA11yAudit` set in the URL import { a11yAudit } from 'ember-a11y-testing/test-support'; test('Some test case', await function(assert) { @@ -158,13 +158,13 @@ test('Some test case', await function(assert) { ``` ```javascript -// &enableA11yAudit=false set in the URL +// No `enableA11yAudit` set in the URL import { a11yAudit } from 'ember-a11y-testing/test-support'; test('Some test case', await function(assert) { await visit('/'); await a11yAudit(); // will not run - assert.ok(true, 'no a11y errors found!'); + // ... }); ``` From 650eba186578c92cbd00fb1be30c6d810d8a00c5 Mon Sep 17 00:00:00 2001 From: Steve Calvert Date: Mon, 31 Aug 2020 10:13:27 -0700 Subject: [PATCH 4/4] Reverting some of the changes as per PR conversations --- README.md | 36 ++++++++++++++++--- addon-test-support/audit.ts | 10 +----- addon-test-support/setup-global-a11y-hooks.ts | 3 +- 3 files changed, 34 insertions(+), 15 deletions(-) diff --git a/README.md b/README.md index 122e033a..09e9a6ab 100644 --- a/README.md +++ b/README.md @@ -142,32 +142,58 @@ only real difference is Acceptance tests get automatic async handling. #### Optionally Running a11yAudit -Ember A11y Testing also allows you to run audits only if `enableA11yAudit=true` +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 // `&enableA11yAudit` set in the URL -import { a11yAudit } from 'ember-a11y-testing/test-support'; +import { a11yAudit, shouldForceAudit } from 'ember-a11y-testing/test-support'; test('Some test case', await function(assert) { await visit('/'); - await a11yAudit(); + + if (shouldForceAudit()) { + await a11yAudit(); + } assert.ok(true, 'no a11y errors found!'); }); ``` ```javascript // No `enableA11yAudit` set in the URL -import { a11yAudit } from 'ember-a11y-testing/test-support'; +import { a11yAudit, shouldForceAudit } from 'ember-a11y-testing/test-support'; test('Some test case', await function(assert) { await visit('/'); - await a11yAudit(); // will not run + + 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 diff --git a/addon-test-support/audit.ts b/addon-test-support/audit.ts index 742f8518..bd919329 100644 --- a/addon-test-support/audit.ts +++ b/addon-test-support/audit.ts @@ -1,5 +1,5 @@ import QUnit from 'qunit'; -import { Promise, resolve } from 'rsvp'; +import { Promise } from 'rsvp'; import { run, AxeResults, @@ -11,7 +11,6 @@ import config from 'ember-get-config'; import formatViolation from 'ember-a11y-testing/utils/format-violation'; import violationsHelper from 'ember-a11y-testing/utils/violations-helper'; import { mark, markEndAndMeasure } from './performance'; -import { shouldForceAudit } from './should-force-audit'; type MaybeElementContext = ElementContext | RunOptions | undefined; @@ -132,13 +131,6 @@ export default function a11yAudit( ): PromiseLike { mark('a11y_audit_start'); - if (!shouldForceAudit()) { - return resolve( - undefined, - 'a11yAudit is disabled. To enable, please use the `enableA11yAudit` query param.' - ); - } - let [context, options] = _normalizeRunParams(contextSelector, axeOptions); document.body.classList.add('axe-running'); diff --git a/addon-test-support/setup-global-a11y-hooks.ts b/addon-test-support/setup-global-a11y-hooks.ts index 59fa0112..6f76cfae 100644 --- a/addon-test-support/setup-global-a11y-hooks.ts +++ b/addon-test-support/setup-global-a11y-hooks.ts @@ -2,6 +2,7 @@ import { _registerHook, HookUnregister } from '@ember/test-helpers'; import { InvocationStrategy } from './types'; import { getRunOptions } from './run-options'; import a11yAudit from './audit'; +import { shouldForceAudit } from './should-force-audit'; let _unregisterHooks: HookUnregister[] = []; @@ -17,7 +18,7 @@ export function setupGlobalA11yHooks( ) { ['visit', 'click', 'doubleClick', 'tap'].forEach((helperName) => { let hook = _registerHook(helperName, 'end', async () => { - if (shouldAudit(helperName, 'end')) { + if (shouldForceAudit() && shouldAudit(helperName, 'end')) { await audit(getRunOptions()); } });