Fixed env for image comparison testing, test via CI

.github/workflows/run-image-comparison.yml

@@ -0,0 +1,59 @@
+# Run cf-plot tests including image comparison, in the reference environment
+name: Run image comparison testing
+
+on:
+  pull_request:
+    types: [opened, reopened, ready_for_review]
+    branches:
+      - main
+
+jobs:
+  test-image-comparison:
+    strategy:
+      fail-fast: true
+      matrix:
+        os: [ubuntu-latest, macos-15-intel]
+
+    runs-on: ${{ matrix.os }}
+
+    steps:
+      - name: Checkout cf-plot
+        uses: actions/checkout@v7
+        with:
+          path: main
+
+      - name: Setup reference Conda environment
+        uses: conda-incubator/setup-miniconda@v4
+        with:
+          auto-update-conda: true
+          miniconda-version: "latest"
+          environment-file: main/cfplot-test-env.yml
+          activate-environment: cfplot-test-env
+
+      - name: Check reference environment
+        shell: bash -l {0}
+        run: |
+          python --version
+          python -c "import sys; assert sys.version_info[:3] == (3, 14, 8), f'Expected Python 3.14.8, got {sys.version}'"
+
+          echo "*Conda report:*"
+          conda info
+          conda list
+
+          echo "*Pip report:*"
+          pip --version
+          pip list
+
+      - name: Install cf-plot from source
+        shell: bash -l {0}
+        working-directory: ${{ github.workspace }}/main
+        run: pip install --no-deps -e .
+
+      - name: Run full test suite including image comparison
+        shell: bash -l {0}
+        working-directory: ${{ github.workspace }}/main
+        run: pytest tests
+
+      - name: Notify about a completed run
+        if: success()
+        run: echo "Image comparison testing completed successfully on ${{ matrix.os }}."

.github/workflows/run-tests.yml

@@ -0,0 +1,197 @@
+
+# A GitHub Action to run the cf-plot test suite after PR events on main.
+name: Run all testing excluding image comparison aspect
+
+# Triggers the workflow on PR events targeting main.
+on:
+  # For now, at least, do not enable on push to save on limited usage resource
+  #push:
+  #  branches:
+  #    - main
+  pull_request:
+    # 'reopened' enables manual retrigger via close & re-open. Disable for all
+    # edits to manage limited resource (PRs often change before merge-ready).
+    types: [opened, reopened, ready_for_review]
+    branches:
+      - main
+
+jobs:
+  # Test on Linux and Intel macOS.
+
+  # Test the suite on Linux (with Ubuntu as representative distribution).
+  test-on-linux:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: true
+      matrix:
+        # DO NOT RUN on the latest Python, because we run this for the
+        # image comparison workflow so it would just be duplicating the
+        # same test.
+        python-version: ["3.11", "3.12", "3.13"]
+
+    steps:
+      - name: Checkout cf-plot
+        uses: actions/checkout@v7
+        with:
+          path: main
+
+      - name: Notify about setup
+        run: echo "Now setting up the environment for the cf-plot test suite..."
+
+      - name: Checkout the current cf-python main to use as a dependency
+        uses: actions/checkout@v7
+        with:
+          repository: NCAS-CMS/cf-python
+          path: cf-python
+
+      - name: Checkout the current cfdm main to use as a dependency
+        uses: actions/checkout@v7
+        with:
+          repository: NCAS-CMS/cfdm
+          path: cfdm
+
+      # Set up Conda for scientific Python dependencies.
+      - name: Setup Miniconda
+        uses: conda-incubator/setup-miniconda@v4
+        with:
+          auto-update-conda: true
+          miniconda-version: "latest"
+          activate-environment: cf-latest
+          python-version: ${{ matrix.python-version }}
+          channels: ncas, conda-forge
+
+      # Report the configured environment.
+      - name: Check conda and pip config
+        shell: bash -l {0}
+        run: |
+          echo "*Conda report:*"
+          conda info
+          conda list
+          conda config --show-sources
+          conda config --show
+          echo "*Pip report:*"
+          pip --version
+          pip list
+
+      # Install the scientific dependencies required by cf-plot and cf-python.
+      - name: Install dependencies
+        shell: bash -l {0}
+        run: |
+          conda install -c ncas -c conda-forge cf-python udunits2
+          conda install -c conda-forge mpich esmpy cartopy scipy matplotlib pytest
+
+      # Install cfdm, cf-python and cf-plot from source.
+      - name: Install development versions of cf* dependencies and cf-plot
+        shell: bash -l {0}
+        run: |
+          cd cfdm
+          pip install -e .
+
+          cd ../cf-python
+          pip install --no-deps -e .
+
+          cd ../main
+          pip install --no-deps -e .
+
+      - name: Notify about starting testing
+        run: echo "Setup complete. Now starting to run the cf-plot test suite..."
+
+      # Run the cf-plot test suite.
+      - name: Run test suite
+        shell: bash -l {0}
+        working-directory: ${{ github.workspace }}/main
+        run: pytest tests --skip-image-comparison
+
+      - name: Notify about a completed run
+        run: |
+          echo "The cf-plot test suite on Linux has completed."
+
+  # Test on Intel macOS rather than ARM64, which is not compatible with
+  # the existing Conda installation approach.
+  test-on-mac:
+    runs-on: macos-15-intel
+    strategy:
+      fail-fast: true
+      matrix:
+        # DO NOT RUN on the latest Python, because we run this for the
+        # image comparison workflow so it would just be duplicating the
+        # same test.
+        python-version: ["3.11", "3.12", "3.13"]
+
+    steps:
+      - name: Checkout cf-plot
+        uses: actions/checkout@v7
+        with:
+          path: main
+
+      - name: Notify about setup
+        run: echo "Now setting up the environment for the cf-plot test suite..."
+
+      - name: Checkout the current cf-python main to use as a dependency
+        uses: actions/checkout@v7
+        with:
+          repository: NCAS-CMS/cf-python
+          path: cf-python
+
+      - name: Checkout the current cfdm main to use as a dependency
+        uses: actions/checkout@v7
+        with:
+          repository: NCAS-CMS/cfdm
+          path: cfdm
+
+      # Set up Conda for scientific Python dependencies.
+      - name: Setup Miniconda
+        uses: conda-incubator/setup-miniconda@v4
+        with:
+          auto-update-conda: true
+          miniconda-version: "latest"
+          activate-environment: cf-latest
+          python-version: ${{ matrix.python-version }}
+          channels: ncas, conda-forge
+
+      # Report the configured environment.
+      - name: Check conda and pip config
+        shell: bash -l {0}
+        run: |
+          echo "*Conda report:*"
+          conda info
+          conda list
+          conda config --show-sources
+          conda config --show
+          echo "*Pip report:*"
+          pip --version
+          pip list
+
+      # Install the scientific dependencies required by cf-plot and cf-python.
+      - name: Install dependencies
+        shell: bash -l {0}
+        run: |
+          conda install -c ncas -c conda-forge cf-python udunits2
+          conda install -c conda-forge mpich esmpy cartopy scipy matplotlib pytest
+
+      # Install cfunits, cfdm, cf-python and cf-plot from source.
+      - name: Install development versions of dependencies and cf-plot
+        shell: bash -l {0}
+        run: |
+          cd cfdm
+          pip install -e .
+
+          cd ../cf-python
+          pip install --no-deps -e .
+
+          cd ../main
+          pip install --no-deps -e .
+
+      - name: Notify about starting testing
+        run: echo "Setup complete. Now starting to run the cf-plot test suite..."
+
+      # Run the cf-plot test suite.
+      - name: Run test suite
+        shell: bash -l {0}
+        working-directory: ${{ github.workspace }}/main
+        run: pytest tests --skip-image-comparison
+
+      - name: Notify about a completed run
+        run: |
+          echo "The cf-plot test suite on Mac has completed."
+          echo "You may now inspect the results."

README.md

@@ -95,6 +95,45 @@ More detail about installation is provided on the
 (`https://ncas-cms.github.io/cf-plot/installation.html`)
 of the documentation.
 
+### Testing
+
+To run the full test suite, call from the repo root:
+
+``` bash
+$ pytest tests
+```
+
+Note however this calls image comparison testing on plot outputs and exact
+image comparison depends on the environment (libraries and versions) used.
+So they may fail if your environment differs from that which was used to
+generate the reference images. Therefore, to allow like-for-like comparison,
+a specific testing conda environment is provided, ``cfplot-test-env.yml``.
+With this environment enabled, the image comparison should pass. Note we
+recommend use of `mamba` for environment creation/solving, but `conda`
+will also work.
+
+```console
+$ # Deactivate all other environments present first
+$ mamba env create --file cfplot-test-env.yml --name cfplot-test-env
+$ conda activate cfplot-test-env
+$ pytest tests
+```
+
+However you can disable this aspect with the ``--skip-image-comparison``
+or equivalently ``-I`` option to the cf-plot test suite run with `pytest`,
+so that only the functional tests run. This is advised when you use any
+environment other than the above, except where some library version
+differs for the purpose of regression testing on that versioning change.
+
+```console
+$ pytest tests -I
+```
+
+> [!NOTE]
+> More comprehensive testing across different environments is under development
+> but is not yet available. For now, use the reference environment to test with.
+
+
 ### Contributing
 
 Everyone is welcome to contribute to cf-plot in the form