nvda-addon-testkit

End-to-end testing for NVDA add-ons, against a real NVDA, in CI.

Your add-on's logic can be unit-tested with stubs. What cannot be stubbed is whether it installs, registers, and behaves inside NVDA itself. This kit provisions a disposable portable NVDA, installs your add-on into it, and lets pytest drive it.

def test_my_addon_announces_itself(nvda, addon_under_test):
    before = nvda.speech.index()
    nvda.keys.press("NVDA+shift+m")
    assert "my add-on is ready" in nvda.speech.wait_for("ready", timeout=10, since=before).text
    nvda.log.assert_no_errors()

Install

pip install nvda-addon-testkit

Configure

[tool.nvda-testkit]
addon-bundle = "dist/my-addon-*.nvda-addon"
nvda-channel = "stable"

Run in GitHub Actions

jobs:
  e2e:
    runs-on: windows-2025
    steps:
      - uses: actions/checkout@v5
      - uses: zirekhq/nvda-addon-testkit@v1
        with:
          nvda-channel: stable
      - run: pytest tests_e2e/ -v

What you get

Requirements

Windows to run the tests. NVDA is downloaded automatically — you do not need one installed, and nothing touches an NVDA you already have.

Tests run serially: only one NVDA can own a desktop session, so pytest-xdist with more than one worker is refused rather than silently producing nonsense.

Developing the kit itself

The host side is fully testable on Linux against a scriptable double:

pip install -e ".[dev]"
python tools/build_spy.py
pytest                       # host and spy unit tests, any platform
pytest tests_e2e/ -v         # real NVDA, Windows only
nvda-testkit doctor          # check this machine

Licence

GPL-2.0-or-later.