tests.yml

name: Tests

# define when workflow runs
on:
  # run on push to main
  push:
    # in both cases ignore markdown docs
    paths-ignore:
      - "docs/**"
      - "*.md"
  # run on pr vs main
  pull_request:
    paths-ignore:
      - "docs/**"
      - "*.md"

# define the jobs that make up the workflow
jobs:
  # define a job called tests
  tests:
    # define the name of a specific job
    name: ${{ matrix.session }} ${{ matrix.python-version }} / ${{ matrix.os }}
    # needed when we have a matrix config with different op systems
    runs-on: ${{ matrix.os }}
    # define the matrix of jobs
    strategy:
      # if any job fails cancel all of them
      fail-fast: false
      # define our matrix as all op systems and 4 python versions
      matrix:
        os: [ubuntu-latest, macos-latest, windows-latest]
        python-version: [3.7, 3.8, 3.9]
        session: [mypy, tests]

    # configure --session for nox to only run a specifc subset of test
    # this is equiv to running e.g. nox --session mypy
    # sessions are specified above in the matrix spec
    env:
      NOXSESSION: ${{ matrix.session }}

    steps:
      # check out this repo onto github runner
      - name: Check out the repository
        uses: actions/checkout@v2.4.0
      # setup specified matrix version of python
      - name: Set up Python ${{ matrix.python-version }}
        uses: actions/setup-python@v2.2.2
        with:
          python-version: ${{ matrix.python-version }}
      
      # get the version of build tools defined by constraints file
      # to keep things replicable and deterministic we pin build tools in CI
      - name: Upgrade pip
        run: |
          pip install --constraint=.github/workflows/constraints.txt pip
          pip --version
      - name: Install Poetry
        run: |
          pip install --constraint=.github/workflows/constraints.txt poetry
          poetry --version
      # install both nox and nox-poetry so when nox builds environments
      # it pulls in dependencies according to pyproject.toml using poetry
      - name: Install Nox
        run: |
          pip install --constraint=.github/workflows/constraints.txt nox nox-poetry
          nox --version
      # run nox testing using selected python version
      # session is passed by env.NOXSESSION above
      - name: Run Nox
        run: |
          nox --force-color --python=${{ matrix.python-version }}
      # if we are running 'tests' session then upload coverage data
      # this ensures that the coverage reports per runner are stored
      # so that the next job (coverage) can grab them and combine them
      # so we run coverage tests per matrix build
      # but combine them to form one coverage report
      - name: Upload coverage data
        if: always() && matrix.session == 'tests'
        uses: "actions/upload-artifact@v2.2.4"
        with:
          name: coverage-data
          path: ".coverage.*"
  
  # define job to run coverage report
  coverage:
    # just need to run on one operating system
    runs-on: ubuntu-latest
    needs: tests
    steps:
      # check our repo and use 3.9 python
      - name: Check out the repository
        uses: actions/checkout@v2.4.0

      - name: Set up Python 3.9
        uses: actions/setup-python@v2.2.2
        with:
          python-version: 3.9

      # install CI build tools
      - name: Upgrade pip
        run: |
          pip install --constraint=.github/workflows/constraints.txt pip
          pip --version
      - name: Install Poetry
        run: |
          pip install --constraint=.github/workflows/constraints.txt poetry
          poetry --version
      - name: Install Nox
        run: |
          pip install --constraint=.github/workflows/constraints.txt nox nox-poetry
          nox --version
      # download the coverage artifact produced by tests job, session=tests
      - name: Download coverage data
        uses: actions/download-artifact@v2.0.10
        with:
          name: coverage-data
      # specifically run the noxfile.py coverage session which combines
      - name: Combine coverage data and display human readable report
        run: |
          nox --force-color --session=coverage
      # create and upload coverage report
      # requires logging into https://codecov.io/ with github first
      # then report gets uploaded here and docs can pull it in
      # as per top of docs/index.md
      - name: Create coverage report
        run: |
          nox --force-color --session=coverage -- xml
      - name: Upload coverage report
        uses: codecov/codecov-action@v2.0.2