Skip to content

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:

[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:

[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:

[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:

[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:

[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:

[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:

[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:

[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:

[[tool.hatch.envs.hatch-test.matrix]]
python = ["3.13", "3.12", "3.11", "3.10", "3.9", "3.8"]
[[envs.hatch-test.matrix]]
python = ["3.13", "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:

[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:

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