NvdaTestingDriver 0.2.0-beta

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:

SendCommandAndGetSpokenTextAsync

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.

SendKeysAndGetSpokenTextAsync

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.