Add pytest coverage workflow & improve test config (#118)

* Add pytest coverage workflow & improve test config

Introduced a GitHub Actions workflow for running tests with coverage
analysis on Python 3.11 and 3.12. Updated test environment files and
documentation to use `pytest-cov` for streamlined coverage reporting. Added
continuous integration details to the development documentation.

.github/workflows/pytest-with-coverage.yaml

@@ -0,0 +1,25 @@
+name: pytest-with-coverage
+
+on:
+  push:
+    branches: [ '*' ]
+  # Enable workflow to be triggered from GitHub CLI, browser, or via API
+  # primarily for testing a conda environment solution for new Python versions
+  workflow_dispatch:
+
+jobs:
+  pytest-with-coverage:
+    permissions:
+      contents: read
+      pull-requests: write
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: [ '3.11', '3.12' ]
+    uses: UBC-MOAD/gha-workflows/.github/workflows/pytest-with-coverage.yaml@main
+    with:
+      python-version: ${{ matrix.python-version }}
+      conda-env-file: SalishSeaTools/envs/environment-test.yaml
+      conda-env-name: salishsea-tools-test
+    secrets:
+      CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}

SalishSeaTools/docs/development.rst

@@ -151,7 +151,7 @@ use:
 .. code-block:: bash
 
     (salishsea-tools)$ cd tools/SalishSeaTools/
-    (salishsea-tools)$ py.test
+    (salishsea-tools)$ pytest
 
 to run the test suite.
 The output looks something like::
@@ -174,32 +174,51 @@ The output looks something like::
 
   ========================= 189 passed in 1.38 seconds =========================
 
-You can monitor what lines of code the test suite exercises using the `coverage.py`_ tool with the command:
+You can monitor what lines of code the test suite exercises using the `coverage.py`_ and `pytest-cov`_ tools with the command:
 
-.. _coverage.py: https://coverage.readthedocs.org/en/latest/
+.. _coverage.py: https://coverage.readthedocs.io/en/latest/
+.. _pytest-cov: https://pytest-cov.readthedocs.io/en/latest/
 
 .. code-block:: bash
 
     (salishsea-tools)$ cd tools/SalishSeaTools/
-    (salishsea-tools)$ coverage run -m py.test
+    (salishsea-tools)$ pytest --cov=./
 
-and generate a test coverage report with:
+The test coverage report will be displayed below the test suite run output.
+
+Alternatively,
+you can use
 
 .. code-block:: bash
 
-    (salishsea-tools)$ coverage report
+    (salishsea-tools)$ pytest --cov=./ --cov-report html
 
-to produce a plain text report,
-or
+to produce an HTML report that you can view in your browser by opening
+:file:`tools/SalishSeaTools/htmlcov/index.html`.
 
-.. code-block:: bash
 
-    (salishsea-tools)$ coverage html
+.. _SalishSeaToolsContinuousIntegration:
+
+Continuous Integration
+----------------------
+
+The :kbd:`SalishSeaTools` package unit test suite is run and a coverage report is generated
+whenever changes are pushed to GitHub.
+The results are visible on the `repo actions page`_,
+from the green checkmarks beside commits on the `repo commits page`_,
+or from the green checkmark to the left of the "Latest commit" message on the
+`repo code overview page`_ .
+The testing coverage report is uploaded to `codecov.io`_
+
+.. _repo actions page: https://github.com/SalishSeaCast/SalishSeaTools/actions
+.. _repo commits page: https://github.com/SalishSeaCast/SalishSeaTools/commits/main
+.. _repo code overview page: https://github.com/SalishSeaCast/SalishSeaTools
+.. _codecov.io: https://app.codecov.io/gh/SalishSeaCast/SalishSeaTools
 
-to produce an HTML report that you can view in your browser by opening :file:`tools/SalishSeaTools/htmlcov/index.html`.
+The `GitHub Actions`_ workflow configuration that defines the continuous integration
+tasks is in the :file:`.github/workflows/pytest-with-coverage.yaml` file.
 
-The run the test suite under Python 2.7,
-create a Python 2.7 :ref:`SalishSeaToolsDevelopmentEnvironment`.
+.. _GitHub Actions: https://docs.github.com/en/actions
 
 
 .. _SalishSeaToolsVersionControlRepository:

SalishSeaTools/envs/environment-dev.yaml

@@ -49,7 +49,7 @@ dependencies:
 
   # For unit tests
   - coverage
-  - pytest
+  - pytest-cov
 
   # For documentation
   - nbsphinx==0.9.5

SalishSeaTools/envs/environment-test.yaml

@@ -0,0 +1,53 @@
+# conda environment description file for SalishSeaTools package testing environment
+#
+# Creates a conda environment in which the SalishSeaTools package unit tests and
+# coverage analysis can be run.
+# Primarily intended to create a conda environment for use in a GitHub Actions workflow.
+
+name: salishsea-tools-test
+
+channels:
+  - conda-forge
+  - nodefaults
+
+dependencies:
+  - arrow>=1.0.0
+  - bottleneck
+  - cliff
+  - cmocean
+  - f90nml
+  - gsw
+  - h5netcdf
+  - ipdb
+  - ipython
+  - jupyterlab
+  - lxml
+  - matplotlib
+  - netCDF4
+  - numpy
+  - openpyxl
+  - pandas
+  - pip
+  - pytz
+  - python-dateutil
+  - pyyaml
+  - requests
+  - retrying
+  - scipy
+  - tqdm
+  - xarray
+
+  # For unit tests and coverage monitoring
+  - coverage
+  - pytest-cov
+
+  # For documentation links checking
+  - sphinx=8.1.3
+  - sphinx-notfound-page=1.0.4
+  - sphinx-rtd-theme=3.0.0
+
+  - pip:
+    - angles
+
+    # Install the SalishSeaTools packages in editable mode
+    - --editable ../