tox

tox ist ein Tool zur Automatisierung des virtualenv-Environment-Management und zum Testen mit mehreren Interpreter-Konfigurationen.

Mit tox könnt ihr komplexe Multiparameter-Testmatrizen über eine einfache Konfigurationsdatei im INI-Stil konfigurieren.

Beispiel

Erstellt eine tox.ini-Datei, z.B.:

[tox]
envlist = py27,py36

[testenv]
deps = pytest
commands =
    pytest

Beim Aufrufen von pipenv run tox werden dann die folgenden Schritte durchlaufen:

  1. Optional erstellen eines Python-Package mit

    $ pipenv run python setup.py sdist
    
  2. Erstellen der in envlist angegebenen Umgebungen

    In jeder dieser Umgebungen werden dann

    1. die Abhängigkeiten und Pakete installiert

    2. die Befehle aus commands ausgeführt

  3. Erstellen eines Reports mit den Ergebnissen aus jeder der Umgebungen, z.B.:

    ____________________ summary ____________________
    py27: commands succeeded
    ERROR:   py36: commands failed
    

Siehe auch

Installation

$ pipenv install tox

Bemerkung

Falls ihr pipenv noch nicht installiert habt, findet ihr eine Anleitung hierzu unter Jupyter Notebook installieren.

Siehe auch

GitHub-Actions

Wenn euer Projekt auf GitHub gehostet ist, könnt ihr GitHub-Actions verwenden um automatisiert eure Tests in verschiedenen Umgebungen ausführen zu können. Dabei sind eine ganze Reihe von Umgebungen für die GitHub-Actions verfügbar: github.com/actions/virtual-environments.

  1. Um eine GitHub-Action in eurem Projekt zu erstellen, klickt auf Actions ‣ set up a workflow yourself. Dies erstellt üblicherweise eine Datei .github/workflows/main.yml.

  2. Gebt dieser Datei einen aussagekräftigeren Namen. Wir verwenden hierfür üblicherweise ci.yml, wobei ci für Continuous Integration, (Englisch: Kontinuierliche Integration) steht.

  3. Die vorausgefüllte YAML-Datei ist für unsere Zwecke wenig hilfreich. Ihr könnt den Text ersetzen, z.B. mit:

name: CI

on:
  push:
    branches: ["main"]
  pull_request:
    branches: ["main"]
  workflow_dispatch:

jobs:
  tests:
    name: "Python ${{ matrix.python-version }}"
    runs-on: "ubuntu-latest"
    env:
      USING_COVERAGE: '3.6,3.8'

    strategy:
      matrix:
        python-version: ["3.6", "3.7", "3.8"]

    steps:
      - uses: "actions/checkout@v2"
      - uses: "actions/setup-python@v2"
        with:
          python-version: "${{ matrix.python-version }}"
      - name: "Install dependencies"
        run: |
          set -xe
          python -VV
          python -m site
          python -m pip install --upgrade pip setuptools wheel
          python -m pip install --upgrade coverage[toml] virtualenv tox tox-gh-actions

      - name: "Run tox targets for ${{ matrix.python-version }}"
        run: "python -m tox"

Bemerkung

Passt ggf. die Python-Versionen in python-version an; ihr müsst jedoch nicht auch die Umgebungsvariable in USING_COVERAGE ändern, da dies durch das tox-Plugin tox-gh-actions (siehe unten) erfolgt.

  1. Anschließend könnt ihr auf Start commit klicken. Da wir noch weitere Änderungen vornehmen wollen bevor die Tests automatisiert ausgeführt werden sollen, wählen wir Create a new branch for this commit and start a pull request und als Name für den neuen Branch github-actions. Schließlich könnt ihr auf Create pull request klicken.

  2. Um nun in den neuen Branch zu wechseln, gehen wir zu Code ‣ main ‣ github-actions.

  3. tox-gh-actions vereinfacht das Ausführen von tox in GitHub-Actions indem es als Umgebung für die Tests diejenige bereitstellt, die auch tox selbst verwendet. Hierfür müssen wir jedoch noch unsere tox.ini-Datei anpassen, z.B.:

    [gh-actions]
    python =
        3.6: py36
        3.7: py37, docs
        3.8: py38, lint, typing, changelog
    

    Dies ordnet GitHub-Actions tox-Umgebungen zu.

    Bemerkung

    • Es müssen nicht alle Varianten eurer Umgebung angegeben werden. Dies unterscheidet tox-gh-actions von tox -e py.

    • Stellt sicher, dass die Versionen im [gh-actions]-Abschnitt mit den verfügbaren Python-Versionen und ggf. mit denen in den GitHub-Actions für Git pre-commit Hooks übereinstimmen.

    • Da alle Tests für eine spezifische Python-Version nacheinander in einem Container ausgeführt werden, gehen hierbei die Vorteile der parallelen Ausführung verloren.

  4. Nun könnt ihr in eurer README.rst-Datei noch ein Badge eures CI-Status hinzufügen, z.B. mit:

    .. image:: https://github.com/YOU/YOUR_PROJECT/workflows/CI/badge.svg?branch=main
         :target: https://github.com/YOU/YOUR_PROJECT/actions?workflow=CI
         :alt: CI Status
    
  5. Die Code-Abdeckung könnt ihr auf Codecov veröffentlichen, s.a. Codecov und GitHub-Actions.

  6. Ihr könnt auch noch ein Badge für die Code-Abdeckung in eurer README.rst-Datei anzeigen, s.a. Codecov Badge.