> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/nvaccess/nvda/llms.txt
> Use this file to discover all available pages before exploring further.

# Testing NVDA

> Guide for testing NVDA including manual testing, automated tests, and contributing as a tester

Testing is crucial to ensuring the quality and reliability of NVDA. Whether you're a developer testing your changes or a community member helping to test new releases, this guide will help you understand the testing process.

## Important Resources

* [NVDA User Guide](https://download.nvaccess.org/documentation/userGuide.html)
* [Changes in the latest release](https://download.nvaccess.org/documentation/changes.html)
* [Manual test plans](https://github.com/nvaccess/nvda/tree/master/tests/manual)
* [NVDA Wiki](https://github.com/nvaccess/nvda/wiki) - Additional guides and documentation
* [NVDA development snapshots](https://download.nvaccess.org/snapshots/alpha/) - Automatically generated builds

## Types of Builds

### Alpha Builds

* **Bleeding edge** builds created directly from the `master` branch
* Created each time a pull request is merged
* Includes code being tested for possible inclusion in upcoming releases
* May not be tested much and may contain major bugs
* Automated tests pass, but likely had no user testing

[Download alpha builds](https://download.nvaccess.org/snapshots/alpha)

### Beta Releases

* **Beta quality** builds
* Include all features for the upcoming release that have proved stable in alpha
* More stable than alpha builds

[Download beta builds](https://download.nvaccess.org/snapshots/beta/)

### Release Candidates (RC)

* Usually identical to the final release
* The latest final release will be identical to the final RC of the release cycle

## Manual Testing

<Note>
  User and community testing is particularly important for languages other than English.
</Note>

### Testing Approaches

NVDA includes [manual test plans](https://github.com/nvaccess/nvda/tree/master/tests/manual) to guide testers in smoke testing features. You can take several approaches:

<Tabs>
  <Tab title="Unfocused Usage">
    Just use NVDA as you normally would and try to complete everyday tasks. This helps catch issues in real-world scenarios.
  </Tab>

  <Tab title="Recent Change Testing">
    Follow the changes being made to NVDA and purposefully test these changes while looking for edge cases.
  </Tab>

  <Tab title="Regression Testing">
    Test older features and behavior to look for unintended regressions that don't seem related to recent changes.
  </Tab>

  <Tab title="Pull Request Testing">
    Test specific pull requests before they're merged:

    <Steps>
      <Step title="Navigate to the PR page">
        Go to the pull request you want to test on GitHub.
      </Step>

      <Step title="Find the build artifact">
        Navigate to the linked "Details of continuous integration" towards the end of the PR, as part of the checks and approval status.
      </Step>

      <Step title="Download from Artifacts tab">
        Go to the "Artifacts" tab and download the NVDA installer (named something like `output\nvda_snapshot_pr15335-28962,a2970e3f.exe`).
      </Step>

      <Step title="Test according to PR description">
        The pull request should contain information on how to test the change.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Bug Confirmation">
    Follow the [issue triage process](https://github.com/nvaccess/nvda/blob/master/projectDocs/issues/triage.md) to help confirm bugs and debug issues.
  </Tab>
</Tabs>

<Tip>
  Forming a group can help you get good coverage, brainstorm on what should be tested, and learn new ways to use NVDA.
</Tip>

## Automated Testing

NVDA performs automated testing as part of CI/CD, including linting checks, unit tests, and system tests.

### Pre-commit Hooks

[Pre-commit hooks](https://pre-commit.com/) automatically run linting, translatable string checks, and unit tests on files staged for commit. This will automatically apply lint fixes where possible and cancel commits on lint issues and test failures.

**Set up pre-commit for your NVDA environment:**

```bash theme={null}
uv run pre-commit install
```

**Or set up globally:**

```bash theme={null}
pip install pre-commit
pre-commit install --allow-missing-config
```

**Skip pre-commit hooks:**

```bash theme={null}
git commit -m "message" --no-verify
```

#### Manually Running Pre-commit Hooks

Run pre-commit hooks manually with filters:

```bash theme={null}
# Run on specific files
uv run pre-commit run --files path/to/file.py

# Run on all files
uv run pre-commit run --all-files

# Compare two revisions
uv run pre-commit run --from-ref origin/master --to-ref HEAD
```

### Translatable String Checks

Check that all translatable strings have translator comments:

```cmd theme={null}
runcheckpot.bat
```

### Linting Your Changes

Our linting process uses:

* **[Ruff](https://docs.astral.sh/ruff)** - Python linting and auto-fixes
* **[pyright](https://microsoft.github.io/pyright/)** - Static type checking

**Run the linter:**

```cmd theme={null}
runlint.bat
```

<Tip>
  Integrate Ruff and pyright with your IDE to be warned about linting errors faster.
</Tip>

### Unit Tests

Unit tests use the [xmlrunner](https://github.com/pycontribs/xmlrunner) wrapper around Python's [unittest](https://docs.python.org/3/library/unittest.html) framework.

**Run all unit tests:**

```cmd theme={null}
rununittests.bat
```

**Run specific tests using the `-k` option:**

```cmd theme={null}
rununittests -k test_cursorManager.TestMove -k test_cursorManager.TestSelection
```

The `-k` option can be provided multiple times to match against multiple patterns.

Refer to [unittest's documentation](https://docs.python.org/3/library/unittest.html#command-line-interface) for more information on filtering tests.

### System Tests

System tests use the Robot test framework.

**Run standard tests for developers:**

```cmd theme={null}
runsystemtests.bat --include NVDA
```

**Run specific test tags:**

```cmd theme={null}
runsystemtests.bat --include <TAG>
```

Any arguments given to `runsystemtests.bat` are forwarded to 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. Check that you don't introduce incompatible dependencies:

```cmd theme={null}
runlicensecheck.bat
```

This is configured in `pyproject.toml` using the [licensecheck pip package](https://github.com/FHPythonUtils/LicenseCheck).

## Testing Checklist for Pull Requests

When submitting a pull request, ensure you've completed:

<Steps>
  <Step title="Manual testing">
    * Test the change thoroughly in real-world scenarios
    * Test on all supported operating systems if applicable
    * Consider possible regressions in related features
    * Follow relevant [manual test plans](https://github.com/nvaccess/nvda/tree/master/tests/manual)
  </Step>

  <Step title="Automated tests">
    ```bash theme={null}
    rununittests.bat    # All tests must pass
    runlint.bat         # No linting errors
    runcheckpot.bat     # Translatable strings validated
    runlicensecheck.bat # No license conflicts
    ```
  </Step>

  <Step title="Consider test coverage">
    * Can your changes be covered by automated unit tests?
    * Can your changes be covered by automated system tests?
    * If this is a commonly tested part of NVDA, add your test steps to the manual test documentation
  </Step>
</Steps>

## Community Communication Channels

Join the testing community:

* [NVDA Users Mailing List](https://groups.google.com/a/nvaccess.org/g/nvda-users)
* [NVDA Developers Mailing List](https://groups.io/g/nvda-devel)
* [Other sources including social media and language-specific communities](https://github.com/nvaccess/nvda/wiki/Connect)

## Contributing as a Tester

You don't need to be a developer to contribute to NVDA through testing! Testing alpha and beta releases, confirming bugs, and testing pull requests are all valuable contributions.

<Note>
  For more information on contributing through testing, see the [contributing guide](/development/contributing).
</Note>

## Release Process

Learn more about how NVDA releases are managed in the [release process documentation](https://github.com/nvaccess/nvda/blob/master/projectDocs/community/releaseProcess.md).