Hey there!
Got a Python project and need to make sure it works on every version of Python out there? Trust me, that can be a HUGE headache. But don't worry, I’ve got your back. In this guide, I’ll show you how to use Tox, Nox and CI/CD, awesome tools, to test your code across multiple Python versions.
And guess what? It’s easier than you think.
By the time you’re done reading this, you’ll be running tests like a pro across Python 3.8 to 3.13. We’ll keep things simple, fun, and totally actionable. Sound good? Let’s dive in.
Why Should You Even Care About Multi-Version Testing?
Picture this: You write some cool Python code, and it works on your computer. But then, BAM! A user emails you, saying it breaks on Python 3.9. You try it, and sure enough, something’s off.
Why?
Because Python’s got all these versions, and each one has its quirks. If you don’t test your code on multiple versions, you’re flying blind.
But the GOOD NEWS is, you don’t have to manually install a bunch of Python versions and run tests on each. That’s where Tox and Nox swoop in like superheroes.
What Are Tox and Nox?
Let’s break it down:
Tox: Think of it as a robot that tests your code in different Python environments. It’s super organized and follows your instructions from a simple tox.ini file. You tell Tox what to do, and it does it.
Nox: It’s like Tox, but cooler in some ways. Why? Because instead of a config file, you get to write a Python script (noxfile.py). Want to add custom logic or conditions? Nox has your back.
So which one’s better? Honestly, it depends. If you like things neat and straightforward, go with Tox. If you’re the creative type and love flexibility, Nox is your jam.
Let’s Build Something Cool
Here’s the deal:
We’re gonna create a mini project with two simple functions:
- Add two numbers.
- Subtract one number from another.
We’ll write some tests to make sure they work, and then we’ll use Tox and Nox to test them on Python versions from 3.8 to 3.13.
Sounds fun, right?
Here’s the file structure we’re working with:
tox-nox-python-test-automation/
├── tox_nox_python_test_automation/
│ ├── __init__.py
│ ├── main.py
│ └── calculator.py
├── tests/
│ ├── __init__.py
│ └── test_calculator.py
├── pyproject.toml
├── tox.ini
├── noxfile.py
├── README.md
Step 1: Write the Code
Here’s our calculator.py:
def add(a, b):
"""Returns the sum of two numbers."""
return a + b
def subtract(a, b):
"""Returns the difference of two numbers."""
return a - b
Simple, right? Let’s keep it that way.
Step 2: Write Some Tests
Time to make sure our code works. Here’s our test_calculator.py:
import pytest
from tox_nox_python_test_automation.calculator import add, subtract
@pytest.mark.parametrize("a, b, expected", [
(1, 2, 3),
(-1, 1, 0),
(0, 0, 0),
])
def test_add(a, b, expected):
assert add(a, b) == expected
@pytest.mark.parametrize("a, b, expected", [
(5, 3, 2),
(10, 5, 5),
(-1, -1, 0),
])
def test_subtract(a, b, expected):
assert subtract(a, b) == expected
We’re using pytest, a testing tool that’s basically the MVP of Python testing. If you’ve never used it, don’t sweat it, it’s super easy to pick up.
Step 3: Manage Dependencies with Poetry
Okay, so how do we make sure everyone working on this project uses the same dependencies? We use Poetry, which is like a supercharged requirements.txt file.
Here’s what our pyproject.toml looks like:
[tool.poetry]
name = "tox_nox_python_tests"
version = "0.1.0"
description = "Testing with multiple Python versions using Tox and Nox."
authors = ["Wallace Espindola <wallace.espindola@gmail.com>"]
license = "MIT"
[tool.poetry.dependencies]
python = "^3.8"
pytest = "^8.3"
nox = "^2024.10.9"
tox = "^4.23.2"
To install everything, just run:
poetry install
Step 4: Run unit tests with Pytest
You can run the basic unit tests this way:
poetry run pytest --verbose
And will see a standard unit test running output.
Step 5: Test with Tox
Tox is all about automation. Here’s our tox.ini:
[tox]
envlist = py38, py39, py310, py311, py312, py313
[testenv]
allowlist_externals = poetry
commands_pre =
poetry install --no-interaction --no-root
commands =
poetry run pytest
Run Tox with one command:
poetry run tox
And boom! Tox will test your code across every version of Python listed. See and example output here:
Step 6: Test with Nox
Want more control? Nox lets you get creative. Here’s our noxfile.py:
import nox
@nox.session(python=["3.8", "3.9", "3.10", "3.11", "3.12", "3.13"])
def tests(session):
session.install("poetry")
session.run("poetry", "install", "--no-interaction", "--no-root")
session.run("pytest")
Run Nox with:
poetry run nox
Now you’ve got full flexibility to add logic, skip environments, or do whatever else you need. See and example output here:
Step 7: Automate with CI/CD
Why stop at local testing? Let’s set this up to run automatically on GitHub Actions and GitLab CI/CD.
GitHub Actions
Here’s a workflow file .github/workflows/python-tests.yml:
name: Python Tests
on:
push:
branches:
- main
pull_request:
jobs:
test:
runs-on: ubuntu-latest
strategy:
matrix:
python-version: [3.8, 3.9, 3.10, 3.11, 3.12, 3.13]
steps:
- uses: actions/checkout@v3
- name: Set up Python
uses: actions/setup-python@v4
with:
python-version: ${{ matrix.python-version }}
- name: Install Poetry
run: pip install poetry
- name: Install Dependencies
run: poetry install --no-interaction --no-root
- name: Run Tests with Tox
run: poetry run tox
- name: Run Tests with Nox
run: poetry run nox
GitLab CI/CD
Here’s a .gitlab-ci.yml:
stages:
- test
tox-tests:
stage: test
image: python:${PYTHON_VERSION}
variables:
PIP_CACHE_DIR: "$CI_PROJECT_DIR/.cache/pip"
before_script:
- pip install poetry
- poetry install --no-interaction --no-root
script:
- poetry run tox
cache:
paths:
- .tox/
- .cache/pip/
parallel:
matrix:
- PYTHON_VERSION: ["3.8", "3.9", "3.10", "3.11", "3.12", "3.13"]
Let’s Wrap It Up
You did it! You now know how to test Python code across multiple versions using Tox, Nox, and Poetry.
Here’s what to remember:
- Tox is your go-to for simple, automated testing.
- Nox gives you the freedom to customize.
- Poetry makes managing dependencies a breeze.
- CI/CD ensures your tests run automatically.
References, of course
This project uses Tox, Nox, Poetry, and Pytest for test automation. For detailed documentation, take a look at:
Tox Documentation
Nox Documentation
Poetry Documentation
Pytest Documentation
Need the full code and examples? Check out the repo on GitHub: tox-nox-python-tests.
For other interesting subjects and technical discussions, check my LinkedIn page.
Now go out there and make your Python projects bulletproof! 🚀
Top comments (0)