Run tests with Nox#

Nox は、複数の Python バージョン間でテストを実行し、分離されたテスト環境を管理するための Python ベースの自動化ツールです。 TOML よりも Python ベースの構成を好む場合、または複雑な自動化ワークフローが必要な場合は、Nox が最適な選択肢です。

For more information about Nox, see the official Nox documentation or the Scientific Python guide to testing.

なぜノックスなのか？#

Nox is a great automation tool because it:

Is Python-based, making it accessible if you already know Python
Will create isolated environments to run workflows
標準テストを超えた複雑なカスタム自動化をサポート
複雑なビルドおよびテストのシナリオに柔軟かつ強力です

nox simplifies creating and managing testing environments. With nox, you can set up virtual environments and run tests across Python versions using the environment manager of your choice with a single command.

Noxをセットアップする#

To get started with Nox, you create a noxfile.py file at the root of your project directory. You then define commands using Python functions.

注釈

Nox installations

When you install and use Nox to run tests across different Python versions, Nox will create and manage individual venv environments for each Python version that you specify in the Nox function. Nox will manage each environment on its own.

Nox can also be used for other development tasks such as building documentation, creating your package distribution, and testing installations across both PyPI-related environments (e.g., venv, virtualenv) and conda (e.g., conda-forge).

Test environments#

By default, nox uses Python's built-in venv environment manager. A virtual environment (venv) is a self-contained Python environment that allows you to isolate and manage dependencies for different Python projects. It helps ensure that project-specific libraries and packages do not interfere with each other, promoting a clean and organized development environment.

venv環境のnox#

Below is an example of setting up Nox to run tests using venv, which is the built-in environment manager that comes with base Python.

Note that the example below assumes that you have setup your pyproject.toml to declare test dependencies using project.optional-dependencies:

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

[project]
name = "pyosPackage"
version = "0.1.0"
dependencies = [
  "geopandas",
  "xarray",
]

[project.optional-dependencies]
tests = ["pytest", "pytest-cov"]

With this setup, you can use session.install(".[tests]") to install your test dependencies. Notice that below one single Nox session allows you to run your tests on 4 different Python environments (Python 3.9, 3.10, 3.11, and 3.12).

注釈

これを実行するには、コンピューターに python3.9、python3.10、python3.11、および python3.12 がインストールされている必要があります。それ以外の場合、nox は不足しているバージョンのテストの実行をスキップします。

# This code would live in a noxfile.py file located at the root of your
# project directory
import nox

@nox.session(python=["3.9", "3.10", "3.11", "3.12"])
def test(session):
    # Install dependencies
    session.install(".[tests]")
    # Run tests
    session.run("pytest")

Above you create a Nox session in the form of a function with a @nox.session decorator. Notice that within the decorator you declare the versions of Python that you wish to run.

To run the above, you'd execute the following command, specifying which session with --session (sometimes shortened to -s). Your function above is called test, therefore the session name is test:

nox --session test

conda / mamba による nox#

Below is an example for setting up Nox to use mamba (or conda) for your environment manager. Unlike venv, conda can automatically install the various versions of Python that you need. You won't need to install all four Python versions if you use conda/mamba, like you do with venv.

注釈

nox で conda を動作させるには、コンピュータに conda か mamba のどちらかがインストールされていることを確認する必要があります。

# This code should live in your noxfile.py file
import nox

# The syntax below allows you to use mamba / conda as your environment
# manager. If you use this approach, you don't have to worry about installing
# different versions of Python

@nox.session(venv_backend='mamba', python=["3.9", "3.10", "3.11", "3.12"])
def test_mamba(session):
    """Nox function that installs dev requirements and runs tests on Python
    3.9 through 3.12.
    """
    # Install dev requirements
    session.conda_install(".[tests]")
    # Run tests using any parameters that you need
    session.run("pytest")

上記のセッションを実行するには、次のようにします:

nox --session test_mamba

ハッチvsノックス#

Hatch と Nox のどちらを選択するか迷っている場合は、メインのテストページの比較と推奨事項を参照してください。

要約すれば#

すでにパッケージングに Hatch を使用していて、すべてを 1 か所にまとめたい場合は、Hatch を選択してください
最大限の柔軟性が必要な場合、Python ベースの構成を好む場合、または複雑な自動化ワークフローが必要な場合は、Nox を選択してください

Next steps#

Nox を使用してローカルでテストを実行する方法を理解したので、継続的インテグレーションを使用してテストを自動的に実行するまたは Hatch を使用してテストを実行するについて学ぶことができます。