{"id":13804578,"url":"https://github.com/ember-a11y/ember-a11y-testing","last_synced_at":"2025-05-15T10:02:34.718Z","repository":{"id":29848352,"uuid":"33393189","full_name":"ember-a11y/ember-a11y-testing","owner":"ember-a11y","description":"A suite of accessibility tests that can be run within the Ember testing framework","archived":false,"fork":false,"pushed_at":"2025-05-07T18:54:05.000Z","size":5268,"stargazers_count":136,"open_issues_count":10,"forks_count":56,"subscribers_count":6,"default_branch":"main","last_synced_at":"2025-05-07T19:43:52.366Z","etag":null,"topics":["a11y","a11y-testing","accessibility"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ember-a11y.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2015-04-04T03:39:11.000Z","updated_at":"2025-05-07T18:53:56.000Z","dependencies_parsed_at":"2024-11-30T21:01:06.320Z","dependency_job_id":"db7ea4ba-2fd2-40e2-af57-6157af923ca7","html_url":"https://github.com/ember-a11y/ember-a11y-testing","commit_stats":{"total_commits":565,"total_committers":52,"mean_commits":"10.865384615384615","dds":0.815929203539823,"last_synced_commit":"15bfba20b9a3d723cab56ff7489e6f1e7ff0ed21"},"previous_names":[],"tags_count":72,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ember-a11y%2Fember-a11y-testing","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ember-a11y%2Fember-a11y-testing/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ember-a11y%2Fember-a11y-testing/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ember-a11y%2Fember-a11y-testing/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ember-a11y","download_url":"https://codeload.github.com/ember-a11y/ember-a11y-testing/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254319716,"owners_count":22051072,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["a11y","a11y-testing","accessibility"],"created_at":"2024-08-04T01:00:50.575Z","updated_at":"2025-05-15T10:02:28.697Z","avatar_url":"https://github.com/ember-a11y.png","language":"TypeScript","funding_links":[],"categories":["Packages","Testing"],"sub_categories":["a11y","Utilities"],"readme":"# ember-a11y-testing\n\n[![CI Build](https://github.com/ember-a11y/ember-a11y-testing/workflows/CI/badge.svg)](https://github.com/ember-a11y/ember-a11y-testing/actions/workflows/ci.yml?query=workflow%3ACI)\n[![NPM Version](https://badge.fury.io/js/ember-a11y-testing.svg)](http://badge.fury.io/js/ember-a11y-testing)\n[![Ember Observer Score](https://emberobserver.com/badges/ember-a11y-testing.svg)](https://emberobserver.com/addons/ember-a11y-testing)\n\n`ember-a11y-testing` is a wrapper around [Deque Labs'](https://github.com/dequelabs)\n[axe-core](https://github.com/dequelabs/axe-core) accessibility testing engine.\nIt integrates into your testing environment using either a one-time setup, or in\nindividual tests using an `a11yAudit()` test helper.\n\n## Compatibility\n\n- Ember.js v4.0.0 or above\n- Ember CLI v3.8 or above\n- Node.js v16 or above\n- `@ember/test-helpers` v3.0.3 or above\n\nNote: we enforce a peerDependency of `@ember/test-helpers`. If you encounter the following message:\n\n```shell\nember-a11y-testing has the following unmet peerDependencies:\n  * @ember/test-helpers: `^2.0.0`; it was resolved to `x.x.x`\n```\n\nplease update your version of `@ember/test-helpers` in your package.json accordingly.\n\nNote: Users who are using Node \u003c= 14 in their apps should use `ember-a11y-testing@^5.2.1`.\n\n## Installation\n\n```bash\nember install ember-a11y-testing\n```\n\n## Usage\n\nUsage of `ember-a11y-testing` in your tests can be done in one of two ways:\n\n1. A one-time setup in your tests/test-helper.js file using `setupGlobalA11yHooks`\n1. In individual tests using the `a11yAudit` test helper.\n\n### axe Options\n\nWhen using the `a11yAudit` helper, you can pass in `axe-core` options that are passed to `axe.run`.\nThese options are documented in the [axe-core API docs](https://www.deque.com/axe/core-documentation/api-documentation/#user-content-options-parameter).\nThe rule definitions are documented on [dequeuniversity.com/rules](https://dequeuniversity.com/rules/axe/4.0).\n\nEach of the following sections individually details how to set aXe options for your tests.\n\n### `setupGlobalA11yHooks` Usage\n\nThe `setupGlobalA11yHooks` function is intended to be imported and invoked a single time in `tests/test-helper.js` for your entire test suite.\n\n```ts\nexport interface InvocationStrategy {\n  (helperName: string, label: string): boolean;\n}\n\nexport interface GlobalA11yHookOptions {\n  helpers: HelperName[];\n}\n\ntype HelperName =\n  | 'blur'\n  | 'click'\n  | 'doubleClick'\n  | 'fillIn'\n  | 'focus'\n  | 'render'\n  | 'scrollTo'\n  | 'select'\n  | 'tab'\n  | 'tap'\n  | 'triggerEvent'\n  | 'triggerKeyEvent'\n  | 'typeIn'\n  | 'visit';\n\nexport const DEFAULT_A11Y_TEST_HELPER_NAMES = [\n  'visit',\n  'click',\n  'doubleClick',\n  'tap',\n];\n\nexport function setupGlobalA11yHooks(\n  shouldAudit: InvocationStrategy,\n  audit: (...args: any[]) =\u003e PromiseLike\u003cvoid\u003e = a11yAudit,\n  options: GlobalA11yHookOptions = { helpers: DEFAULT_A11Y_TEST_HELPER_NAMES }\n);\n```\n\nThe `setupGlobalA11yHooks` function takes three parameters:\n\n- `shouldAudit`: An `InvocationStrategy` - a [predicate function](https://stackoverflow.com/a/1344021/769) that takes a `helperName` and a `label`, and returns a `boolean` indicating whether or not to perform the audit.\n- `audit` (optional): The audit function, which performs the `axe-core` audit, defaulting to `a11yAudit`. This allows you to potentially wrap the `a11yAudit` test helper with custom logic.\n- `options` (optional): Setup options, which allow you to specify after which test helpers to run the audit.\n\nUsing a custom `InvocationStrategy` implementation will allow you to maintain a high level of control over your test invocations. Examples of invocation strategies can be found in [this](https://github.com/ember-a11y/ember-a11y-testing/blob/50ef5f8fff4aa91d7a85b9feee5b1ce9bf380df9/tests/acceptance/setup-global-a11y-hooks-test.ts#L32) [repository's](https://github.com/ember-a11y/ember-a11y-testing/blob/50ef5f8fff4aa91d7a85b9feee5b1ce9bf380df9/tests/acceptance/setup-global-a11y-hooks-test.ts#L81) [tests](https://github.com/ember-a11y/ember-a11y-testing/blob/50ef5f8fff4aa91d7a85b9feee5b1ce9bf380df9/tests/acceptance/setup-global-a11y-hooks-test.ts#L135).\n\nTo use, import and invoke the global setup function, passing in your specific invocation strategy:\n\n```js\n// tests/test-helper.js\nimport Application from 'my-app/app';\nimport config from 'my-app/config/environment';\nimport { setApplication } from '@ember/test-helpers';\nimport { start } from 'ember-qunit';\nimport { setupGlobalA11yHooks } from 'ember-a11y-testing/test-support';\nsetApplication(Application.create(config.APP));\n\nsetupGlobalA11yHooks(() =\u003e true);\n\nstart();\n```\n\n:warning: It's important to note that you must also use the [`enableA11yAudit`](#force-running-audits) query parameter in order to force audits. This setting is required in addition to any invocation strategy you provide.\n\nBy default, audits will be run on `visit`, `click`, `doubleClick`, and `tap`. To add additional helpers to hook into, specify them by name in the `options.helpers` argument. Note that this option specifies the _complete_ set of helpers to hook into; to include the defaults you must import them and splat them into the array as shown below.\n\n```js\nimport {\n  setupGlobalA11yHooks,\n  DEFAULT_A11Y_TEST_HELPER_NAMES,\n} from 'ember-a11y-testing/test-support';\n\nsetupGlobalA11yHooks(() =\u003e true, {\n  helpers: [...DEFAULT_A11Y_TEST_HELPER_NAMES, 'render', 'tab'],\n});\n```\n\n#### Setting Options using `setRunOptions`\n\nYou can provide options to axe-core for your tests using the `setRunOptions` API. This API is helpful if you don't have access to the `a11yAudit` calls directly, such as when using the `setupGlobalA11yHooks`, or if you want to set the same options for all tests in a module.\n\nOptions can be set a few ways:\n\nGlobally:\n\n```javascript\n// tests/test-helper.js\nimport { setRunOptions } from 'ember-a11y-testing/test-support';\n\nsetRunOptions({\n  rules: {\n    region: { enabled: true },\n  },\n});\n```\n\nTest module level:\n\n```javascript\nimport { module, test } from 'qunit';\nimport { setRunOptions } from 'ember-a11y-testing/test-support';\n\nmodule('some test module', function (hooks) {\n  hooks.beforeEach(function () {\n    setRunOptions({\n      rules: {\n        region: { enabled: true },\n      },\n    });\n  });\n\n  // ...\n});\n```\n\nIndividual test level:\n\n```javascript\nimport { module, test } from 'qunit';\nimport { a11yAudit, setRunOptions } from 'ember-a11y-testing/test-support';\n\nmodule('some test module', function (hooks) {\n  test('some test', function (assert) {\n    setRunOptions({\n      rules: {\n        region: { enabled: true },\n      },\n    });\n\n    // ...\n    a11yAudit();\n    // ...\n  });\n\n  // ...\n});\n```\n\nWhen using `setRunOptions` during a test, the options you set are automatically reset when the test completes.\n\n### `a11yAudit` Usage\n\n`ember-a11y-testing` provides a test helper to run accessibility audits on specific tests within your test suite. The `a11yAudit` helper is an async test helper which can be used in a similar fashion to other `@ember/test-helpers` helpers:\n\nIn Application tests:\n\n```javascript\nimport { visit } from '@ember/test-helpers';\nimport { a11yAudit } from 'ember-a11y-testing/test-support';\n\nmodule('Some module', function () {\n  //...\n\n  test('Some test case', async function (assert) {\n    await visit('/');\n    await a11yAudit();\n    assert.ok(true, 'no a11y errors found!');\n  });\n});\n```\n\nThe helper is also able to be used in Integration/Unit tests like so:\n\n```javascript\nimport { render } from '@ember/test-helpers';\nimport { a11yAudit } from 'ember-a11y-testing/test-support';\n\n// ...elided for brevity\n\ntest('Some test case', function (assert) {\n  await render(hbs`{{some-component}}`);\n\n  let axeOptions = {\n    rules: {\n      'button-name': {\n        enabled: false,\n      },\n    },\n  };\n\n  await a11yAudit(this.element, axeOptions);\n\n  assert.ok(true, 'no a11y errors found!');\n});\n```\n\n#### Setting Options with `a11yAudit`\n\nThe helper can optionally accept a \"context\" on which to focus the audit as\neither a selector string or an HTML element. You can also provide a secondary\nparameter to specify axe-core options:\n\n```js\ntest('Some test case', async function (assert) {\n  let axeOptions = {\n    rules: {\n      'button-name': {\n        enabled: false,\n      },\n    },\n  };\n\n  await visit('/');\n  await a11yAudit(axeOptions);\n\n  assert.ok(true, 'no a11y errors found!');\n});\n```\n\nOr specify options as a single argument:\n\n```js\ntest('Some test case', async function (assert) {\n  let axeOptions = {\n    rules: {\n      'button-name': {\n        enabled: false,\n      },\n    },\n  };\n\n  await visit('/');\n  await a11yAudit('.modal', axeOptions);\n\n  assert.ok(true, 'no a11y errors found!');\n});\n```\n\n### Force Running audits\n\n`ember-a11y-testing` allows you to force audits if `enableA11yAudit` is set as a query param\non the test page or the `ENABLE_A11Y_AUDIT` environment variable is provided. This is useful if you want to conditionally run accessibility audits, such\nas during nightly build jobs.\n\nTo do so, import and use `shouldForceAudit` from `ember-a11y-testing`, as shown below.\n\n```javascript\n// `\u0026enableA11yAudit` set in the URL\nimport { a11yAudit, shouldForceAudit } from 'ember-a11y-testing/test-support';\n\ntest(\n  'Some test case',\n  await function (assert) {\n    await visit('/');\n\n    if (shouldForceAudit()) {\n      await a11yAudit();\n    }\n    assert.ok(true, 'no a11y errors found!');\n  }\n);\n```\n\n```javascript\n// No `enableA11yAudit` set in the URL\nimport { a11yAudit, shouldForceAudit } from 'ember-a11y-testing/test-support';\n\ntest(\n  'Some test case',\n  await function (assert) {\n    await visit('/');\n\n    if (shouldForceAudit()) {\n      await a11yAudit(); // will not run\n    }\n    // ...\n  }\n);\n```\n\nYou can also create your own app-level helper, which will conditionally check whether to run the audits or not:\n\n```javascript\nexport function a11yAuditIf(contextSelector, axeOptions) {\n  if (shouldForceAudit()) {\n    return a11yAudit(contextSelector, axeOptions);\n  }\n\n  return resolve(undefined, 'a11y audit not run');\n}\n```\n\n#### QUnit and Testem integration\n\nYou can setup a new configuration checkbox in QUnit and Testem by using the `setupQUnitA11yAuditToggle`.\nWhen the checkbox is checked, it will set `enableA11yAudit` as a query param.\n\nTo use, import and invoke the setup function, passing in your QUnit instance:\n\n```js\n// tests/test-helper.js\nimport Application from 'my-app/app';\nimport config from 'my-app/config/environment';\nimport * as QUnit from 'qunit';\nimport { setApplication } from '@ember/test-helpers';\nimport { start } from 'ember-qunit';\nimport { setupGlobalA11yHooks, setupQUnitA11yAuditToggle } from 'ember-a11y-testing/test-support';\nsetApplication(Application.create(config.APP));\n\nsetupGlobalA11yHooks(() =\u003e true);\nsetupQUnitA11yAuditToggle(QUnit);\n\nstart();\n```\n\n### Logging violations to the console\n\nThis addon provides the capability of summarizing all violations found during tests, and outputting those failures to the console once the test suite is completed. To enable this functionality, import `setupConsoleLogger` and invoke in your `tests/test-helper.js` file:\n\n```js\nimport Application from 'my-app/app';\nimport config from 'my-app/config/environment';\nimport { setApplication } from '@ember/test-helpers';\nimport { start } from 'ember-qunit';\nimport { setupConsoleLogger } from 'ember-a11y-testing/test-support';\n\nsetApplication(Application.create(config.APP));\n\nsetupConsoleLogger();\n\nstart();\n```\n\nExample:\n\n\u003cimg src=\"docs/assets/ember-a11y-testing-console-reporter.png\" alt=\"Console Logger Output Example\" width=\"600\" /\u003e\n\n### Test Middleware\n\nThis addon provides middleware - code that allows the browser to talk to the node process running the tests via testem. This is useful in scenarios such as internal compliance monitoring used to track accessibility grades.\n\nThe middleware reporter writes the results containing all violations detected in all tests to a JSON file stored in a directory, `ember-a11y-report`, in your application or addon's root directory.\n\n:warning: **Audit report files get generated in an additive manner, typically resulting in the `a11y-audit-report` directory growing in size as subsequent test suites are run. Environments with specific space size restrictions will require an explicit strategy to manage the deletion of older reports, as this addon no longer does so.**\n\nTo use the middleware reporter, import `setupMiddlewareReporter` and invoke in your `tests/test-helper.js` file:\n\n```js\nimport Application from 'my-app/app';\nimport config from 'my-app/config/environment';\nimport { setApplication } from '@ember/test-helpers';\nimport { start } from 'ember-qunit';\nimport { setupMiddlewareReporter } from 'ember-a11y-testing/test-support';\n\nsetApplication(Application.create(config.APP));\n\nsetupMiddlewareReporter();\n\nstart();\n```\n\nA 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.\n\n```js\nimport Application from 'my-app/app';\nimport config from 'my-app/config/environment';\nimport { setApplication } from '@ember/test-helpers';\nimport { start } from 'ember-qunit';\nimport {\n  setupMiddlewareReporter,\n  useMiddlewareReporter,\n} from 'ember-a11y-testing/test-support';\n\nsetApplication(Application.create(config.APP));\n\nif (useMiddlewareReporter()) {\n  // Only runs if `enableA11yMiddlewareReporter` is set in URL\n  setupMiddlewareReporter();\n}\n\nstart();\n```\n\nNote, as a convenience, `useMiddlewareReporter` automatically forces audits, thus explicitly specifying\nthe `enableA11yAudit` query param or the `ENABLE_A11Y_AUDIT` environment variable is unnecessary.\n\n### Development Usage\n\nWhile 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:\n\n- [**Accessibility Insights for Web**](https://accessibilityinsights.io/docs/en/web/overview) - Accessibility Insights for Web helps developers find and fix accessibility issues in web apps and sites. This browser extension for Chrome and the new Microsoft Edge runs on Windows, MacOS, and Linux computers.\n- [**Lighthouse**](https://developers.google.com/web/tools/lighthouse) - an open-source, automated tool for improving the quality of web pages. You can run it against any web page, public or requiring authentication. It has audits for performance, accessibility, progressive web apps, SEO and more.\n- [**Sa11y**](https://ryersondmp.github.io/sa11y/) - an accessibility quality assurance tool that visually highlights common accessibility and usability issues. Geared towards content authors, Sa11y indicates errors or warnings at the source with a simple tooltip on how to fix.\n- [**axe Chrome extension**](https://www.deque.com/axe/browser-extensions/) - a free axe browser extension ideal for development teams to test web applications to help identify and resolve common accessibility issues.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fember-a11y%2Fember-a11y-testing","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fember-a11y%2Fember-a11y-testing","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fember-a11y%2Fember-a11y-testing/lists"}