tox.ini

[tox]
min_version = 4.25
requires =
    tox-uv>=1

env_list =
    py3.11-numpy_latest-vtk_9.2.6
    py3.12-numpy_latest-vtk_9.3.1
    py3.13-numpy_latest-vtk_9.4.2
    py3.13-numpy_latest-vtk_9.5.2
    py3.14-numpy_latest-vtk_latest
    py3.14-numpy_nightly-vtk_latest
    py3.{10-14}
    py3.{10-14}-vtk_dev

# ================= DEFAULT ENVIRONMENTS =================
[testenv]
install_command =
    uv pip install --prerelease=allow {opts} {packages}
description = Run the tests for python {basepython}
package =
    cov: editable # Otherwise, the coverage is not computed correctly
    !cov: wheel
wheel_build_env = .pkg

passenv =
    PYVISTA*
    TRAME*
    JUPYTER*
    PLOT_SKIP*
    DISPLAY
    XAUTHORITY
    ALLOW_PLOTTING
    PYTEST*
    GITHUB*
    *SSL*
    COVERAGE*
    CI*
    MESA*
    VTK*
    DISPLAY*
    UV_INDEX
    PIP_INDEX_URL
    PIP_TRUSTED_HOST

setenv =
    TOX_ROOT = {tox_root}
    PYTEST_ADDOPTS = --color=yes -v {env:PARALLEL:}

dependency_groups = test
deps =
    numpy_1.23: numpy ~= 1.23.0
    numpy_1.26: numpy ~= 1.26.0
    vtk_9.2.2: vtk == 9.2.2
    vtk_9.2.6: vtk == 9.2.6
    vtk_9.3.1: vtk == 9.3.1
    vtk_9.4.2: vtk == 9.4.2
    vtk_9.5.2: vtk == 9.5.2

uv_index_numpy_nightly = https://pypi.anaconda.org/scientific-python-nightly-wheels/simple
uv_index_vtk_dev = https://wheels.vtk.org
numpy_nightly_install = uv pip install --upgrade --pre --no-cache --no-deps --extra-index-url {[testenv]uv_index_numpy_nightly} matplotlib numpy
vtk_dev_install = uv pip install --upgrade --pre --no-cache --no-deps --extra-index-url {[testenv]uv_index_vtk_dev} vtk

commands_pre =
    numpy_nightly: python -c 'import os, subprocess, shlex; os.environ["UV_INDEX"]="{[testenv]uv_index_numpy_nightly}"; subprocess.run(shlex.split("{[testenv]numpy_nightly_install}"), check=True)'
    vtk_dev: python -c 'import os, subprocess, shlex; os.environ["UV_INDEX"]="{[testenv]uv_index_vtk_dev}"; subprocess.run(shlex.split("{[testenv]vtk_dev_install}"), check=True)'
    {[testenv]software_report_cmdline}

commands =
    {[testenv]all_testing_cmdline}

cov_flags =
    --cov \
    pyvista \
    --cov-config \
    {tox_root}{/}pyproject.toml \
    --cov-context \
    test \
    --cov-report \
    term:skip-covered \
    --cov-report \
    xml:coverage_{env_name}.xml \
    --cov-report \
    html:coverage_{env_name}

test_downloads = --test_downloads
disallow_unused_cache = --disallow_unused_cache
core_flags = --ignore=tests/plotting {[testenv]test_downloads}
plotting_flags = tests/plotting {[testenv]disallow_unused_cache}
all_flags = {[testenv]test_downloads} {[testenv]disallow_unused_cache}

all_testing_cmdline =
    !cov-core: pytest {[testenv]core_flags} {posargs}
    !cov-plotting: pytest {[testenv]plotting_flags} {posargs}
    cov-core: pytest {[testenv]core_flags} {[testenv]cov_flags} {posargs}
    cov-plotting: pytest {[testenv]plotting_flags} {[testenv]cov_flags} {posargs}
    !cov-!plotting-!core: pytest {[testenv]all_flags} {posargs}

software_report_cmdline=
    pyvista report --gpu --downloads

# ================= LOCAL DEV TEST ENVIRONMENTS =================
# These mirror the `core` / `plotting` factor splits used in CI (see
# .github/workflows/testing-and-deployment.yml) so the Makefile
# `test-core` / `test-plotting` targets run the exact same pytest
# invocation as CI. They inherit from [testenv] above and rely on the
# existing `core` / `plotting` factor logic so filters are maintained
# in one place.
[testenv:test{,-core,-plotting}]
description =
    test: Run the full test suite locally (core + plotting, matches CI flags)
    test-core: Run core tests locally (matches CI `tox run -e pyX.Y-core`)
    test-plotting: Run plotting tests locally (matches CI `tox run -e pyX.Y-plotting`)

# ================= PLAYWRIGHT TESTING ENVIRONMENT =================
# This environment is specialized to run PyVista tests that require
# playwright. It is treated like an integration test, but it is not
# a true integration test in the sense that a 3rd party library is
# not being tested. The "integration" part is mainly relevant for CI
# since this test is treated just like an integration test and is
# run in the same manner and with the same frequency.
[testenv:integration-playwright]
description = Run tests that use playwright
basepython = py3.14
dependency_groups = test-playwright
commands_pre =
    {[testenv]software_report_cmdline}
    playwright install --with-deps chromium
commands =
    python -m pytest -m needs_playwright --playwright {posargs}

# ================= INTEGRATION ENVIRONMENTS =================
[testenv:integration-{trame,geovista,mne,pyvistaqt}]
description =
    trame: Run the integration tests for trame
    mne: Run the integration tests for mne
    geovista: Run the integration tests for geovista
    pyvistaqt: Run the integration tests for pyvistaqt

skip_install = true # added since commands_pre that install the target package might override the current pyvista installation
basepython =
    pyvistaqt: py3.14
    trame,mne: py3.14
    geovista: py3.13
dependency_groups =
    mne: []
deps =
    pyvistaqt: PyQt6-Qt6!=6.6.0,!=6.7.0
    pyvistaqt: PyQt6!=6.6.0

setenv =
    GEOVISTA_HOME = {temp_dir}{/}geovista
    MNE_HOME = {temp_dir}{/}mne
    PYVISTAQT_HOME = {temp_dir}{/}pyvistaqt
    TRAME_HOME = {temp_dir}{/}trame-pyvista
    XDG_CACHE_HOME = {temp_dir}{/}.cache # for geovista pooch downloads
    XDG_DATA_HOME = {temp_dir}{/}.data # for cartopy url downloads
    GEOVISTA_POOCH_MUTE = true

    _GEOVISTA_ARGS = {env:GEOVISTA_HOME}{/}tests --rootdir={env:GEOVISTA_HOME}

    _MNE_ARGS = {env:MNE_HOME}{/}mne{/} -m pvtest --rootdir={env:MNE_HOME}

    _PYVISTAQT_ARGS = {env:PYVISTAQT_HOME}/tests \
        --rootdir={env:PYVISTAQT_HOME}

    _TRAME_ARGS = {env:TRAME_HOME}{/}tests --rootdir={env:TRAME_HOME}

allowlist_externals =
    git
    sh
    bash

change_dir =
    geovista,mne,trame: {tox_root}

platform =
    mne: linux

commands_pre =
    # TRAME-PYVISTA SETUP
    trame: bash -c "[ -d {env:TRAME_HOME} ] || git clone https://github.com/pyvista/trame-pyvista.git {env:TRAME_HOME} --single-branch"
    trame: uv pip install {env:TRAME_HOME}[test]

    # GEOVISTA SETUP
    geovista: bash -c "[ -d {env:GEOVISTA_HOME} ] || git clone https://github.com/bjlittle/geovista.git {env:GEOVISTA_HOME} --single-branch"
    geovista: uv pip install {env:GEOVISTA_HOME}[test,exam,cmap]
    geovista: cartopy_feature_download physical --output {env:XDG_DATA_HOME}{/}cartopy --no-warn

    # MNE-PYTHON SETUP
    # Only clone if it hasn't been done already
    mne: bash -c "[ -d {env:MNE_HOME} ] || git clone --depth=1 https://github.com/mne-tools/mne-python.git {env:MNE_HOME} --branch main --single-branch"
    mne: uv pip install git+https://github.com/pyvista/pyvistaqt.git
    # Editable install so MNE's `*/tests` packages stay importable: MNE's
    # hatch build excludes `/mne/**/tests` from the wheel, but the notebook
    # viz tests import `mne.viz.backends.tests` from inside a Jupyter kernel
    # whose cwd is the pyvista tree, so it resolves the installed package
    # rather than the cloned source. Editable keeps the source tree on path.
    mne: uv pip install -e {env:MNE_HOME}[full-pyside6] --project {env:MNE_HOME} --group test_extra
    mne: bash -c "{env:MNE_HOME}/tools/github_actions_download.sh"
    mne: python -c "import pyvista; assert not pyvista.OFF_SCREEN, f'{pyvista.OFF_SCREEN=} should be False'"

    # PYVISTAQT SETUP
    pyvistaqt: bash -c "[ -d {env:PYVISTAQT_HOME} ] || git clone https://github.com/pyvista/pyvistaqt.git {env:PYVISTAQT_HOME} --single-branch"
    pyvistaqt: uv pip install {env:PYVISTAQT_HOME}[test]

    # COMMON SETUP (CURRENT PYVISTA VERSION INSTALLATION)
    uv pip install {tox_root} --project {tox_root} --group pinned
    {[testenv]software_report_cmdline}

    # EXTRA SOFTWARE REPORTS
    geovista: scooby --report geovista
    mne: mne sys_info -p
    trame: scooby --report trame
    pyvistaqt: scooby --report pyvistaqt

commands =
    trame: pytest --color=yes -v {env:_TRAME_ARGS} {posargs}
    geovista: pytest --color=yes -v -W ignore::pyvista.core.errors.PyVistaDeprecationWarning {env:_GEOVISTA_ARGS} {posargs}
    mne: pytest --color=yes -v {env:_MNE_ARGS} {posargs}
    pyvistaqt: pytest --color=yes -v {env:_PYVISTAQT_ARGS} {posargs}

commands_post =
    geovista: python -c "import shutil,os,stat;shutil.rmtree(os.environ['GEOVISTA_HOME'], onerror=lambda func, path, _: (os.chmod(path, stat.S_IWRITE), func(path)))"
    mne: python -c "import shutil,os,stat;shutil.rmtree(os.environ['MNE_HOME'], onerror=lambda func, path, _: (os.chmod(path, stat.S_IWRITE), func(path)))"
    pyvistaqt: python -c "import shutil,os,stat;shutil.rmtree(os.environ['PYVISTAQT_HOME'], onerror=lambda func, path, _: (os.chmod(path, stat.S_IWRITE), func(path)))"
    trame: python -c "import shutil,os,stat;shutil.rmtree(os.environ['TRAME_HOME'], onerror=lambda func, path, _: (os.chmod(path, stat.S_IWRITE), func(path)))"


# ================= TYPING ENVIRONMENT =================
[testenv:mypy]
description = Run mypy type checks
basepython = py3.14
setenv =
  MYPY_FORCE_COLOR = 1
  TERM = xterm-color
dependency_groups = typing
commands = mypy

# ================= DOCTESTING ENVIRONMENTS =================
[testenv:doctest-{modules,local}]
description =
    modules: Run doctest-modules with pytest
    local: Run doctest using docstring local namespace
setenv =
    PYVISTA_OFF_SCREEN = true
    PYTEST_ADDOPTS = --color=yes -v {env:PARALLEL:-n auto}
commands =
	modules: pytest --doctest-modules --doctest-continue-on-failure {env_site_packages_dir}{/}pyvista {posargs}
    local: python tests/check_doctest_names.py

# ================= DOCUMENTATION ENVIRONMENTS =================
[testenv:docs-build]
description = Building documentation
basepython = py3.14
dependency_groups = docs
setenv =
    FORCE_COLOR = true
    PYDEVD_DISABLE_FILE_VALIDATION = 1
    PYVISTA_OFF_SCREEN = true
    ALLOW_PLOTTING = true
    SHELLOPTS = errexit:pipefail

    # SPHINX OPTIONS
    # Default to auto-detected parallelism when PARALLEL is not set
    _SPHINX_JOBS = {env:PARALLEL:-jauto}
    _SPHINX_DEFAULTS = -w sphinx_warnings.txt -W --keep-going
    _SPHINX_SOURCE_DIR = source
    _SPHINX_BUILD_DIR = _build

change_dir = doc
commands_pre =
    {[testenv]software_report_cmdline}
    python -c "import subprocess, os;subprocess.run([r'{envpython}','make_tables.py'], cwd='{env:_SPHINX_SOURCE_DIR}', check=True)"
    python -c "import subprocess, os;subprocess.run([r'{envpython}','make_external_gallery.py'], cwd='{env:_SPHINX_SOURCE_DIR}', check=True)"
commands =
    python -m sphinx -M {posargs:html} {env:_SPHINX_SOURCE_DIR} {env:_SPHINX_BUILD_DIR} {env:_SPHINX_DEFAULTS} {env:_SPHINX_JOBS}

[testenv:image-report]
description = Generate HTML report for failed test image comparisons
basepython = py3
skip_install = true
dependency_groups =
passenv =
    PR_URL
    BRANCH
deps =
    rich
commands_pre =
commands =
    python {tox_root}{/}tests{/}generate_test_image_report.py \
        {posargs:{tox_root}{/}_failed_test_images {tox_root}{/}_image_report}

[testenv:docs-test]
description = Test documentation build (needs already built docs)
basepython = py3.14
dependency_groups = docs-test
setenv =
    PYTEST_ADDOPTS = --color=yes
commands_pre =
    {[testenv]software_report_cmdline}
commands =
    playwright install chromium
    pytest {tox_root}{/}tests{/}doc{/}tst_doc_build.py
    pytest --doc_mode -n auto