Running Automated Tests

If you make a change to the NVDA code, you should run NVDA's automated tests. These tests help to ensure that code changes do not unintentionally break functionality that was previously working.

Git hooks (prek)

Git hooks can be used to automatically run linting, translatable string checks and unit tests on files staged for commit. This will automatically apply lint fixes where possible, and will cancel the commit on lint issues and other test failures. NVDA uses prek, a faster, drop-in compatible alternative to pre-commit.

There are two ways to run prek, and the examples below use both:

• Via the project's uv environment, prefixing commands with uv run (e.g. uv run prek install). This needs no separate installation.
• Via a global install, calling prek directly (e.g. prek install). Install it once with uv tool install prek.

From a shell, set up the Git hooks for your NVDA python environment:

uv run prek install

Alternatively, if you installed prek globally, set up the Git hooks with:

prek install --allow-missing-config

To skip the hooks from triggering, use the --no-verify CLI option. Example: git commit -m "message" --no-verify.

Switching from pre-commit

If you previously ran pre-commit install, an old pre-commit Git hook is still installed. Run uv run prek install -f once to overwrite it with the prek hook.

Manually running hooks

You can run the hooks manually with prek run. The examples below use the project's uv environment (uv run prek run …); if you installed prek globally, drop the uv run prefix and call prek run … directly.

• You can filter files with --files and --all-files
• You can also compare two revisions: uv run prek run --from-ref origin/master --to-ref HEAD

Translatable string checks

To run the translatable string checks (which check that all translatable strings have translator comments), run:

runcheckpot.bat

Linting your changes

Our linting process involves running Ruff to pick up Python linting issues and auto-apply fixes where possible.

pyright and ty are both used for static type checking. runlint.bat runs both type checkers.

To run the linter locally:

runlint.bat

To be warned about linting errors faster, you may wish to integrate Ruff, pyright and ty with your IDE or other development tools you are using.

Unit Tests

Unit tests can be run with the rununittests.bat script. Internally this script uses the xmlrunner wrapper around the unittest framework to execute the tests. Any arguments given to rununittests.bat are forwarded onto xmlrunner, and then to unittest.

To run only specific unit tests, specify a pattern to match against using the -k option on the command line. The -k option can be provided multiple times to provide multiple patterns to match against. For example, to run only methods in the TestMove and TestSelection classes in the file tests\unit\test_cursorManager.py file, run this command:

rununittests -k test_cursorManager.TestMove -k test_cursorManager.TestSelection

Please refer to unittest's documentation for further information on how to filter tests.

System Tests

System tests can be run with the runsystemtests.bat --include <TAG> script. To run all tests standard tests for developers use runsystemtests.bat --include NVDA. Internally this script uses the Robot test framework to execute the tests. Any arguments given to runsystemtests.bat are forwarded onto Robot. For more details (including filtering and exclusion of tests) see tests/system/readme.md.

License checks

NVDA uses GPLv2 which is incompatible with certain licenses like Apache. Run runlicensecheck.bat to check that you don't introduce any new python dependencies with incompatible licenses.

This is configured in pyproject.toml using the licensecheck pip package.