Run tests for your Python package#

パッケージがユーザーに対して確実に動作するようにするには、さまざまな Python バージョンおよびオペレーティング システム間でテストを実行することが重要です。ユーザーは、あなたとは異なるバージョンの Python やオペレーティング システムを実行している可能性があります。

このページでは、隔離された環境でローカルにテストを実行し、複数の Python バージョンにわたってテストを実行する方法を説明します。 Hatch と Nox という 2 つの主要な自動化ツールについて学習します。次のレッスンでは、継続的インテグレーション (CI) でオンラインでテストを実行する方法を学習します。

Why run tests across multiple environments?#

コンピューター上でパッケージを開発すると、パッケージは 1 つの特定の環境 (Python バージョン、オペレーティング システム、インストールされている依存関係) で動作します。ただし、ユーザーはさまざまな環境でコードを実行します。複数の Python バージョンとオペレーティング システムでテストを実行することで、ユーザーが発見する前に互換性の問題を発見できます。

さらに、隔離された環境でテストを実行すると、コンピューターに予期しない依存関係がインストールされているためではなく、コードによってテストが合格することが保証されます。これにより、他の人がインストールしたときに自分のパッケージが動作するという確信が得られます。

このページでは、隔離された環境でテストを実行したり、Python のバージョンを越えてテストを実行したりするために使えるツールについて学びます。

参考

関連ページ:

Tools to run your tests#

There are three categories of tools that will make it easier to setup and run your tests in various environments:

  1. Testing framework (pytest): Provides the syntax and tools for writing and running your tests. Learn more from the pytest documentation. Below you will learn about pytest, the most commonly used testing framework in the scientific Python ecosystem. Testing frameworks are essential for running tests, but they don't provide an easy way to run tests across Python versions or in isolated environments—that's where automation tools come in.

  2. 自動化ツール (Nox、Tox、Hatch): 単一のコマンドで、隔離された環境で複数の Python バージョンにわたってテストを実行できます。以下では、Hatch と Nox に焦点を当てます。これらのツールは仮想環境を自動的に作成し、テストが一貫して実行されることを保証します。ただし、通常はローカル オペレーティング システム上でのみテストされます。

  3. 継続的インテグレーション (CI): さまざまなオペレーティング システム (Windows、Mac、Linux) および Python バージョン間でオンラインでテストを実行します。 CI は GitHub Actions などのプラットフォームと統合して、すべてのプル リクエストとコード変更を自動的にテストします。

CI についてはこちらをご覧ください。

簡単な比較: 各ツールの機能#

Testing Framework (pytest):

  • 現在の Python 環境でローカルにテストを実行します

  • テスト (アサーション、フィクスチャなど) を作成するためのコア構文を提供します。

  • プラグインで拡張可能 (カバレッジ用の pytest-cov など)

Automation Tools (Nox, Tox, Hatch):

  • Run tests locally across multiple Python versions

  • 隔離された仮想環境を自動的に作成および管理する

  • ドキュメントの作成などの他のタスクを自動化できます

  • テスト環境を簡単に再現できるようにする

Continuous Integration (GitHub Actions):

  • プルリクエストごとにオンラインでテストを自動的に実行します

  • Tests across different operating systems (Windows, Mac, Linux)

  • Tests across multiple Python versions in parallel

  • 導入、リリース、その他のワークフローを自動化できます

テストを実行するには、どのテストフレームワーク/パッケージを使用すればよいですか？#

パッケージテストのビルドと実行には Pytest を使うことを推奨します。 Pytest は Python のエコシステムで最もよく使われているテストツールです。

Pytestパッケージ には、以下のような機能を追加するために使用できる多くの拡張機能もあります：

  • pytest-cov allows you to analyze the code coverage of your package during your tests, and generates a report that you can upload to codecov.

注釈

お使いのエディタや IDE には、テストを実行したり、ブレークポイントを設定したり、 -no-cov フラグを切り替えたりするための便利な機能が追加されているかもしれません。 詳しくはエディタのドキュメントを参照してください。

pytest を使ってテストを実行する#

pytest を使用している場合、テストをローカルで実行することができます:

pytest

また、特定のテストファイル - このファイルを "test_module.py" と呼ぶことにします - を実行したい場合は、次のようにします:

pytest test_module.py

Learn more about pytest here.

あなたのコンピュータで pytest を実行すると、現在有効になっている Python 環境でテストが実行されます。 つまり、テストは単一のバージョンのPythonで、ローカルで実行しているオペレーティングシステム上でのみ実行されます。

自動化ツールは、様々な Python 環境でテストを実行するプロセスを単純化することができます。

オペレーティングシステムをまたいだテスト

If you want to run your tests on different operating systems you can use continuous integration. Learn more here.

テストの実行を自動化するツール#

一つのコマンドで様々な Python のバージョンや特定の環境でテストを実行するには、 nox や tox のような自動化ツールを使うことができます。 nox も tox も、隔離された仮想環境を作成することができます。 これにより、複数の環境や Python のバージョンをまたいだテストを簡単に実行することができます。

Hatch は チュートリアル および Python パッケージ テンプレート で使用するデフォルト ツールであるため、このページでは Hatch に焦点を当てます。

If you are not a hatch fan, then Nox is an alternative tool that we cover in the next lesson. nox is a Python-based automation tool that builds upon the features of both make and tox. nox is designed to simplify and streamline testing and development workflows. Everything that you do with nox can be implemented using a Python-based interface. You will learn more about using nox here.

その他の自動化ツール

  • Tox は自動化ツールで、ドキュメントのビルドや、Pythonの様々なバージョン間でのテストの実行など、一般的なステップをサポートしています。

  • Make is a build automation tool that some developers use for running tests due to its versatility. However, Make's unique syntax can be challenging to learn, and it won't manage environments for you like Hatch and Nox do.

Run tests with Hatch#

Hatch は、テスト実行機能を pyproject.toml に直接統合する、最新の Python パッケージングおよび環境マネージャーです。 Nox (別の noxfile.py を使用する) とは異なり、Hatch はすべてのプロジェクト構成を 1 か所に保持するため、ワークフローのパッケージ化にすでに Hatch を使用している場合に最適です。

なぜテストのためにハッチするのか?#

  • 設定はプロジェクトのメタデータとともに pyproject.toml に保存されます

  • Hatch のパッケージ化およびビルド ワークフローとシームレスに統合

  • (Nox とは異なり) 別の Python ファイルは必要ありません

  • 標準化されたテスト環境をチーム全体で簡単に共有

Setting up Hatch environments#

Hatch environments can be defined in pyproject.toml. These environments can be used to specify what Hatch needs to run the tests for the package. Test dependencies can be listed individually under [tool.hatch.envs.test], but if packages have already been grouped together under a name, those groups can be listed here instead. Using named groups keeps the dependencies in one place and avoids duplication.

The additional tools or options to run with the tests is specified under [tool.hatch.envs.test.scripts].

[tool.hatch.envs.test]
dependency-groups = [
    "test",
]

[tool.hatch.envs.test.scripts]
run = "pytest {args:--cov=test --cov-report=term-missing --cov-report=xml}"

For a complete example, see our packaging template tutorial which shows a full pyproject.toml configuration.

Hatch を使用したテストの実行#

テスト環境を定義したら、簡単なコマンドでテストを実行できます。

List available environments:

hatch env show

テスト環境で pytest を実行します:

# This command is how tests are run if you use the pyos-package-template
hatch run test:run

Testing across Python versions#

To test across multiple Python versions, define a matrix in your pyproject.toml under [[tool.hatch.envs.test.matrix]]:

[tool.hatch.envs.test]
...
...

[[tool.hatch.envs.test.matrix]]
python = ["3.10", "3.11", "3.12"]

次に、単一のコマンドですべてのバージョンを実行します。

hatch run test:run

Hatch は、Python 3.10、3.11、および 3.12 でテストを自動的に実行します。特定の Python バージョンのみをテストしたい場合:

hatch run test.py3.11:run

GitHub アクションでのハッチの使用#

ハッチは CI/CD とうまく統合されます。最小限の GitHub Actions セットアップは次のとおりです。

name: Run tests

on:
  pull_request:
  push:
    branches:
      - main

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@8c6903cd8c0fde910a37f88322edcfb5dd907a8 # v4
      - name: Install dependencies
        run: |
          python -m pip install --upgrade pip
          python -m pip install hatch
      - run: hatch run test:run

テストの依存関係はすべて pyproject.toml の dependency-group テーブルで宣言されているため、CI 環境は再現可能であり、ローカル テストに使用している環境と一貫性があります。

Nox と Hatch: 適切なツールの選択#

Hatch と Nox は両方とも、Python バージョン間でテストを実行するための優れた自動化ツール/タスク ランナーです。どちらがワークフローに適しているかを判断するために、これらを比較する方法は次のとおりです。

ハッチ#

  • 構成: Hatch は「宣言的」構成アプローチを使用します。環境に何が入るかを伝えると、Hatch が環境を作成できるようになります。すべての構成設定は、プロジェクトのメタデータとともに「pyproject.toml」内に存在します。

  • 統合: Hatch は、統合された自動化/タスク ランナーも備えたパッケージ管理ツールです。 Hatch を使用すると、パッケージ化と自動化のすべてのニーズに同じツールを使用することになります。

  • 学習曲線: コードベースのワークフローよりも宣言的な構成を好む場合は簡単です

  • パッケージ化の範囲 Hatch は、テストとパッケージ化に重点を置いた単純なワークフローに適しています。より複雑なビルドを使用している場合、または非純粋な Python パッケージを作成している場合は、Nox を使用することをお勧めします。これについては、科学的な Python 開発ガイドに詳細が記載されています。

  • 最適な用途: パッケージ化に Hatch を使用しているチーム、または 1 か所で標準化された構成を必要としているチーム

ノックス#

  • 構成: 最大限の柔軟性を実現する「noxfile.py」経由の Python 駆動

  • カスタマイズ: カスタム ロジックが必要な複雑なワークフローに最適

  • 学習曲線: すでに Python を知っており、柔軟なセッション制御が必要な場合は簡単です

  • 最適な用途: 複雑な自動化のニーズ、テストと並行してドキュメントを構築する、または標準モデルに適合しないワークフロー

私たちが推奨するもの#

パッケージ化に Hatch を使用している場合: テストにも Hatch を使用します。すべてを 1 か所で、一貫した 1 つのツールで入手できます。

最大限の柔軟性が必要な場合: Nox を選択してください。 Python ベースのアプローチにより、ほぼすべてのワークフローを実装できます。

始めたばかりの場合: Hatch から始めます。設定も理解も簡単で、必要に応じていつでも Nox に切り替えることができます。

Both tools are good choices. For a more comprehensive guide to using Nox, see Run tests with Nox and the Scientific Python testing guide.

Next steps#

Python のバージョン間でテストをローカルで実行する方法を理解したので、継続的インテグレーションを使用した GitHub Actions でのテストの自動実行 について学習できます。パッケージの テスト タイプ および 書き込みテスト を確認することもできます。