GitHub Actions¶

TL;DR: GitHub actions will run your unit tests for you and tell you if your tools are passing or failing. If you're using tests, this will up your game.

What are unit tests?¶

Unit tests are small snippets of code that use a small part of your tool, and check that it's functional. Basic tests might just ensure that certain parts of your tool install properly. More advanced tests will go through a short workflow with your tool, and check that it provides the right answer.

Where do actions come in?¶

Once you've written tests, you may run them on your local machine to check that your code passes. If you use GitHub actions, you can run your tests every time you merge a new change, and you can run it on different architecture to check that your tests pass on e.g. Python 3.7 and Python 3.8.

1. Make an .yaml file¶

To start out, in your project you'll have to add a directory

mkdir .github
mkdir .github/workflows

And then in that directory you're going to make a .yaml file, which will contain all the information you want to run your action. Here's an example of my test.yaml file for running tests in one of my packages

name: pytest

on: [push, pull request]

jobs:
  build:

    runs-on: ubuntu-latest
    strategy:
      matrix:
        python-version: [3.7, 3.8, 3.9]

    steps:
    - uses: actions/checkout@v2
    - name: Set up Python ${{ matrix.python-version }}
      uses: actions/setup-python@v2
      with:
        python-version: ${{ matrix.python-version }}
    - name: Install dependencies
      run: |
        python -m pip install --upgrade pip
        python -m pip install poetry
        poetry install
    - name: Test with pytest
      run: |
        make pytest

This says, whenever there is a push to the main branch, run the following on Python versions 3.7, 3.8 and 3.9. First it installs poetry, then it installs the packages, and then it runs make pytest. I have a Makefile in the directory, which has a command named pytest which automatically runs my tests in this package. This is a great place to start for GitHub actions.

2. Push to GitHub¶

Once these files, in this directory structure, are archived at GitHub, your actions should trigger automatically based on the on line in the .yaml file. At the moment it's set up to trigger any time there is a push, or pull request.