Introduction

Often, we’ll run into those accessibility bugs that aren’t so clear to understand. Sometimes you’ll run into screen reader issues, or maybe it’s a browser bug, or perhaps it’s an operating system issue.

This guide is meant to help anyone trying to debug an accessibility issue or discover why a problem is occurring.

Please note: I’ll be sure to keep this a living document and post updates as I go.

 

The a11y debugging guide

The steps below are some I use to help me debug an accessibility issue. I follow these steps when I think I’ve found a screen reader compatibility bug or a rare bug that has no documentation online.

Prerequisite - You need to have a bug you're working on debugging

This document assumes you’ve found a bug already and are trying to debug it. So, this post requires some accessibility bugs filed into your bug tracking system.

For this post, if you need some inspiration, pretend you found a screen reader bug in the following environment:

  • Screen Reader: VoiceOver
  • Platform: IOS 15.5
  • Browser: Safari.

Step 1 – File the bug

File the bug. Ensure this bug is tracked and managed in your bug tracking system. Be sure to follow your organization’s standards for writing bugs. If you don’t have a standard bug writing template, here are some ideas below to get you started. I would recommend including details like:

  • Screen Reader
  • Platform
  • Browser
  • App Build
  • Steps to Reproduce
  • Any additional info

Step 2 – Check to see if this bug occurs anywhere else.

Goals: Determine if this issue is specific to your website or app.

  • We want to check if this issue occurs anywhere else. So we might want to visit another website with a similar feature. Go online and test out an accessible version. 

Requirements:

  • You must use the same environment and combination that the reporter described in the bug. Everything is the same. The only thing that is changing is the website or environment. We’re trying to evaluate someone with a similar coding implementation on a different website.

Step 3 – Check if this occurs using a different assistive technology.

Goal: determine if this issue is related to your assistive tool.

  • For example, let’s say this was a screen reader bug. We’re trying to determine if this issue is unique to that specific screen reader.

Requirements

  • You must use the same environment but now with a different tool (e.g., screen reader). The only thing that changes is the tool; everything else must remain the same. For example, if you tested with NVDA, now do a test with JAWS or VoiceOver.

Step 4- Determine if it’s a browser/environment-related issue.

Goal: To determine if this is related to a specific browser or browser version.

  • Is this only occurring in chrome? Or does it also happen in firefox or safari?

Requirements:

  • You must change the browser but keep everything else the same. Use the same operating system and screen reader, but change the browser.

Step 5 – Check to see if this is reproducible by someone else.

Ask a friend or fellow a11y specialist to reproduce the bug. Be sure to give them instructions that are clear and easy to follow, and be sure to include details or credentials.

  • Two people should be able to reproduce the bug, preferably three people.

If this is reproducible, move on to the next step.

Step 6 - Start disabling features and inspecting the code

First off, it’s critical to take a strategized approach here. We have to selectively disable things one by one to get an accurate baseline. If you disable multiple items, such as three things at once, how can you tell which one caused the issue?

This is a slow and steady process. Be patient. Listen to music or do some calming breathing exercises as you do this.

Step 7 - Disable CSS

Sometimes CSS affects what a screen reader says. Wow, crazy, right? A few examples of this are:

  • In safari, if you apply the CSS of “list-style-type: none,” on a list item, the VoiceOver screen reader will not announce the element as a list. Scott o Hara also wrote about this in his post “Fixing Lists.”
  • Developers sometimes use CSS to float things, leading to a reading order issue.
  • I’m unsure if this is still the case, but I believe using “display: flex; on a data table, the screen reader won’t announce the element like a table. This does not allow a screen reader user to use the table semantics and disables the screen reader’s table navigation feature.

Once you disable CSS. Retest the page to confirm if the issue is resolved. If it’s not, CSS is not the issue.

Step 8 - Disable JS

Sometimes Javascript might cause issues. It’s hard to be a little prescriptive here as so many potential javascript scenarios can happen. Anytime you manipulate content dynamically there’s a risk of issues.

Once you disable Javascript, retest the page to confirm if the issue is resolved. If it’s not, the JS is not the issue.

Step 9 - Disable Images

Surprisingly I have run into issues where images have caused problems. Specifically, an image within an Iframe was causing a focus trap because it was lazy-loaded. The screen reader couldn’t understand the image due to the lazy load.

Once you disable images, retest the page to confirm if the issue is resolved. If it’s not, the images are not the issue.

Step 10 - Disable/Remove other things/Isolate even more...

Suppose disabling CSS, JS, and Images didn’t resolve your problem. The following steps are to continue to disable things as you see fit.

Remember to do it consciously, a scientific method approach of cause and effect. Channel your inner jack skellington.

  • Start trimming down the DOM. For example, I might actually start deleting things one by one as I inspect the code to see if it’s causing issues. 
  • I would also copy the code and paste it into a separate environment. If I had a full page of 20 features, but my issue was on a specific table. I would extract the table and paste it into a codepen or onto a local HTML document and upload it to Github pages.
  • Isolate the page however you see fit.

Step 11 - Look on the web

Please note: This step might go up earlier in the process for you. It really depends on your experience . I have this on the last stage as I usually don’t have to look things up for most issues as I’ve experienced lots of issues. With that out of the way, let’s continue.

Time do some research online. We’ve exhausted our personal efforts.

  • Do a quick google search. It’s critical to search with specific details and keywords.
  • Look through the documentation or existing support pages. For example, if you go onto NVDA’s GitHub page, you can see existing issues for NVDA.
  • Search through common a11y slack channels like the web-a11y slack channel. I would also ask a question here.

Step 12 - File an external dependency bug

Please file a bug stating that it’s an external dependency bug. So let’s say you found an NVDA bug. You should go to the NVDA GitHub page (opens window) and say, “Hey, what the heck, there’s a bug.”

I would flag a bug there and see what they say. Maybe it’s a known issue, perhaps it’s a new bug, and you contributed to the community.

Here’s a table of all the potential places you might want to file an accessibility external dependency bug.

This table might require horizontal scrolling if you’re on mobile

Bug Tracker URL Bug Type
JAWS https://github.com/FreedomScientific/VFO-standards-support/issues

Screen Reader
NVDA Issues https://github.com/nvaccess/nvda Screen Reader
Apple Bug Reporter https://feedbackassistant.apple.com/ Screen Reader Assistive Technology Native iOS/OS X
Firefox https://bugzilla.mozilla.org/ Browser
Webkit Bugzilla including Safari https://bugs.webkit.org/ Browser
Android https://source.android.com/source/report-bugs.html OS
Open Radar http://www.openradar.me Screen Reader Assistive Technology Native iOS/OS X
Chromium Bug Tracker https://code.google.com/p/chromium/issues/list Browser
Internet Explorer Feedback https://connect.microsoft.com/ie/ (Microsoft Connect has been retired) Browser
TalkBack https://www.google.com/accessibility/get-in-touch.html Screen Reader
VoiceOver Apple welcomes comments and inquiries about the accessibility of their products. Please accessibility@apple.com. This is the email to use/recommended for best results regarding bugs and issues with VO specifically. Screen Reader
GNOME (Orca) Bugzilla https://bugzilla.gnome.org/enter_bug.cgi?product=orca Screen Reader
Dragon Naturally Speaking Tech Support Assistive Technology
ZoomText Ai Squared Support Assistive Technology
WAI-ARIA Specs W3C ARIA GitHub Repository Specs
Microsoft Edge Microsoft Edge Issue Tracker Browser

Conclusion

Debugging a bug can be tricky. Whether you’re a developer or an accessibility tester, having a guide to debugging problematic accessibility issues should help.

Suppose you notice anything in the blog post that can be improved. Please leave a comment or reach out to me via LinkedIn. I’m always open to feedback.

I hope this helps!

Please note: I plan to upload a video here in the coming weeks. My goal is to provide a video for all posts. So keep a lookout for that soon

Thanks! – Gio

Memes for fun

Casual programmer memes.

Man on phone named - Debugging. Text saying: I don't know where you are. I don't know how you work, but I will find you, and I will fix you.
2 panel Meme: On top a person pensive looking at computer saying "It doesn't work...why?" and underneath the same image but it says "it works.... why?"

Comments (Markdown Supported)

39 responses to “The Ultimate Guide to Debugging Accessibility Issues”

  1. Anna Smith says:

    Great article! Awesome job explaining step by step testing! Well done!!

  2. Caryl says:

    I’m curious if you’ve used the accessibility tree for debugging. Do you have any suggestions around that?

  3. Mike Gifford says:

    I would add steps to also look at upstream sources of the bug. Is the bug just something in your site, or does it occur in a library that you use. In complex modern sites there are lots of places that bugs can occur.

  4. Kate Kalcevich says:

    I’d add a caveat that it may not even be a bug, but just the way a particular screen reader works and users would totally be okay with it. The only way to figure that out is to talk to actual screen reader users. It can save you from going down a rabbit hole of debugging and fixing what isn’t even a real problem for users.

  5. I read this pагagraph fully regardіng the difference of hοttest and
    previߋus teϲhnologіes, it’s remarkable article.

  6. av subthai says:

    Tһanks for a marvelous posting! I genuinely enjoyеd reaԁing it, you can be a great author.I will remember tⲟ booкmark your blog
    and will often come back later in life. I want to encourage one to continue your great posts, haᴠe a
    nice dɑy!

  7. หี says:

    I thіnk this is ߋne of the most important information for me.

    And і’m gⅼad reading your aгticle. But should remаrk on some general things, The sіte style is
    perfect, the articles is really great : D. Good joƄ, cheers

  8. Ꮋi just wanted to give you a quick heads up and let you know a few of the imaɡes aren’t loadіng correctly.
    I’m not sure why but I think its a linking issue. I’ve trieɗ it іn two different internet browsers and both show the same outcome.

  9. Hi there, aⅼl is going nicely here and ofcoursе every
    one is sharing faсts, thаt’s truly good, keep up writing.

  10. Hi fantastic websіtе! Does running a blog like this take a massive amount work?
    I’ve virtually no knowledge of computer programming but I had bеen hoping to start my օwn blog
    soon. Anyway, if you have any ideas or tеchniques for new blog owners please share.
    I understand this is off subject nevertheless I just wanted to ask.
    Cһeеrs!

  11. Ꮋello, just wanted to mentiߋn, I liked this post. It was
    practical. Keep on posting!

  12. pornhub says:

    Thank yߋu, I have just been lߋoking for information about this topic for a long time and yoսrs is the best I have
    found out till now. But, what about the bottom line? Are you positіve concerning thе supply?

  13. av subthai says:

    Hi thеre, just ԝanted to tell you, I liked this blog
    post. It was helpful. Keep on poѕting!

  14. pornhub says:

    Haνing read this I thought it ԝas rather enlightening.

    I appreciate you finding the time ɑnd effort to put this infоrmative article together.
    I once again fіnd myself pеrsonally spendіng a significant
    amоunt of time bߋth reading and commenting.
    But so what, it was still worth it!

  15. Ꮃhat’s up tօ аll, it’s truly a good for me to go to sеe this website, it contains
    precious Information.

  16. Tһis is really interesting, You’re a very skilled blogger.
    I have joіned your rss feed and look forward to seeking more
    of y᧐ur wonderful ⲣost. Also, I have shared
    your websіte in my social networks!

  17. I don’t know whethеr it’s just me or if everyone else encountering prоblemѕ with your site.
    It appears as though sⲟme of the written teхt in your
    posts are running off the sϲreen. Can someone elѕe pleasе provide fеedback and let me know if
    this is haⲣpening to them as well? This migһt be ɑ iѕsue with my web
    browser because I’ѵе had this happen before. Cheers

  18. І’m amazed, I must say. Ꭱarely do I come acroѕs a
    blog that’s both equally eduϲativе and еntertaining,
    ɑnd without a dоubt, you have hit the nail on the head.
    The prⲟblem іs somethіng that not enough people are speaking intelligently about.
    I am very haρpy that I stumbled acrosѕ this in my hunt for something regarding thiѕ.

  19. This parɑgraph will assist the іnternet
    users for setting up new webpage or even a weblog from start to
    end.

  20. av says:

    Fantastic site y᧐u have here but I was wanting tօ know if you knew of any community forums that
    cover the same topics talҝed about in this article?
    I’d really like to Ƅe a part of community where I can get
    feed-ƅack from other knowleԀgeable people thаt share the same interest.

    If you havе any recommendations, please let me know.
    Thank you!

  21. Maɡnificent beat ! I would liкe to apprentice
    while you amend ʏour site, how cɑn i suƅscribe for a blog webѕite?
    The account aided me a acceptable deal. I had been tiny bit acԛuainteԀ of this your broadcast proѵided
    bright clear idea

  22. Hi! This is кіnd of off topіc but I need some help from an established blog.
    Is it difficult to set up your oԝn blog? I’m not very techincal but I can figսre things out pretty quick.

    I’m thinking about makіng my own but I’m not sure where to begin. Do you hаve any ideas or suggestions?
    With thanks

  23. wondеrful issues altogеther, you just received a new
    reader. What may you suggеѕt abⲟut your put up that you just made some dаys аgo?
    Any positive?

  24. It’s an гemarkable piece of writing designed for aⅼl the
    оnline users; they wіll take advantaɡe from it I am surе.

  25. ոatᥙrally like your web site however you have
    to take a look at the ѕpelling on ѕeveral of your posts.
    A numƄer of them are rife with spelling issues and I find it very Ƅothersome to inform the reality however I’ll surеly
    come again ɑgain.

  26. Hᥙrrah, that’s ԝhat I ԝas exploгing for, wһat a material!
    еxisting here at this weblog, thаnks admin of
    this website.

  27. pornhub says:

    Grеat post. I wаs checking continuoսsly this blog and I
    am impressed! Extremely uѕeful information particularly the last part 🙂 I
    care fⲟr such info a lot. I waѕ looking for thiѕ certain information for a
    l᧐ng time. Thank you аnd good luck.

  28. It’s impгessive that you are getting ideas from this article as wеll as from оur discussion made at this
    place.

  29. First off I ᴡant to say wonderful Ƅlog!
    I had ɑ quick qᥙestion in wһich I’d like to ask if ʏou
    do not mind. І was interested to know how yоu center yourself and clear yoᥙr heɑd
    before writing. I’ve had a difficult time clearing my mind in getting my ideas out.

    I truly do enjoy writing however it just seеms
    like the first 10 to 15 minutes are lost simply just trying to figure
    out how to begin. Any rеcommendations or tips? Thank you!

  30. vk ไทย says:

    Hi there, I do believe yoᥙr site could be having internet browser compatibility problems.
    When I take a look at your site in Safari, it looкs fіne however when opening іn IE, it has some οverlaρping issues.

    I simply wanted to proviԀe you with a quick heads up!
    Besidеs that, wonderful blog!

  31. Excellent post. I was checking continuously this blog and I’m impressed! Extremely useful information specially the last part 🙂 I care for such information a lot. I was seeking this certain info for a long time. Thank you and best of luck.

  32. Excellent article! We are linking t᧐ this great poѕt on our site.
    Keep up the good writing.

  33. animekimi says:

    What’s Going down i’m new to this, I stսmbled upon this I have found
    It positively useful and it has aided me out loads.
    I am hoping to give a contribution & aid different customers like its helрed me.
    Great job.

  34. eva elfie says:

    Ԝow, superb blog layout! How long have you been blogging
    for? yoս make blogging look easy. The overall looқ of yⲟur
    site is magnificent, as well as the content!

  35. javhd says:

    Helⅼo! I could have sԝorn I’ve visited this ѡeb sіte before
    but ɑfter going tһrough some of the posts I realized it’s new tο
    me. Nonetheless, I’m certаinly delighted I came aсгoss it ɑnd I’ll be bookmarking it and checking back frequentlү!

  36. Мy brother suggested I might like tһis website. He was totally right.
    This post truly made my day. You cann’t consider just how
    a lot time I had spent for thiѕ information!
    Tһanks!

  37. Ηmm is аnyone else encountering problems with the images on tһіs blog loading?
    I’m trying to deteгmine if its а problem on my еnd or if it’s the blog.

    Any feedback would be greatly appreciated.

  38. I likе the һeⅼpful info you prⲟvide
    in your articles. І’ll bookmark your wеblog and
    check agаin here freԛuently. I am quite certain I’ll learn many new stuff right here!

    Best of luck for the next!

Leave a Reply

Your email address will not be published.

Blog Categories

Search for a post

Blog Categories