> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.nvidia.com/cuda/cupotential/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.nvidia.com/cuda/cupotential/_mcp/server.

# Tests

> Check the OpenMM plugin against reference results, from a source build or an installed package.

The plugin's correctness tests compare its results with stock OpenMM. They are
available in the [cuPotential repository](https://github.com/NVIDIA/cuPotential)
and the [source tarball](/cuda/cupotential/install). For performance measurements,
see [Benchmarks](/cuda/cupotential#benchmarks).

## Run the tests

Run `./run_test` from the repository root. It starts the Docker container
through `./run_docker` and builds the plugin before running the selected tests.

For a short energy check on DHFR in double precision, run:

```bash
./run_test openmm_unit -k "test_energy and dhfr-fp64"
```

After the build, this check takes a few seconds. The `-k` option filters tests
by name, as it does in pytest. Without `-k`, `openmm_unit` runs the full
correctness suite, which takes a few hours on one GPU.

Run `./run_test --list-stages` to see the available stages.

Run `export NV_GPU=0` before `./run_test` to select the first host GPU. GPU indices
start at 0. If `NV_GPU` is unset, all GPUs are available to the Docker container.
Tests fail immediately if another process is using the selected GPU.

> **Tip**
>
> If the GPU disappears in the middle of the tests, with "Failed to initialize NVML:
> Unknown Error" or "No compatible CUDA device is available", the host probably ran
> `systemctl daemon-reload`. Set `CUPO_DOCKER_ADD_DEVICE_NODES=1` to have
> `./run_docker` also pass the GPUs' device nodes, which keeps them. See
> [The GPUs the container gets](/cuda/cupotential/install#the-gpus-the-container-gets).

## Test an installed plugin

By default, the tests use the plugin built from source. Set
`CUPO_TEST_INSTALLED=1` to test a pip or conda installation instead. Install the
plugin and run the tests in the same `./run_docker bash` session.

The examples below install the plugin and run a short test in one session.
Replace the placeholders with the wheel URL or unpacked conda channel from the
[installation guide](/cuda/cupotential/install).

For pip, the tests use the Docker environment's Python, which already includes
pytest:

```bash
./run_docker bash
pip install <the release's wheel>
CUPO_TEST_INSTALLED=1 ./run_test openmm_unit -k test_unit_conversion
```

For conda, install pytest in the `cupotential` environment and use
`micromamba run` to run the tests there:

```bash
./run_docker bash
micromamba create -y -n cupotential -c ./<the release's conda channel> -c conda-forge nv-openmm-plugin
micromamba install -y -n cupotential -c conda-forge pytest
CUPO_TEST_INSTALLED=1 micromamba run -n cupotential ./run_test openmm_unit -k test_unit_conversion
```

`-k test_unit_conversion` selects a test module that runs in under a minute.
Outside Docker, install pytest in the same environment as the plugin.

The session header identifies the plugin being tested and lists its module,
library, and version. If `CUPO_TEST_INSTALLED=1` is set but no plugin is installed,
the tests fail immediately. Tests that require the source build are skipped
with a message naming the variable.

See the [test README](https://github.com/NVIDIA/cuPotential/blob/v0.3.5/plugins/openmm/tests/README.md)
for details.