Testing projects¶

testコマンド(by default)は、pytestと選択プラグインおよびcoverage.pyを使用します。詳細については、testing configurationを参照してください。

ほとんどのプロジェクトは、カスタムenvironmentsを必要とせずに、この方法で完全にテストできます。

Passing arguments¶

引数なしでtestコマンドを実行すると、testsはdefault argumentとしてpytestに渡されます(これはtestsディレクトリがあることを前提としています)。たとえば、次のコマンドを呼び出します。:

hatch test

大まかには次のように変換されます。:

pytest tests

pytestに引数を渡すには、testコマンドに引数を追加します。たとえば、次のコマンドを呼び出します。:

hatch test -vv tests/test_foo.py::test_bar

大まかには次のように変換されます。:

pytest -vv tests/test_foo.py::test_bar

--セパレータを使用すると、引数を強制的に定位置として扱うことができます。これは、--helpフラグなど、testコマンドの組み込みフラグがpytestの組み込みフラグと競合する場合に特に便利です。たとえば、次のコマンドを呼び出します。:

hatch test -r -- -r fE -- tests

大まかには次のように変換されます。:

pytest -r fE -- tests

Environment selection¶

Single environment¶

環境オプションが選択されていない場合、「test」コマンドは、すでに存在するか互換性のある最初に定義された環境でのみテストを実行します。さらに、チェック順序は、Hatchが実行されているインタプリタと一致するversion of Pythonを定義する環境を優先します。

たとえば、次のようにdefault matrixをオーバーライドしたとします。:

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

[[tool.hatch.envs.hatch-test.matrix]]
python = ["3.11"]
feature = ["foo", "bar"]

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

[[envs.hatch-test.matrix]]
python = ["3.11"]
feature = ["foo", "bar"]

拡張環境は通常、次のようになります。:

hatch-test.py3.12
hatch-test.py3.11
hatch-test.py3.11-foo
hatch-test.py3.11-bar

Python 3.11にHatchをインストールした場合、チェックの順序は次のようになります。:

hatch-test.py3.11
hatch-test.py3.11-foo
hatch-test.py3.11-bar
hatch-test.py3.12

All environments¶

--allフラグを使用すると、互換性のあるすべての環境でテストを実行できます。たとえば、次のようにmatrixとoverridesを定義したとします。:

[[tool.hatch.envs.hatch-test.matrix]]
python = ["3.12", "3.11"]
feature = ["foo", "bar"]

[tool.hatch.envs.hatch-test.overrides]
matrix.feature.platforms = [
  { value = "linux", if = ["foo", "bar"] },
  { value = "windows", if = ["foo"] },
  { value = "macos", if = ["bar"] },
]

[[envs.hatch-test.matrix]]
python = ["3.12", "3.11"]
feature = ["foo", "bar"]

[envs.hatch-test.overrides]
matrix.feature.platforms = [
  { value = "linux", if = ["foo", "bar"] },
  { value = "windows", if = ["foo"] },
  { value = "macos", if = ["bar"] },
]

次の表に、テストが実行される環境を示します。:

Environment	Linux	Windows	macOS
hatch-test.py3.12-foo
hatch-test.py3.12-bar
hatch-test.py3.11-foo
hatch-test.py3.11-bar

Specific environments¶

環境のサブセットを選択するには、--include/-iおよび--exclude/-xオプションを使用します。これらのオプションは、特定のマトリックス変数を含めたり除外したりするために使用でき、オプションでその後に特定のカンマ区切りの値が続き、複数回選択できます。

たとえば、マトリックスを次のように定義したとします。:

[[tool.hatch.envs.hatch-test.matrix]]
python = ["3.12", "3.11"]
feature = ["foo", "bar", "baz"]

[[envs.hatch-test.matrix]]
python = ["3.12", "3.11"]
feature = ["foo", "bar", "baz"]

Python 3.12とfooまたはbar機能を持つすべての環境でテストを実行したい場合は、次のコマンド呼び出しを使用できます。:

hatch test -i python=3.12 -i feature=foo,bar

あるいは、同じ結果を得るためにbaz機能を除外することもできます。:

hatch test -i python=3.12 -x feature=baz

hatch test -py 3.12 -i feature=foo,bar
hatch test -py 3.12 -x feature=baz

Measuring code coverage¶

--coverフラグを使用すると、code coverageを有効にできます。たとえば、次のコマンドを呼び出します。:

hatch test --cover

大まかには次のように変換されます。:

coverage run -m pytest tests

すべてのselected environmentsでテストが実行された後、カバレッジデータが結合され、レポートが表示されます。--cover-quietフラグを使用してレポートを抑制し、--coverフラグを暗黙的に有効にすることができます。:

hatch test --cover-quiet

.coverage*

Retry failed tests¶

--retriesオプションを使用すると、失敗したテストをretryできます。:

hatch test --retries 2

テストが毎回失敗し、再試行回数が2に設定されている場合、テストは合計3回実行されます。

--retry-delayオプションを使用して、再試行の間隔を秒単位で設定することもできます。:

hatch test --retries 2 --retry-delay 1

Parallelize test execution¶

--parallel/-pフラグを使用して、parallelizeテストを実行できます。:

hatch test --parallel

これにより、環境内のテストが複数のワーカーに分散されます。ワーカーの数は、使用可能な物理CPUではなく論理CPUの数に対応します。

Randomize test order¶

--randomize/-rフラグを使用すると、テストの順序をrandomizeできます。:

hatch test --randomize