At Salesforce, we have a strong commitment to deliver apps that are usable by persons of all ability. Because of that, Salesforce follows the internationally recognized best practices in Section 508 of the Rehabilitation Act and the Web Content Accessibility Guidelines Version 2.0 (WCAG 2.0) level AA to the extent possible. You, as a developer, should follow the sample principle and make your content accessible to everyone, both when extending Salesforce products, and when building out of the platform. Accessibility is a big topic, and cannot be covered in a single blog post. However, in this post I’ll tell you the story of how we audited the accessibility of Sample Gallery apps and how we created automated DOM accessibility tests using sa11y, a set of open source libraries created by Salesforce.
Do Sample Gallery apps comply with WCAG 2.0?
Some weeks ago, my team was asked this question. At that point, we didn’t know to which level sample apps complied with accessibility standards. We knew that base components, as well as SLDS, try to follow accessibility standards as much as possible, and that we are using them heavily in our Sample Gallery apps. But, to which level the custom code that we had created complied with accessibility standards? To respond to this question, we decided to start a project: evaluate accessibility in Sample Apps!
Don’t know where to start?
There are many aspects of accessibility that need to be taken into account when designing, developing and testing apps. These include:
- The use of semantic structure of the DOM, and the utilization of ARIA attributes (if needed) to allow assistive technologies to correctly identify the markup meaning.
- The appropriate use of colors, with enough contrast and not relying on them as the only way to convey information.
- Making sure the app is fully accessible using the keyboard alone (i.e. no mouse!) with a correct implementation of focus.
When thinking about evaluating if these practices are being followed by an existing application, you may not know where to start. Luckily there are some tools out there that can help you in testing some of the requirements in an automated way. This is the case with sa11y.
sa11y to the rescue!
sa11y ensures your DOM follows a set of accessibility guidelines (WCAG) and best practices. This is a list of some of the issues that sa11y will help you with, and some of the issues you will have to manually test:
|Test for||@sa11y/jest||@sa11y/wdio||@sa11y/assert (generic JS)|
|Use of semantic structure of the DOM||Yes||Yes||Yes|
|Utilization of ARIA attributes||Yes||Yes||Yes|
|Offering text-based alternatives for images & icons||Yes||Yes||Yes|
|Navigation aids for screen readers||Yes||Yes||Yes|
|Not using deprecated elements that hurt a11y, as <blink>, <maarquee>, meta refresh or server side image maps||Yes||Yes||Yes|
|Appropriate use of colors, with enough contrast||No||Yes||No|
|Audio, Video elements||No||Yes||No|
|App support of keyboard navigation and appropriate focus implementation||No||No||No|
|Accessibility guidelines that apply only to mobile, as an adequate use of gestures||No||No||No|
Note that sa11y can be configured using three different presets, that will make the checks less or more strict.
As you can see, implementing sa11y is a good starting point. However, this doesn’t exempt you from knowing and understanding accessibility best practices, as well as from manually testing with specific interfaces, like the keyboard or a mobile phone.
Fun fact: sa11y is pronounced as “sally”, however, it’s written as sa-11-y (salesforce + a11y). a11y stands for accessibility and it’s a numeronym! Make sure to not confuse it with sally, as that’s a different npm module.
Integrating @sa11y/jest module
With all this in mind, we decided to give our first step and implement sa11y accessibility tests for Sample Gallery apps. This would help us find out some accessibility issues that the apps may have had. LWC unit tests are written with Jest, so our first step was to integrate the
@sa11y/jest module. These are the steps that we followed:
@sa11y/jest as it’s a dev dependency running the next command on the command line positioned at the project folder:
npm install -D @sa11y/jest
This adds a new line into your package.json
2. Create a setup file that registers the
toBeAccessible() sa11y matcher so that it can be used with
3. Include the newly created setup file into your generic jest config file.
Note that as sample apps use the
@salesforce/sfdx-lwc-jest package, the config file has code specifically for it. However, for an out of the box sa11y setup, the
setupFilesAfterEnv line is all that’s needed.
How to write good accessibility tests
Once done with the above, you can start creating Jest tests to see how accessibility guidelines are being enforced by the DOM that your components generate. This is fairly straightforward. To make sure an element doesn’t have any objective a11y defects (all the ones that we listed above!) you just call
Let’s say that we have the following component:
To test the component with sa11y, you must think about the different DOM configurations that the component can have. In this case, there are two sections that contain different DOM elements. So, what we can do, is to write a single test that configures the two sections as open. This way, all the possible DOM elements that can be rendered in the component will be evaluated.
Let’s take a look at a different example. Think about components in which DOM elements may have different states. For instance, imagine that you need to implement a custom expandable section using a button (don’t do this at home!).
In that case, you should test the two different states in which the button can be:
Here you have some additional tips to bear in mind:
- When running unit tests, base components are replaced by stubs that are part of the
@salesforce/sfdx-lwc-jestpackage. So, for instance, if you’re using lightning-accordion and lightning-accordion-section, Jest tests really use a lightning-accordion stub and a lightning-accordion-section stub. If you pay attention to these stubs, you’ll see they just contain a
<slot></slot>. This means that anything passed in via slots will render, and you don’t have to test an accordion with the different sections open, because indeed there’s no way to open a section in the stubs code, it’s a simple fake interface!
- Follow the blackbox testing approach when possible. Test in each component whatever belongs to that component. For example, in the next component, the parent component is responsible for testing only the lines highlighted in blue. It’s responsibility of
c-contact-tileto test its inner implementation.
After writing accessibility tests with sa11y for all our Sample Gallery apps, this is a summary of what we found:
|Sample App||# Accessibility Issues found||Description of the issues||Solution|
|Visualforce to LWC||22||Frames must have title attribute x 22||Add title attribute|
|LWC Recipes||1||Headings must not be empty||Add default heading content|
|Ebikes||2||Headings must not be empty
No alt text in image
|Add default heading content
Add alt text
|LWC Recipes OSS||1||<ul> and <ol> must only directly contain <li>, <script> or <template> elements||Modify markup to follow correct structure|
|Redwoods Insurance||1||Heading levels should only increase by one||Modify heading levels to increase by one|
As you can see in the table, we didn’t find many issues. This is due to the fact that sample apps make extensive use of base components (which remember, are stubs in our Jest tests), and use the least custom code as possible. At the same time, sample apps custom code follows SLDS guidelines and uses SLDS classes, so it’s not a surprise that we didn’t find lots of issues.
What we did next was to fix the issues found, adapting the custom code to follow accessibility best practices. Jest tests were already part of our CI jobs, so now, accessibility tests execute for every pull request, making sure that we’re not breaking the rules.
If you want to take a look at a concrete pull request to dig more into how we’ve implemented the tests and fixes, check out the E-bikes example.
Testing for accessibility
Accessibility is a huge topic, and it’s the responsibility of everyone in the software manufacturing chain. From UX designers, through developers, to QA engineers, everyone in the chain should be aware of accessibility best practices and understand how to apply them in their job.
Have you implemented or plan to implement sa11y? Let us know by writing a tweet and mentioning @SalesforceDevs, @SalesforceUX or @SalesforceA11y!
Finally, remember by using LWC base components and following SLDS guidelines as much as possible, you’ll get an accessible foundation for free. For Salesforce, accessibility is a priority, and we work hard to ensure that we comply with accessibility best practices.
About the author
Alba Rivas works as a Lead Developer Evangelist at Salesforce. She focuses on Lightning Web Components and Lightning adoption strategy. You can follow her on Twitter @AlbaSFDC.