Adopt tox

SciTools · Mar 29, 2023 · 9b39783 · 9b39783
1 parent 2056703
commit 9b39783
Show file tree

Hide file tree

Showing 7 changed files with 121 additions and 88 deletions.
diff --git a/.github/workflows/ci-tests.yml b/.github/workflows/ci-tests.yml
@@ -35,19 +35,28 @@ jobs:
       fail-fast: false
       matrix:
         os: ["ubuntu-latest"]
-        python-version: ["3.10"]
-        session: ["doctest", "gallery", "linkcheck"]
+        python-version: ["310"]
+        session: ["docs-tests", "docs-linkcheck"]
         include:
           - os: "ubuntu-latest"
-            python-version: "3.10"
+            python-version: "310"
             session: "tests"
-            coverage: "--coverage"
+            posargs: "--gallery-tests"
           - os: "ubuntu-latest"
-            python-version: "3.9"
+            python-version: "310"
             session: "tests"
+            posargs: "--cov=lib/iris --cov-report=xml"
           - os: "ubuntu-latest"
-            python-version: "3.8"
+            python-version: "39"
             session: "tests"
+          - os: "ubuntu-latest"
+            python-version: "38"
+            session: "tests"
+          - os: "ubuntu-latest"
+            python-version: "310"
+            session: "tests"
+            posargs: "--gallery-tests"
+
 
     env:
       IRIS_TEST_DATA_VERSION: "2.19"
@@ -63,7 +72,7 @@ jobs:
           CACHE_WEEKS: 2
         run: |
           echo "CACHE_PERIOD=$(date +%Y).$(expr $(date +%U) / ${CACHE_WEEKS})" >> ${GITHUB_ENV}
-          echo "LOCK_FILE=requirements/ci/nox.lock/py$(echo ${{ matrix.python-version }} | tr -d '.')-linux-64.lock" >> ${GITHUB_ENV}
+          echo "LOCK_FILE=requirements/ci/locks/py$(echo ${{ matrix.python-version }} | tr -d '.')-linux-64.lock" >> ${GITHUB_ENV}
 
       - name: "data cache"
         uses: ./.github/workflows/composite/iris-data-cache
@@ -91,10 +100,10 @@ jobs:
       - name: "conda environment cache"
         uses: ./.github/workflows/composite/conda-env-cache
         with:
-          cache_build: 0
+          cache_build: 1
           cache_period: ${{ env.CACHE_PERIOD }}
           env_name: ${{ env.ENV_NAME }}
-          install_packages: "cartopy nox pip"
+          install_packages: "cartopy tox'<4'"
 
       - name: "conda info"
         run: |
@@ -108,8 +117,8 @@ jobs:
           cache_period: ${{ env.CACHE_PERIOD }}
           env_name: ${{ env.ENV_NAME }}
 
-      - name: "nox cache"
-        uses: ./.github/workflows/composite/nox-cache
+      - name: "tox cache"
+        uses: ./.github/workflows/composite/tox-cache
         with:
           cache_build: 0
           env_name: ${{ env.ENV_NAME }}
@@ -134,11 +143,9 @@ jobs:
           cat ${MPL_RC}
 
       - name: "iris ${{ matrix.session }}"
-        env:
-          PY_VER: ${{ matrix.python-version }}
         run: |
-          nox --session ${{ matrix.session }} -- --verbose ${{ matrix.coverage }}
+            tox -e py${{ matrix.python-version }}-${{ matrix.session }} -- ${{ matrix.posargs }}
 
       - name: Upload coverage report
         uses: codecov/codecov-action@v3
-        if: ${{ matrix.coverage }}
+        if: contains(${{ matrix.posargs }}, "--cov=lib/iris --cov-report=xml")
diff --git a/.github/workflows/ci-wheels.yml b/.github/workflows/ci-wheels.yml
@@ -54,7 +54,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        python-version: ["3.8", "3.9", "3.10"]
+        python-version: ["38", "39", "310"]
         session: ["wheel"]
     env:
       ENV_NAME: "ci-wheels"
@@ -74,7 +74,7 @@ jobs:
           CACHE_WEEKS: 2
       run: |
         echo "CACHE_PERIOD=$(date +%Y).$(expr $(date +%U) / ${CACHE_WEEKS})" >> ${GITHUB_ENV}
-        echo "LOCK_FILE=requirements/ci/nox.lock/py$(echo ${{ matrix.python-version }} | tr -d '.')-linux-64.lock" >> ${GITHUB_ENV}
+        echo "LOCK_FILE=requirements/ci/locks/py$(echo ${{ matrix.python-version }} | tr -d '.')-linux-64.lock" >> ${GITHUB_ENV}
 
     - name: "conda package cache"
       uses: ./.github/workflows/composite/conda-pkg-cache
@@ -95,23 +95,21 @@ jobs:
     - name: "conda environment cache"
       uses: ./.github/workflows/composite/conda-env-cache
       with:
-        cache_build: 0
+        cache_build: 1
         cache_period: ${{ env.CACHE_PERIOD }}
         env_name: ${{ env.ENV_NAME }}
-        install_packages: "nox pip"
+        install_packages: "tox'<4' pip"
 
-    - name: "nox cache"
-      uses: ./.github/workflows/composite/nox-cache
+    - name: "tox cache"
+      uses: ./.github/workflows/composite/tox-cache
       with:
         cache_build: 0
         env_name: ${{ env.ENV_NAME }}
         lock_file: ${{ env.LOCK_FILE }}
 
-    - name: "nox install and test wheel"
-      env:
-        PY_VER: ${{ matrix.python-version }}
+    - name: "tox install and test wheel"
       run: |
-        nox --session ${{ matrix.session }} -- --verbose
+        tox -e py${{ matrix.python-version }}-${{ matrix.session }}
 
   show-artifacts:
     needs: build

diff --git a/.../workflows/composite/nox-cache/action.yml → .../workflows/composite/tox-cache/action.yml b/.../workflows/composite/nox-cache/action.yml → .../workflows/composite/tox-cache/action.yml
@@ -1,9 +1,9 @@
-name: "nox cache"
-description: "cache the nox test environments"
+name: "tox cache"
+description: "cache the tox test environments"
 
 inputs:
   cache_build:
-    description: "nox cache build number"
+    description: "tox cache build number"
     required: false
     default: "0"
   env_name:
@@ -18,5 +18,5 @@ runs:
   steps:
     - uses: actions/cache@v3
       with:
-        path: ${{ github.workspace }}/.nox
-        key: ${{ runner.os }}-nox-${{ inputs.env_name }}-s${{ matrix.session }}-py${{ matrix.python-version }}-b${{ inputs.cache_build }}-${{ hashFiles(inputs.lock_file) }}
+        path: ${{ github.workspace }}/.tox
+        key: ${{ runner.os }}-tox-${{ inputs.env_name }}-s${{ matrix.session }}-py${{ matrix.python-version }}-b${{ inputs.cache_build }}-${{ hashFiles(inputs.lock_file) }}
diff --git a/docs/src/common_links.inc b/docs/src/common_links.inc
@@ -35,6 +35,7 @@
 .. _scitools-iris: https://pypi.org/project/scitools-iris/
 .. _sphinx: https://www.sphinx-doc.org/en/master/
 .. _test-iris-imagehash: https://github.com/SciTools/test-iris-imagehash
+.. _tox: https://tox.readthedocs.io/en/latest/
 .. _using git: https://docs.github.com/en/github/using-git
 .. _requirements: https://github.com/SciTools/iris/tree/main/requirements
 .. _CF-UGRID: https://ugrid-conventions.github.io/ugrid-conventions/

diff --git a/docs/src/developers_guide/contributing_running_tests.rst b/docs/src/developers_guide/contributing_running_tests.rst
@@ -12,8 +12,8 @@ There are two options for running the tests:
   the tests or use ``python`` interactively to investigate any issues.  See
   :ref:`test manual env`.
 
-* Use ``nox``.  This will automatically generate an environment and run test
-  sessions consistent with our GitHub continuous integration.  See :ref:`using nox`.
+* Use ``tox``.  This will automatically generate an environment and run test
+  sessions consistent with our GitHub continuous integration.  See :ref:`using tox`.
 
 .. _test manual env:
 
@@ -101,97 +101,84 @@ using the commands ``python test_mapping.py -h`` or
 ``python test_mapping.py --help``.
 
 .. tip::  A useful command line option to use is ``-d``.  This will display
-          matplotlib_ figures as the tests are run.  For example::
+          `matplotlib_` figures as the tests are run.  For example::
 
              python test_mapping.py -d
 
-.. _using nox:
+.. _using tox:
 
-Using Nox for Testing Iris
+Using tox for Testing Iris
 ==========================
 
-The `nox`_ tool has for adopted for automated testing on `Iris GitHub Actions`_
+The `tox`_ tool has been adopted for automated testing on `Iris GitHub Actions`_
 and also locally on the command-line for developers.
 
-`nox`_ is similar to `tox`_, but instead leverages the expressiveness and power of a Python
-configuration file rather than an `.ini` style file. As with `tox`_, `nox`_ can use `virtualenv`_
-to create isolated Python environments, but in addition also supports `conda`_ as a testing
-environment backend.
+`tox`_ uses `virtualenv`_ to create isolated Python environments and is
+configured within a tox.ini file.
 
-
-Where is Nox Used?
+Where is tox Used?
 ------------------
 
-Iris uses `nox`_ as a convenience to fully automate the process of executing the Iris tests, but also
-automates the process of:
+Iris uses `tox`_ as a convenience to fully automate the process of:
 
-* building the documentation and executing the doc-tests
-* building the documentation gallery
+* executing the Iris tests,
+* building the documentation,
+* executing the doc-tests,
+* executing the gallery tests, and
 * running the documentation URL link check
 
-You can perform all of these tasks manually yourself, however the onus is on you to first ensure
-that all of the required package dependencies are installed and available in the testing environment.
+You can perform all of these tasks manually yourself, however the onus is on you
+to first ensure that all of the required package dependencies are installed and
+available in the testing environment.
 
-`Nox`_ has been configured to automatically do this for you, and provides a means to easily replicate
-the remote testing behaviour of `Iris GitHub Actions`_ locally for the developer.
+`tox`_ has been configured to automatically do this for you, and provides a
+means to easily replicate the remote testing behaviour of `Iris GitHub Actions`_
+locally for the developer.
 
 
-Installing Nox
+Installing tox
 --------------
 
-We recommend installing `nox`_ using `conda`_. To install `nox`_ in a separate `conda`_ environment::
+We recommend installing `tox`_ using `conda`_. To install `tox`_ in a separate
+`conda`_ environment::
 
-  conda create -n nox -c conda-forge nox
-  conda activate nox
+  conda create -n tox -c conda-forge tox
+  conda activate tox
 
-To install `nox`_ in an existing active `conda`_ environment::
+To install `tox`_ in an existing active `conda`_ environment::
 
-  conda install -c conda-forge nox
+  conda install -c conda-forge tox
 
-The `nox`_ package is also available on PyPI, however `nox`_ has been configured to use the `conda`_
-backend for Iris, so an installation of `conda`_ must always be available.
+The `tox`_ package is also available on PyPI, however `tox`_ has been configured
+to use `conda`_ to create the testing environments and so an installation of
+`conda`_ must always be available.
 
 
-Testing with Nox
+Testing with tox
 ----------------
 
-The `nox`_ configuration file `noxfile.py` is available in the root ``iris`` project directory, and
-defines all the `nox`_ sessions (i.e., tasks) that may be performed. `nox`_ must always be executed
-from the ``iris`` root directory.
-
-To list the configured `nox`_ sessions for Iris::
-
-  nox --list
-
-To run the Iris tests for all configured versions of Python::
+The `tox`_ configuration file `tox.ini` is available in the root ``iris``
+project directory, and defines all the `tox`_ test environments (i.e., tasks)
+that may be performed. `tox`_ must always be executed from the ``iris`` root
+directory.
 
-  nox --session tests
+To list the configured `tox`_ sessions for Iris::
 
-To build the Iris documentation specifically for Python 3.7::
+  tox --listenvs-all
 
-  nox --session doctest-3.7
+To run the Iris tests for Python 3.10::
 
-To run all the Iris `nox`_ sessions::
+  tox -e py310-tests
 
-  nox
+To build the Iris documentation specifically for Python 3.10::
 
-For further `nox`_ command-line options::
-
-  nox --help
-
-.. tip::
-    For `nox`_ sessions that use the `conda`_ backend, you can use the ``-v`` or ``--verbose``
-    flag to display the `nox`_ `conda`_ environment package details and environment info.
-    For example::
+  tox -e py310-docs
 
-        nox --session tests -- --verbose
+For further `tox`_ command-line options::
 
+  tox --help
 
-.. note:: `nox`_ will cache its testing environments in the `.nox` root ``iris`` project directory.
+.. note:: `tox`_ will cache its testing environments in the `.tox` root ``iris`` project directory.
 
 
-.. _setuptools: https://setuptools.readthedocs.io/en/latest/
-.. _tox: https://tox.readthedocs.io/en/latest/
-.. _virtualenv: https://virtualenv.pypa.io/en/latest/
-.. _PyPI: https://pypi.org/project/nox/
-.. _v41.5.0: https://setuptools.readthedocs.io/en/latest/history.html#v41-5-0
+.. _virtualenv: https://virtualenv.pypa.io/en/latest/
diff --git a/docs/src/whatsnew/latest.rst b/docs/src/whatsnew/latest.rst
@@ -140,6 +140,9 @@ This document explains the changes made to Iris for this release
 #. `@lbdreyer`_ removed the Iris TestRunner. Tests are now run via nox or
    pytest. (:pull:`5205`)
 
+# `@lbdreyer`_ replaced nox with tox as the automated test runnner.
+  (:pull:`5184`)
+
 
 .. comment
     Whatsnew author names (@github name) in alphabetical order. Note that,

diff --git a/tox.ini b/tox.ini
@@ -0,0 +1,37 @@
+[tox]
+requires =
+    tox-conda
+
+[testenv]
+conda_spec =
+    py38: {toxinidir}{/}requirements{/}locks{/}py38-linux-64.lock
+    py39: {toxinidir}{/}requirements{/}locks{/}py39-linux-64.lock
+    py310: {toxinidir}{/}requirements{/}locks{/}py310-linux-64.lock
+
+[testenv:py{38,39,310}-tests]
+description = Perform Iris unit, integration and system tests.
+usedevelop =
+    true
+commands =
+    pytest -n auto {posargs} {toxinidir}{/}lib{/}iris{/}tests
+
+[testenv:py{38,39,310}-docs{,-linkcheck,-tests}]
+description = Build, and optionally linkcheck or test, the Iris documentation
+allowlist_externals =
+    make
+changedir =
+    {toxinidir}{/}docs
+usedevelop =
+    true
+commands =
+    make clean html
+    linkcheck: make linkcheck
+    tests: make doctest
+
+[testenv:py{38,39,310}-wheel]
+description = Install wheel and test Iris import
+skip_install = true
+deps =
+    {toxinidir}{/}dist{/}scitools_iris*.whl
+commands =
+    python -c "import iris; print(f'\{iris.__version__=\}')"