feat(jest): add jest accessibility matcher #9

mohanraj-r · 2020-04-28T21:32:06Z

Primary addition starts at the jest package

`jest`

Accessibility matcher for Jest

Setup
- Project level
- Test module level
Usage

Setup

The accessibility matcher helper APIs need to be registered with Jest before they can be used in tests.

Project level

You can set up the a11y matchers once at the project level to make it available to all the Jest tests in the project.
For an example look at the Integration tests.

Add a Jest setup file (e.g. jest-setup.js) and add the following code that registers the a11y matchers

const { registerA11yMatchers } = require('@sa11y/jest');
registerA11yMatchers();

Add/Modify Jest config at project root to invoke the Jest setup file as setup above.
In the jest.config.js at the root of your project, add:

module.exports = {
    setupFilesAfterEnv: ['<rootDir>/jest-setup.js'],
};

Test module level

Invoke registerA11yMatchers before using the accessibility matchers in the tests e.g.

import { registerA11yMatchers } from '@sa11y/jest';

beforeAll(() => {
    registerA11yMatchers();
});

Usage

import { recommended } from '@sa11y/preset-rules';
import { registerA11yMatchers } from '@sa11y/jest';

beforeAll(() => {
    registerA11yMatchers();
});

it('should be accessible', async () => {
    // Setup DOM to be tested for accessibility
    //...

    // assert that DOM is accessible (using extended preset-rule)
    await expect(document).toBeAccessible();

    // use recommended preset-rule
    await expect(document).toBeAccessible(recommended);
});

as per https://docs.npmjs.com/files/package.json#repository

as --fix option wasn't being passed to the eslint cmd

modify root jest dep version to match

and add links to existing docs in root readme

add type def, tests

to prevent failed commit process due to failed checks in staged files

github-actions · 2020-04-28T21:33:35Z

Coverage after merging feat/add_jest_integration into master

100.00%

Coverage Report

File	Branches	Funcs	Lines
packages/assert/src
assert.ts	100%	100%	100%
packages/format/src
format.ts	100%	100%	100%
packages/jest/src
jest.ts	100%	100%	100%
packages/preset-rules/src
a11yConfig.ts	100%	100%	100%
extended.ts	100%	100%	100%
index.ts	100%	100%	100%
recommended.ts	100%	100%	100%
packages/test-utils/src
index.ts	100%	100%	100%
jest-setup.ts	100%	100%	100%
test-data.ts	100%	100%	100%
utils.ts	100%	100%	100%

Fixes Error when using "await" with "toBeAccessible": "Unexpected await of a non-Promise (non-"Thenable") value"

that supports typescript among other things

to enable markdown eslint plugin to check them

github-actions · 2020-04-29T03:31:05Z

Coverage after merging feat/add_jest_integration into master

100.00%

Coverage Report

File	Branches	Funcs	Lines
packages/assert/src
assert.ts	100%	100%	100%
packages/format/src
format.ts	100%	100%	100%
packages/jest/src
jest.ts	100%	100%	100%
packages/preset-rules/src
a11yConfig.ts	100%	100%	100%
extended.ts	100%	100%	100%
index.ts	100%	100%	100%
recommended.ts	100%	100%	100%
packages/test-utils/src
index.ts	100%	100%	100%
jest-setup.ts	100%	100%	100%
test-data.ts	100%	100%	100%
utils.ts	100%	100%	100%

github-actions · 2020-04-29T03:33:33Z

Coverage after merging feat/add_jest_integration into master

100.00%

Coverage Report

File	Branches	Funcs	Lines
packages/assert/src
assert.ts	100%	100%	100%
packages/format/src
format.ts	100%	100%	100%
packages/jest/src
jest.ts	100%	100%	100%
packages/preset-rules/src
a11yConfig.ts	100%	100%	100%
extended.ts	100%	100%	100%
index.ts	100%	100%	100%
recommended.ts	100%	100%	100%
packages/test-utils/src
index.ts	100%	100%	100%
jest-setup.ts	100%	100%	100%
test-data.ts	100%	100%	100%
utils.ts	100%	100%	100%

refactor lint run scripts

Add integration test package to test setup of a11y matcher

mohanraj-r

Thanks for the review @trevor-bliss
I have taken care of your comments. Can you review please.

mohanraj-r · 2020-05-04T22:06:39Z

packages/jest/src/matcher.ts

+ * @param config - A11yConfig to be used to test for accessibility. Defaults to extended.
+ */
+export async function toBeAccessible(
+    receivedDom: Document = document,


axe supports element references, node lists and css selectors - defaulting to the entire DOM.
Which of those would make sense? Or could we just make the first parameter a passthrough?
https://github.com/dequelabs/axe-core/blob/develop/doc/API.md#context-parameter

mohanraj-r · 2020-05-04T22:53:12Z

packages/jest/src/matcher.ts

+    receivedDom: Document = document,
+    config: A11yConfig
+): Promise<jest.CustomMatcherResult> {
+    return toBeAccessible(receivedDom, config);


Yeah was wondering the same after adding it. The marginal readability achieved with the With(Config) matcher is probably not worth the overhead. Removed.

mohanraj-r · 2020-05-04T22:53:27Z

packages/assert/src/assert.ts

-import { A11yConfig } from '@sa11y/preset-rules';
-import { Formatter, a11yResultsFormatter } from '@sa11y/format';
+import * as axe from 'axe-core';
+import { ElementContext, RunOptions } from 'axe-core';


Agree - felt weird for me too, fixed.

mohanraj-r · 2020-05-04T22:55:46Z

packages/jest/src/index.ts

+ */
+
+export { toBeAccessible, toBeAccessibleWith } from './matcher';
+export { adaptA11yConfig, registerA11yMatchers } from './setup';


Right now the tests are using it - so it needs to be exported I guess?
But I have been thinking about its usefulness to consumers as well.. Right now with its limited scope, its probably not useful. But if we allowed consumers to register their own adapters that could be useful. But there isn't a clear use case for such a workflow right now.

mohanraj-r · 2020-05-04T23:19:02Z

packages/jest/README.md

+In the `jest.config.js` at the root of your project, add
+
+```javascript
+const { jestConfig } = require('@sa11y/jest');


@trevor-bliss In 2b18c4b I am trying to automate setup of the a11y matchers so that they can be setup once in a project instead of every test module. But I am not able to get it to work. Can you please take a look at see what I am missing.

I would simplify the jest config in the integration test package and work backwards from a working solution.

In packages/test-integ/jest.config.js, can you have the setupFilesAfterEnv option directly that points to a local file that calls expect.extend to add a trivial custom matcher?

Once you have that then start using the imports/exports until you get back to where you wanted to be.

Good suggestion, let me try that out - thanks.

@trevor-bliss Ran into some issues trying the config jest
I have opened an issue with info #11
If there are no other issues with this PR can we merge this while I continue working on the jest config? I can revert 2b18c4b from this PR and add it to another branch?

Yeah works for me. Approved the PR.

Thanks @trevor-bliss
Modified jest setup as per your suggestions in #11
Can you please review

github-actions · 2020-05-04T23:32:03Z

Coverage Report 🎉

Totals
Statements:	100% ( 44 / 44 )
Methods:	100% ( 15 / 15 )

change name of CI action to Lint, Test

as it is used only internally currently

add/modify tests

spelak-salesforce · 2020-05-05T21:09:22Z

@mohanraj-r , I'm working on testing the work in this Pull Request in existing jest tests from another repo, but I'm having a difficult time referencing @sa11y/jest and the other modules locally. I'll try again and let you know if I can test this Pull Request out.

mohanraj-r · 2020-05-05T23:18:57Z

@mohanraj-r , I'm working on testing the work in this Pull Request in existing jest tests from another repo, but I'm having a difficult time referencing @sa11y/jest and the other modules locally. I'll try again and let you know if I can test this Pull Request out.

Thanks a lot @spelak-salesforce
I was able to install it from my local git dir using the following commands

cd /tmp
git clone --single-branch --branch feat/add_jest_integration git@github.com:salesforce/sa11y.git
cd /tmp/sa11y && yarn install && yarn build
cd <back to project dir where we want to install sa11y jest>
yarn add /tmp/sa11y/packages/jest/

Please let me know if that works for you.

trevor-bliss

with a11y matcher api Fixes #11

for uniformity

mohanraj-r · 2020-05-07T22:05:40Z

@cordeliadillon I refactored the docs since your last review. Can you please look a quick look at them to make sure they make sense.

Fix incorrect integration test, add doc about async usage

trevor-bliss

🚢

mohanraj-r · 2020-05-13T02:10:24Z

Fixes #11 #8

Mohan Raj Rajamanickam added 18 commits April 8, 2020 17:29

build(root): update repository urls in package json files

d9f0b26

as per https://docs.npmjs.com/files/package.json#repository

test(rules,format): fix test names to follow convention

7a41187

feat(jest): add basic scaffolding for jest integration

483291c

build(root): fix lint:fix script

4eaaf65

as --fix option wasn't being passed to the eslint cmd

build(jest): add jest as a peer dependency

6630be3

modify root jest dep version to match

docs(root): add homepage fields in package json to point to readme

a91a3e0

and add links to existing docs in root readme

feat(jest): add scaffolding for jest expect matcher

51ec35d

improvement(jest): flesh out custom jest axe matcher

e8055fa

add type def, tests

build(jest): add jest matcher utils dep

54be107

build(root): add npm update checker util

7609b7b

build(root): update script to upgrade dependencies; upgrade dependencies

6c7e86d

improvement(jest): use matcher hint util to format message

f8649b2

build(root): check staged files before invoking commit process

b5bee0f

to prevent failed commit process due to failed checks in staged files

test(jest): fix dom lang setup, test names, err msgs

c7184e4

build(root): add eslint watcher package and watch scripts

1554fdf

feat(jest): add toBeAccessibleWith jest a11y matcher for use with config

ecbfbf9

feat(test-utils): add a test utilities package

2a1c1bf

refactor(test-utils): refactor packages to use the common code

ba71b58

Mohan Raj Rajamanickam added 5 commits April 28, 2020 17:30

build(root): add markdown link checker dep, scripts, config

2481a06

build(root): add eslint plugin to check code snippets in markdown files

37f5f8f

improvement(jest): fix return types on the matcher interface

28e628f

Fixes Error when using "await" with "toBeAccessible": "Unexpected await of a non-Promise (non-"Thenable") value"

build(root): upgrade to next version of eslint markdown plugin

3531458

that supports typescript among other things

docs(root): add typescript tag to code blocks in docs

3dbd29a

to enable markdown eslint plugin to check them

build(root): update dependencies

342f577

Mohan Raj Rajamanickam added 3 commits April 28, 2020 20:48

build(root): add plugin to generate table of contents for markdown files

a88ef4d

docs(root): update table of contents for all markdown docs

a832256

build(root): add eslint plugins to check imports, comment directives

97677cb

refactor lint run scripts

improvement(jest): add config to automate setup of a11y matchers

2b18c4b

Add integration test package to test setup of a11y matcher

mohanraj-r dismissed cordeliadillon’s stale review via 2b18c4b May 4, 2020 23:15

mohanraj-r commented May 4, 2020

View reviewed changes

ci: add missing build step to new github actions

56b4893

Mohan Raj Rajamanickam added 3 commits May 4, 2020 16:54

ci(github action): change pr title check to install only req deps

3889075

change name of CI action to Lint, Test

refactor(jest): remove adaptA11yConfig from package level direct export

eca6850

as it is used only internally currently

improvement(jest): add ability to check HTML elements for accessibility

6eb2a3b

add/modify tests

build(jest): fix main entry point in jest package.json

85609d3

trevor-bliss previously approved these changes May 7, 2020

View reviewed changes

mohanraj-r dismissed trevor-bliss’s stale review via 85609d3 May 7, 2020 07:34

Mohan Raj Rajamanickam added 5 commits May 7, 2020 11:26

build: add ts-cleaner to clean dist files

36b0087

test(jest): add integration test package to test jest config setup

cbbe288

with a11y matcher api Fixes #11

refactor(test-integration): rename test-integ to test-integration

a6662f6

docs: add/refactor docs

e4c2717

docs: change code block types in docs from ts to js

97249c9

for uniformity

test(jest): add doc/tests for checking html elem with jest

9b1aa3b

Fix incorrect integration test, add doc about async usage

mohanraj-r requested review from trevor-bliss and cordeliadillon May 12, 2020 23:24

trevor-bliss approved these changes May 13, 2020

View reviewed changes

mohanraj-r merged commit fd586d1 into master May 13, 2020

mohanraj-r deleted the feat/add_jest_integration branch May 13, 2020 02:08

This was referenced May 13, 2020

Add ability to register a11y matcher in jest config once per project #11

Closed

Fix build failure in code coverage step on merge to master #8

Closed

mohanraj-r self-assigned this May 13, 2020

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(jest): add jest accessibility matcher #9

feat(jest): add jest accessibility matcher #9

mohanraj-r commented Apr 28, 2020 •

edited

Loading

github-actions bot commented Apr 28, 2020

github-actions bot commented Apr 29, 2020

github-actions bot commented Apr 29, 2020

mohanraj-r left a comment

mohanraj-r May 4, 2020

mohanraj-r May 4, 2020

mohanraj-r May 4, 2020

mohanraj-r May 4, 2020

mohanraj-r May 4, 2020

trevor-bliss May 5, 2020

mohanraj-r May 5, 2020

mohanraj-r May 7, 2020

trevor-bliss May 7, 2020

mohanraj-r May 7, 2020

github-actions bot commented May 4, 2020 •

edited

Loading

spelak-salesforce commented May 5, 2020

mohanraj-r commented May 5, 2020

trevor-bliss left a comment

mohanraj-r commented May 7, 2020

trevor-bliss left a comment

mohanraj-r commented May 13, 2020

feat(jest): add jest accessibility matcher #9

feat(jest): add jest accessibility matcher #9

Conversation

mohanraj-r commented Apr 28, 2020 • edited Loading

jest

Setup

Project level

Test module level

Usage

github-actions bot commented Apr 28, 2020

github-actions bot commented Apr 29, 2020

github-actions bot commented Apr 29, 2020

mohanraj-r left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

github-actions bot commented May 4, 2020 • edited Loading

Coverage Report 🎉

spelak-salesforce commented May 5, 2020

mohanraj-r commented May 5, 2020

trevor-bliss left a comment

Choose a reason for hiding this comment

mohanraj-r commented May 7, 2020

trevor-bliss left a comment

Choose a reason for hiding this comment

mohanraj-r commented May 13, 2020

mohanraj-r commented Apr 28, 2020 •

edited

Loading

`jest`

github-actions bot commented May 4, 2020 •

edited

Loading