diff --git a/packages/jest-puppeteer-axe/README.md b/packages/jest-puppeteer-axe/README.md index b5e20cda390eb8..fc85725e27e9af 100644 --- a/packages/jest-puppeteer-axe/README.md +++ b/packages/jest-puppeteer-axe/README.md @@ -2,7 +2,7 @@ [Axe](https://www.deque.com/axe/) (the Accessibility Engine) API integration with [Jest](https://jestjs.io/) and [Puppeteer](https://pptr.dev/). -Defines Jest async matcher to check whether a given Puppeteer's page instance is accessible. +Defines Jest async matcher to check whether a given Puppeteer's page instance passes [Axe](https://www.deque.com/axe/) accessibility tests. ## Installation @@ -33,11 +33,11 @@ import '@wordpress/jest-puppeteer-axe'; In your Jest test suite add the following code to the test's body: ```js -test( 'checks accessibility of the test page', async () => { +test( 'checks the test page with Axe', async () => { // First, run some code which loads the content of the page. loadTestPage(); - await expect( page ).toBeAccessible(); + await expect( page ).toPassAxeTests(); } ); ``` @@ -46,11 +46,12 @@ It is also possible to pass optional Axe API options to perform customized check - `exclude` - CSS selector to to add the list of elements to exclude from analysis. ```js -test( 'checks accessibility of the test component excluding some button', async () => { +test( 'checks the test component with Axe excluding some button', async () => { + // First, run some code which loads the content of the page. loadPageWithTestComponent(); - await expect( page ).toBeAccessible( { + await expect( page ).toPassAxeTests( { include: '.test-component', exclude: '.some-button', } ); diff --git a/packages/jest-puppeteer-axe/src/index.js b/packages/jest-puppeteer-axe/src/index.js index 4333aae72c97ca..ccf1be7cf0a641 100644 --- a/packages/jest-puppeteer-axe/src/index.js +++ b/packages/jest-puppeteer-axe/src/index.js @@ -45,7 +45,9 @@ function formatViolations( violations ) { } /** - * Defines async matcher to check whether a given Puppeteer's page instance is accessible. + * Defines async matcher to check whether a given Puppeteer's page instance passes Axe accessibility tests. + * + * @see https://www.deque.com/axe/ * It is possible to pass optional Axe API options to perform customized check. * * @see https://github.com/dequelabs/axe-puppeteer @@ -59,7 +61,7 @@ function formatViolations( violations ) { * * @return {Object} A matcher object with two keys `pass` and `message`. */ -async function toBeAccessible( page, { include, exclude } = {} ) { +async function toPassAxeTests( page, { include, exclude } = {} ) { const axe = new AxePuppeteer( page ); if ( include ) { @@ -75,15 +77,15 @@ async function toBeAccessible( page, { include, exclude } = {} ) { const pass = violations.length === 0; const message = pass ? () => { - return this.utils.matcherHint( '.not.toBeAccessible' ) + + return this.utils.matcherHint( '.not.toPassAxeTests' ) + '\n\n' + 'Expected page to contain accessibility check violations.\n' + 'No violations found.'; } : () => { - return this.utils.matcherHint( '.toBeAccessible' ) + + return this.utils.matcherHint( '.toPassAxeTests' ) + '\n\n' + - 'Expected page to be accessible.\n' + + 'Expected page to pass Axe accessibility tests.\n' + 'Violations found:\n' + this.utils.RECEIVED_COLOR( formatViolations( violations ) @@ -97,5 +99,5 @@ async function toBeAccessible( page, { include, exclude } = {} ) { } expect.extend( { - toBeAccessible, + toPassAxeTests, } );