Python パッケージのテストを実行する

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

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

複数の環境でテストを実行する理由は?

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

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

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

参考

関連ページ:

• テスト スイートの作成に関するベスト プラクティスについては、テストの作成

• テストの種類 で単体テスト、統合テスト、エンドツーエンドテストを理解する

• CI を使用してオンラインでテストを実行する (GitHub Actions セットアップ用)

• コード カバレッジ は、テストがカバーするコードの量を測定します。

テストを実行するためのツール

さまざまな環境でテストのセットアップと実行を容易にするツールには、3つのカテゴリーがあります:

1. テストフレームワーク (pytest): テストを書いて実行するための構文とツールを提供します。詳しくは pytest ドキュメント を参照してください。以下では、科学 Python エコシステムで最もよく使われているテストフレームワークである pytest について学びます。テストフレームワークはテストの実行に不可欠ですが、複数の Python バージョンや隔離された環境でテストを簡単に実行する方法は提供していません。そこで登場するのが自動化ツールです。

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

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

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

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

テストフレームワーク (pytest):

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

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

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

自動化ツール (Nox、Tox、Hatch):

• ローカルで複数の Python バージョンにまたがってテストを実行する

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

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

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

継続的インテグレーション (GitHub Actions):

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

• さまざまなオペレーティングシステム (Windows、Mac、Linux) にまたがるテスト

• 複数の Python バージョンのテストを並行して実行する

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

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

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

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

• pytest-cov を使うと、テスト中にパッケージのコードカバレッジを分析し、codecov にアップロードできるレポートを生成できます。

注釈

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

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

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

pytest

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

pytest test_module.py

pytest について詳しくはこちらをご覧ください。

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

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

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

異なるオペレーティングシステムでテストを実行したい場合は、継続的インテグレーションを利用できます。詳しくはこちらをご覧ください。

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

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

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

Hatch が好みでない場合は、次のレッスンで取り上げる Nox が代替ツールです。nox は Python ベースの自動化ツールで、make と tox の両方の機能をベースにしています。nox はテストと開発のワークフローを簡素化し、効率化するように設計されています。nox で行うことはすべて、Python ベースのインターフェースを使って実装できます。nox の使い方について詳しくはこちらで学べます。

その他の自動化ツール

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

• Make はビルド自動化ツールで、その汎用性の高さからテストの実行に使う開発者もいます。しかし、Make の独特な構文は習得が難しく、Hatch や Nox のような環境管理は行ってくれません。

Hatch でテストを実行する

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

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

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

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

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

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

Hatch 環境のセットアップ

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].

[dependency-groups]
test = [
    "pytest",
    "pytest-cov"
]

[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 を使用したテストの実行

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

利用可能な環境の一覧表示:

hatch env show

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

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

複数の Python バージョンにまたがるテスト

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.

次のステップ

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