自動テストしたい(tox)

$ tox --version
4.60.0 from [PATH]

$ tox

toxは複数のテストを組み合わせて自動化できるツールです。 tox.iniもしくはpyproject.tomlで設定します。

Pythonのランタイムごとに仮想環境を作成し、 フォーマッター&リンター、 型チェック、 ユニットテストのすべてをtoxコマンドひとつで実行できるようになります。

インストールしたい(tox)

  • pipxでインストール

$ pipx install tox
  • poetryでインストール

$ poetry add tox --group test
  • uvでインストール

$ uv tool install tox

設定したい(tox.toml)

1env_list = ["py312"]
2
3[env_run_base]
4deps = ["pytest"]
5commands = [["pytest"]]

プロジェクトルートにtox.tomlを配置すると、TOML形式で設定を書けます。 env_listでテストするPython環境(envlistのTOML版)を指定します。 [env_run_base]([testenv]のTOML版)に、各環境で共通のインストールパッケージや実行コマンドを書きます。 commandsは、1つのコマンドを文字列の配列として書き、それをさらに配列で囲みます。

注釈

従来のtox.ini(INI形式)も引き続き使えます。 pyproject.tomlの[tool.tox]セクションに、 legacy_tox_iniというキーでtox.iniの内容を文字列としてまるごと埋め込むこともできますが、 TOMLの中にINIを文字列として書く形になるため、素直にtox.tomlを使う方がわかりやすいです。

複数の自動テストを組み合わせたい

1env_list = ["py311", "py312", "lint"]
2
3[env_run_base]
4deps = ["pytest"]
5commands = [["pytest"]]
6
7[env.lint]
8deps = ["ruff"]
9commands = [["ruff", "check", "."]]

env_listに複数の環境名を並べると、toxコマンド1つでそれぞれが順番に実行されます。 py311、py312のようなpy<バージョン>という名前の環境は、 [env_run_base]の設定(共通の依存・コマンド)を使ってそのPythonバージョンで実行されます。 lintのような任意の名前の環境は、[env.<環境名>]で個別に依存やコマンドを上書きできます。 上記の例では、Python 3.11と3.12でそれぞれpytestを実行しつつ、 lint環境でruff check .を実行しています。

$ tox
...
  py311: OK (3.25=setup[2.24]+cmd[1.01] seconds)
  py312: OK (1.83=setup[1.31]+cmd[0.52] seconds)
  lint: OK (1.86=setup[1.50]+cmd[0.36] seconds)
  congratulations :) (6.95 seconds)

すべての環境が成功すると、最後にサマリーが表示されます。 Pythonバージョンごとのユニットテストと、リンター・型チェックなど種類の異なるチェックを、 まとめて1コマンドで実行できるのがtoxの強みです。

リファレンス