Installation

pip install nvda-addon-testkit

Compatibility

nvda-addon-testkit	NVDA	Python inside NVDA (the spy add-on)	Python running pytest
2.x	2026.1 and later	3.13, 64-bit	3.13 to 3.14
1.x	2024.1 and later	3.11, 32-bit (NVDA 2024.1 to 2025.3); 3.13, 64-bit (NVDA 2026.1 and later)	3.11 to 3.14

nvda-addon-testkit

NVDA

Python inside NVDA (the spy add-on)

Python running pytest

2.x

2026.1 and later

3.13, 64-bit

3.13 to 3.14

1.x

2024.1 and later

3.11, 32-bit (NVDA 2024.1 to 2025.3); 3.13, 64-bit (NVDA 2026.1 and later)

3.11 to 3.14

From 2.0 the spy add-on declares minimumNVDAVersion = 2026.1, so NVDA refuses to load it on older releases: a pinned --nvda-version before 2026.1 fails with a HandshakeTimeout. Use the 1.x releases to test against NVDA 2024.1 to 2025.3.

The Python column for NVDA comes from NVDA’s own source: its createDevEnvironment.md and pyproject.toml at each release tag (3.11 until 2025.3, 3.13 from 2026.1). The kit’s host side runs under your own pytest: 2.x requires Python 3.13 or later (the version NVDA 2026.1 embeds) and is tested on 3.13 and 3.14; 1.x supports 3.11 to 3.14.

Configure

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

Every key has a matching pytest flag where noted; flags win over pyproject.toml.

[tool.nvda-testkit] key pytest flag Default Meaning

`[tool.nvda-testkit]` key	pytest flag	Default	Meaning
`nvda-channel`	`--nvda-channel`, `--nvda-version`	`stable`	`stable`, `beta`, `alpha`, or a pinned version
`addon-bundle`		none	glob for the built `.nvda-addon`
`modules`		`[]`	accepted (string or list) but not read by the kit yet
`allow-eval`	`--nvda-allow-eval`	`false`	enable `nvda.eval()` and `nvda.exec()`
`timeout`		`10.0`	default wait timeout in seconds
`timeout-scale`	`--nvda-timeout-scale`	`1.0`	multiplier applied to every timeout
`keep-portable`	`--nvda-keep-portable`	`false`	keep the portable NVDA copy after teardown
`out-dir`	`--nvda-out-dir`	`testOutput`	where logs and artifacts are written
`fail-on-log-errors`		`false`	DSL fails when NVDA logs errors
`ignore-log-errors`		`[]`	regexes of log errors to ignore
`verbose`	`--nvda-verbose`	`false`	do not truncate lists in DSL failure messages

nvda-channel

--nvda-channel, --nvda-version

stable

stable, beta, alpha, or a pinned version

addon-bundle

none

glob for the built .nvda-addon

modules

[]

accepted (string or list) but not read by the kit yet

allow-eval

--nvda-allow-eval

false

enable nvda.eval() and nvda.exec()

timeout

10.0

default wait timeout in seconds

timeout-scale

--nvda-timeout-scale

1.0

multiplier applied to every timeout

keep-portable

--nvda-keep-portable

false

keep the portable NVDA copy after teardown

out-dir

--nvda-out-dir

testOutput

where logs and artifacts are written

fail-on-log-errors

false

DSL fails when NVDA logs errors

ignore-log-errors

[]

regexes of log errors to ignore

verbose

--nvda-verbose

false

do not truncate lists in DSL failure messages

Run in GitHub Actions

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

Action inputs: nvda-channel (default stable), python-version (default 3.13), and testkit-version (a pip version specifier for nvda-addon-testkit; empty installs the latest).

The action requires a Windows runner — pick whichever one matches what your users run. This repository’s own e2e test suite runs on both windows-2025 and windows-2022 (the latter for Windows 10 22H2, including builds still on Extended Security Updates).