Skip to content

Instantly share code, notes, and snippets.

Show Gist options
  • Save robertknight/295736d5d07dbd405d2085acd5586880 to your computer and use it in GitHub Desktop.
Save robertknight/295736d5d07dbd405d2085acd5586880 to your computer and use it in GitHub Desktop.
Testing the Windows screenreader NVDA on a Mac

How to test NVDA screen reader behaviour on a Mac:

  1. Download Microsoft Edge VM from
  2. Download Virtualbox and import the Edge VM image.

Then in the VM:

  1. Install guest addons in the VM
  2. Download & install latest NVDA from
  3. Download & install SharpKeys and use it to map left an alternative key (eg. Left Ctrl) to the Insert key. This is needed because Macs do not typically have an “Insert” key which is the prefix for many NVDA commands.
  4. Log out and log in again for SharpKeys changes to take effect. Pressing Ctrl+N should now launch NVDA.
  5. Configure NVDA to use “Laptop” keyboard layout in the NVDA menu (NVDA+n) => Preferences => Keyboard Settings since the desktop layout relies on many keys which do not exist on a standard Mac keyboard.
  6. Install the Focus Highlight addon for NVDA which makes it easier to see what object currently has each of NVDA’s different focus targets.
  7. Enable the “Speech Viewer” log window via NVDA Menu => Tools => Speech Viewer so you can see what NVDA is saying more easily.

When testing, you may want to try different browsers and in particular Firefox which has historically been the best supported browser by NVDA.

Copy link

NVDA recommends pairing with Firefox for best outcomes. The recommendation is over a year old on their Community wiki, but I've seen it provide the best results in my own screen reader testing on Win7 and 10 in virtual and full OS environments.

Copy link

ptrin commented Jun 27, 2018

Copy link

This worked beautifully. Thank you!

Copy link

Shameless plug, but if you don't have time (or disk space) to deal with a VM, I built a cloud-based test lab so you can get started in a few seconds:

Copy link

A few performance tips:

  1. In Finder, browse to Applications/, control click, select Get Info > Open in Low Resolution.
  2. In VirtualBox:
    a. Select Machine > Settings > Storage > Add optical drive > VBoxGuestAdditions.iso > Choose.
    b. Select Machine > Settings > Display:
    i. Video Memory > 128 MB.
    ii. Graphics Controller > VBoxSVGA.
  3. When the virtual machine is running:
    a. Select View > Virtual Screen 1 > Scale to 100%.
    b. Select View > Auto-resize Guest Display.

Credit goes to this Redditor:

Copy link

Thank you for writing this up! Very helpful.

Copy link

kruzyk commented Feb 14, 2022

This helps me a lot:

Some folks have reported issues with setting vram for the vGPU on when using VMSVGA to the max supported (i.e. 256 megs) using the Virtual Box VM Manager GUI. You can side step this by just using the CLI command:
VBoxManage modifyvm "Name of VM" --vram 256

Also this from

For some newer Mac machines with touch bars, SharpKeys may not be the best solution. However, there is an alternate open source program called Karabiner Elements that is a powerful and stable keyboard customizer that should work if SharpKeys doesn't.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment