tox

tox ist ein Werkzeug zur Automatisierung der Verwaltung von Virtualenv-Umgebungen und zum Testen mit mehreren Interpreterkonfigurationen.

Siehe auch

• tox plugins

1. Installation

   Linux/macOS

   $ bin/python -m pip install tox
   

   Windows

   C:> Scripts\python -m pip install tox
   

2. Konfiguration

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

   [tox]
   envlist = py27,py38,py39
   
   [testenv]
   deps = pytest
   commands =
       pytest
   

3. Ausführen

   Mit bin/tox werden dann die folgenden Schritte durchlaufen:

   1. Optional erstellen eines Python-Package mit

      $ 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
      

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.

   Siehe auch

   • Build & test Python

   • Workflow syntax

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.