Best Practices and Automated Accessibility Testing
Please ensure that Node.js 18.16 LTS as runtime environment and yarn as package manager are installed in your machine.
Run yarn install to install all the project dependencies.
In the root directory, you can run the following scripts:
Starts the application in development mode with hot-code reloading, API mock, error reporting, and more.
Run:
yarn startOpen http://localhost:3000 to view it in the browser.
The page will reload if you make edits. You will also see any lint errors in the console.
Creates an optimized production build of your application in the build folder.
yarn buildIt correctly bundles React in production mode and optimizes the build for the best performance.
The build is minified and the filenames include the hashes.
See the section about deployment for more information.
Starts the application in production mode. The application should be compiled with yarn build first.
yarn start:prodThe application will start at http://localhost:3000 by default.
Launches the test runner in the interactive watch mode.
yarn testTo launch the test runner and gets test coverage run:
yarn test:coverageSee the section about running tests for more information.
Determining whether a web application is accessible needs a well-rounded, holistic testing approach.
Automated testing is an integral part of our approach to accessibility testing and a great way to start weaving accessibility into a project, but it only captures about 40-50% of accessibility issues and many scenarios can’t be automated at all, requiring manual testing by using keyboard and screen readers, including mobile devices.
Automated accessibility tests definitely can’t catch everything, but it’s a valuable way to address easy wins and prevent basic fails.
Jest-axe is a custom Jest matcher for axe-core testing library. Because we are using TypeScript we need also to install the community maintained types package.
Install Jest-axe library and the required types by running:
npm install --save-dev jest-axe @types/jest-axeOnce you have installed Jest-axe in your project, we need to provide the global configuration to be used:
Create a new utils file: src\utils\tests.js with the following content.
In this case we configure it to validate onlyWCAG 2 A and 2.1 A rules:
import { configureAxe, toHaveNoViolations } from "jest-axe";
[...]
// Extend Jest expect with Axe tool
expect.extend(toHaveNoViolations);
// Jest-axe Utils
// Runner options for axe-core
// https://www.deque.com/axe/core-documentation/api-documentation/#options-parameter
const runAxe = configureAxe({
runOnly: ["wcag2a", "wcag21a"]
});
export { renderWithProviders, runAxe };Note: Check the axe-core options
Import the axe runner in you test file: e.g.: Home.test.tsx:
// Test Utils
import { renderWithProviders, runAxe } from "utils/tests";Add a new test to your file:
it("Renders with no accessibility violations", async () => {
const { container } = renderWithProviders(<Home />);
// Check a11y violations
const results = await runAxe(container);
expect(results).toHaveNoViolations();
});Run your tests with yarn test
The test will fail if the renderComponent method is updated by passing an undefined alternative text:
Expected the HTML found at $('img') to have no violations:
Received:
"Images must have alternate text (image-alt)"
Fix any of the following: Element does not have an alt attribute aria-label attribute does not exist or is empty aria-labelledby attribute does not exist, references elements that do not exist or references elements that are empty Element has no title attribute Element's default semantics were not overridden with role="none" or role="presentation"
You can find more information on this issue here: https://dequeuniversity.com/rules/axe/4.5/image-alt?application=axeAPI
Fix the accessibility issues for the images and run again to check that tests are passed successfully and verify that the errors have been fixed.