Testing configuration¶

Check out the testing overview tutorial for a more comprehensive walk-through.

Settings¶

If an option has a corresponding test command flag, the flag will always take precedence.

Default arguments¶

You can define default arguments for the test command by setting the default-args option, which must be an array of strings. The following is the default configuration:

pyproject.toml hatch.toml


[tool.hatch.envs.hatch-test]
default-args = ["tests"]


[envs.hatch-test]
default-args = ["tests"]

Extra arguments¶

You can define extra internal arguments for test scripts by setting the extra-args option, which must be an array of strings. For example, if you wanted to increase the verbosity of pytest, you could set the following:

pyproject.toml hatch.toml


[tool.hatch.envs.hatch-test]
extra-args = ["-vv"]


[envs.hatch-test]
extra-args = ["-vv"]

Randomize test order¶

You can randomize the order of tests by enabling the randomize option which corresponds to the --randomize/-r flag:

pyproject.toml hatch.toml


[tool.hatch.envs.hatch-test]
randomize = true


[envs.hatch-test]
randomize = true

Parallelize test execution¶

You can parallelize test execution by enabling the parallel option which corresponds to the --parallel/-p flag:

pyproject.toml hatch.toml


[tool.hatch.envs.hatch-test]
parallel = true


[envs.hatch-test]
parallel = true

Retry failed tests¶

You can retry failed tests by setting the retries option which corresponds to the --retries flag:

pyproject.toml hatch.toml


[tool.hatch.envs.hatch-test]
retries = 2


[envs.hatch-test]
retries = 2

You can also set the number of seconds to wait between retries by setting the retry-delay option which corresponds to the --retry-delay flag:

pyproject.toml hatch.toml


[tool.hatch.envs.hatch-test]
retry-delay = 1


[envs.hatch-test]
retry-delay = 1

Customize environment¶

You can fully alter the behavior of the environment used by the test command.

Dependencies¶

You can define extra dependencies that your tests may require:

pyproject.toml hatch.toml


[tool.hatch.envs.hatch-test]
extra-dependencies = [
  "pyfakefs",
  "pytest-asyncio",
  "pytest-benchmark",
  "pytest-memray",
  "pytest-playwright",
  "pytest-print",
]


[envs.hatch-test]
extra-dependencies = [
  "pyfakefs",
  "pytest-asyncio",
  "pytest-benchmark",
  "pytest-memray",
  "pytest-playwright",
  "pytest-print",
]

The following is the default configuration:

pyproject.toml hatch.toml


[tool.hatch.envs.hatch-test]
dependencies = [
  "coverage-enable-subprocess==1.0",
  "coverage[toml]~=7.4",
  "pytest~=8.1",
  "pytest-mock~=3.12",
  "pytest-randomly~=3.15",
  "pytest-rerunfailures~=14.0",
  "pytest-xdist[psutil]~=3.5",
]


[envs.hatch-test]
dependencies = [
  "coverage-enable-subprocess==1.0",
  "coverage[toml]~=7.4",
  "pytest~=8.1",
  "pytest-mock~=3.12",
  "pytest-randomly~=3.15",
  "pytest-rerunfailures~=14.0",
  "pytest-xdist[psutil]~=3.5",
]

Matrix¶

You can override the default series of matrices:

pyproject.toml hatch.toml


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


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

Scripts¶

If you want to change the default commands that are executed, you can override the scripts. The following default scripts must be redefined:

pyproject.toml hatch.toml


[tool.hatch.envs.hatch-test.scripts]
run = "pytest{env:HATCH_TEST_ARGS:} {args}"
run-cov = "coverage run -m pytest{env:HATCH_TEST_ARGS:} {args}"
cov-combine = "coverage combine"
cov-report = "coverage report"


[envs.hatch-test.scripts]
run = "pytest{env:HATCH_TEST_ARGS:} {args}"
run-cov = "coverage run -m pytest{env:HATCH_TEST_ARGS:} {args}"
cov-combine = "coverage combine"
cov-report = "coverage report"

The run script is the default behavior while the run-cov script is used instead when measuring code coverage. The cov-combine script runs after all tests complete when measuring code coverage, as well as the cov-report script when not using the --cover-quiet flag.

Note

The HATCH_TEST_ARGS environment variable is how the test command's flags are translated and internally populated without affecting the user's arguments. This is also the way that extra arguments are passed.

Installer¶

By default, UV is enabled. You may disable that behavior as follows:

pyproject.toml hatch.toml


[tool.hatch.envs.hatch-test]
installer = "pip"


[envs.hatch-test]
installer = "pip"