How to: Accessibility Bug Reports

accessibility-bug-reporting.md

How to: Accessibility Bug Reports

Here's a run-down of steps I've used to capture and report accessibility bugs in software.

Environment

If you're using MacOS, I recommend setting up VMWare Fusion, even if you have separate Windows hardware. It's much easier to switch between environments for quick screen reader debugging with a local VM.

On MacOS

• Don't use VirtualBox, it doesn't work well with screen readers. VMWare Fusion works well.

brew cask install vmware-fusion

• Double the default RAM allocated to the VM in Fusion settings
• Download and Install Windows 8.1 with IE11 Image from https://developer.microsoft.com/en-us/microsoft-edge/tools/vms/

On Windows VM

NVDA is best with Firefox, JAWS is best with IE.

• Install NVDA for free (https://www.nvaccess.org/download/)
• Install JAWS trial version
• Set NVDA modifier to Caps Lock
• Install Firefox
• Switch NVDA to Microsoft Speech API
• Take a snapshot of the VM

Documenting

• Capture bugs with screen recording software that hooks into system audio. You can also capture gifs for keyboard issues.
• Make it easier for viewers by using a key-casting tool.
• Upload the bug report to a private youtube channel and turn on automated captions to get captions for the screen reader announcements. If you're using VoiceOver, you get the screen reader captions built in.

brew cask install screenflow
brew cask install keycastr
brew cask install licecap

Reporting

• Add a bug to project planning software (e.g. JIRA) and add a link to screencast, and/or or attach an animated gif with keycasting and captions.
• Label it as accessibility so that you can track accessibility issues globally across different backlogs in your organization.
• Frame the bug in terms of user impact. Ping a member of a team to prioritize the bug according to severity, impact, and relationship to other work.
• Add a link to user feedback and relevant guidelines where you can.

---

Example Ticket

Title

Submit button on Checkout page does not get Keyboard Focus

Description

When I use a keyboard to navigate the cart page, I can't place focus onto the Submit button.

Labels

• accessibility

Impact

This is an issue for people that use a keyboard only or switch access to navigate a page. It can prevent them from checking out, leading to reduced conversion and frustration.

Steps to Recreate

• Visit https://example.com/shop
• Add an item to you cart and checkout
• Use the keyboard tab key to navigate to the button labelled "Submit"
• Expected behavior: the focus moves to the "Submit" button and I can hit space to submit.
• Actual behavior: the focus moves past the button to links in the footer.

Recommendations

• Consider using a <button> or <input> element instead of a <div>, or else add tabindex='0' and attach event handlers to keyboard actions.

<attachment: screen recording>