diff --git a/.github/workflows/pytest-with-coverage.yaml b/.github/workflows/pytest-with-coverage.yaml new file mode 100644 index 00000000..e967e747 --- /dev/null +++ b/.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 }} diff --git a/SalishSeaTools/docs/development.rst b/SalishSeaTools/docs/development.rst index 7df18b02..eb2f0d62 100644 --- a/SalishSeaTools/docs/development.rst +++ b/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: diff --git a/SalishSeaTools/envs/environment-dev.yaml b/SalishSeaTools/envs/environment-dev.yaml index 83bfbe22..508c2fcd 100644 --- a/SalishSeaTools/envs/environment-dev.yaml +++ b/SalishSeaTools/envs/environment-dev.yaml @@ -49,7 +49,7 @@ dependencies: # For unit tests - coverage - - pytest + - pytest-cov # For documentation - nbsphinx==0.9.5 diff --git a/SalishSeaTools/envs/environment-test.yaml b/SalishSeaTools/envs/environment-test.yaml new file mode 100644 index 00000000..9dba3ca8 --- /dev/null +++ b/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 ../