NvdaTestingDriver 0.2.0-beta

This is a prerelease version of NvdaTestingDriver.
dotnet add package NvdaTestingDriver --version 0.2.0-beta
NuGet\Install-Package NvdaTestingDriver -Version 0.2.0-beta
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="NvdaTestingDriver" Version="0.2.0-beta" />
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add NvdaTestingDriver --version 0.2.0-beta
#r "nuget: NvdaTestingDriver, 0.2.0-beta"
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
// Install NvdaTestingDriver as a Cake Addin
#addin nuget:?package=NvdaTestingDriver&version=0.2.0-beta&prerelease

// Install NvdaTestingDriver as a Cake Tool
#tool nuget:?package=NvdaTestingDriver&version=0.2.0-beta&prerelease

Nvda Testing Driver: Automate your tests with a screen reader

Introduction. What is NvdaTestingDriver?

NvdaTestingDriver is a package that will allow us to perform functional tests of accessibility, using the screen reader NVDA. The package is able to start the screen reader (it does not need installation, as it already includes a portable version), and handle it as if it were the user himself who interacts with it, sending it commands and receiving the textual responses. With these responses, we will be able to prepare our tests, which will fail if the texts received do not correspond to what we consider the reader should pronounce at all times.

NvdaTestingDriver, although it is a NetStandard package, is only compatible with Windows (7 SP 1 versions onwards), as NVDA is a screen reader developed for this operating system.

What is a screen reader?

A screen reader is a software that is capable of identifying and interpreting what appears on a computer screen, and transferring it to the user by means of a voice synthesis or a Braille screen. Thus, this software allows a person who is blind or has low vision to operate a computer by being able to read what is happening on the screen at all times.

But for the screen reader to be able to read an application or website, it has to be accessible.

Starting from this premise, NVDA is a wonderful tool to test if our website is accessible or not, since the reader must be able to convert all our website to text that a blind or low vision person can read: images, site structure, forms ...

How does Nvda Testing Driver work?

Nvda Testing Driver will allow us to run the NVDA screen reader automatically, manage it from .Net, obtain the textual responses that the screen reader would announce aloud, and compare those answers with the texts that we expect the reader to pronounce, if the component to be tested works as expected.

So, for example, if we have a contact page, and we know that in the name edit box, NVDA should read: "Name: text edit", we could create a test that navigates to the contact page, positions itself over the edit box, gets the text that NVDA will return when positioned over it, and compares it with what we know it should pronounce. If the texts match, the component is read as expected, and the test passes. Otherwise, something has failed, the texts don't match, and the test will fail.

This example is very simple, but imagine a more complex component, such as a tree view that we have programmed with Aria. If we manually check that this tree view works well with NVDA, we can create a test that positions itself over it, navigate expanding and collapsing nodes, and compare the texts returned by NVDA with what we know it should pronounce. So, if at any time during web development the tree view stops working properly, the automatic execution of the test will allow us to realize quickly, detect the bug and correct it, without having to manually check all pages to ensure that they still maintain a good level of accessibility with a screen reader. In one of the example tests you have a test that interacts with a tree view and guarantees that NVDA works correctly with it.

How do I get the texts that NVDA should pronounce to build my tests?

NVDA has a great tool called "Voice viewer". This tool will keep a log of everything NVDA pronounces during a session. So, to build our test, all we have to do is start the screen reader, open the "Voice Viewer" tool, navigate to the website, interact with the elements we want to test, and then copy the log of everything pronounced by NVDA and build our tests according to those texts.

NVDA commands

NVDA has a large number of orders to execute a multitude of actions. To facilitate interaction and prevent coding errors, this library includes, as already defined commands, the most relevant NVDA functions, written in several static classes within the NvdaTestingDriver.Commands.NvdaCommands namespace. Each class contains a category, as we can see in the NVDA help.

Execution flow

Instantiating a NvdaTestingDriver object

The first thing we have to do is instantiate the NvdaTestingDriver class. We can do this instantiation without parameters (NVDA will be loaded with the default options), or passing it a function that will receive as parameter the object NvdaOptions , which we can change to modify the default behavior of the screen reader. For example:

			var nvdaDriver = new NvdaDriver(opt =>
				opt.GeneralSettings.Language = NvdaTestingDriver.Settings.NvdaLanguage.English;

Start NVDA

The next step is to connect the driver, i.e. start NVDA and connect to it to control it.

await nvdaTestingDriver.ConnectAsync();

Interacting with NVDA

The third step is to interact with NVDA.

This library contains several methods for sending commands to NVDA and receiving textual responses from the screen reader. With the NVDA response, we will be able to make comparisons with the texts we expect to receive, and thus determine if any component is not behaving as it should.

Important: Remember that to make comparisons you must use the TextContains method of the NvdaTestHelper class, or, if you want the method to raise an AssertFailedException , use the TextContains method of the NvdaAssert class (NvdaTestingDriver.MSTest package).

Here we explain the most important methods:


This method will receive a command (it can be predefined or built manually indicating the combinations of keys to send), and will return the response that NVDA will verbalize as a result of that command.

For example:

string text = await nvdaDriver.SendCommandAndGetSpokenTextAsync(BrowseModeCommands.NextFormField);

This instruction will send the command BrowseModeCommands.NextFormField to NVDA (equivalent to sending the keystroke F, it will wait for NVDA to send a response, and it will return that response, which will be stored in the text variable. We can use that variable to make the necessary comparisons and make sure that the command responds as expected.


This method will receive a list of keys (they will be treated as a combination), and will return the response that NVDA will verbalize as a result of those keystrokes.

For example:

string text = await nvdaDriver.SendKeysAndGetSpokenTextAsync(Key.DownArrow);

This instruction will send the DownArrow key to NVDA, wait for NVDA to send a response, and return that response, which will be stored in the text variable. We can use that variable to make the necessary comparisons and make sure that the command responds as expected.

Disconnect and exit NVDA

The last step is to close the NVDA connection and quit the screen reader:

			await NvdaDriver.DisconnectAsync();

This command will disconnect the remote control to NVDA, and then exit the screen reader.

Since `NvdaTestingDriver` implements the `IDisposable` interface, if we include the instantiation of the class within a `using` block, when we close the block, the `Dispose` method will be executed, and it will call the `DisconnectAsync` method, closing the remote control and exiting NVDA.
Product Compatible and additional computed target framework versions.
.NET net5.0 was computed.  net5.0-windows was computed.  net6.0 was computed.  net6.0-android was computed.  net6.0-ios was computed.  net6.0-maccatalyst was computed.  net6.0-macos was computed.  net6.0-tvos was computed.  net6.0-windows was computed.  net7.0 was computed.  net7.0-android was computed.  net7.0-ios was computed.  net7.0-maccatalyst was computed.  net7.0-macos was computed.  net7.0-tvos was computed.  net7.0-windows was computed.  net8.0 was computed.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed. 
.NET Core netcoreapp2.0 was computed.  netcoreapp2.1 was computed.  netcoreapp2.2 was computed.  netcoreapp3.0 was computed.  netcoreapp3.1 was computed. 
.NET Standard netstandard2.0 is compatible.  netstandard2.1 was computed. 
.NET Framework net461 was computed.  net462 was computed.  net463 was computed.  net47 was computed.  net471 was computed.  net472 was computed.  net48 was computed.  net481 was computed. 
MonoAndroid monoandroid was computed. 
MonoMac monomac was computed. 
MonoTouch monotouch was computed. 
Tizen tizen40 was computed.  tizen60 was computed. 
Xamarin.iOS xamarinios was computed. 
Xamarin.Mac xamarinmac was computed. 
Xamarin.TVOS xamarintvos was computed. 
Xamarin.WatchOS xamarinwatchos was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages (2)

Showing the top 2 NuGet packages that depend on NvdaTestingDriver:

Package Downloads

This package contains extensions to use NvdaTestingDriver with Selenium WebDriver. NVDA needs the browser window to be in the foreground, and it also needs any element to take the focus in order to analyze it. This package includes functions to do both.


This package contain classes to use MSTest with NvdaTestingDriver package.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last updated
0.2.0-beta 5,445 3/24/2019
0.1.0-beta 522 2/17/2019

V 0.2.0:

- Added the license files within each project.
- Changed projects to refer to license files instead of a URL.
- Fixed a problem with StopReadingAsync, which could go into an infinite loop if the cancellation signal was not received.
- Updated package to use NVDA 18.4.1. The size of NVDA has been significantly reduced.
- Fixed a bug when getting the NVDA zip in the first use.
- AddedBurmese, french, Danish, Farsi, Nepali, Portuguese (Brazil) and Portuguese (Portugal), Romanian, Russian and  Spain (Colombia) languages in supported NVDA languages.
- Fixed a typographical error in the repository URL.
- Removed unnecesary package dependency to NGettext
This is a beta version. Please don't hesitate to collaborate with improvements, making pull requests and helpping this project continue to grow.
Thanks to Pablo Núñez (@pablonete), for giving me the idea to start this project.