Skip to content

Docs/UX: hatch test -h should reference testing configuration and default dependencies #2202

@ssiccha

Description

@ssiccha

When using hatch test, the environment comes with hard-coded default dependencies (pytest, coverage, pytest-rerunfailures, etc.). This can lead to confusing errors when a user adds a conflicting version via
extra-dependencies:

[tool.hatch.envs.hatch-test]
extra-dependencies = [
    "pytest-rerunfailures==15.0",
]
$ hatch test -py 3.12
  × No solution found when resolving dependencies:
  ╰─▶ Because you require pytest-rerunfailures>=14.0,<15.dev0 and pytest-rerunfailures==15.0,
      we can conclude that your requirements are unsatisfiable.

The error gives no indication that pytest-rerunfailures~=14.0 comes from hatch's built-in defaults. The user has to know to run hatch test --show, then figure out that some deps are defaults vs user-specified, then find the testing configuration docs to understand the dependencies vs extra-dependencies distinction.

Suggestions:

  1. The Dependencies section of the testing config docs should note that
    extra-dependencies is additive and will conflict if you specify a package already present in the defaults with an incompatible version. The
    workaround (overriding dependencies entirely) should be mentioned explicitly.

  2. hatch test -h should include a link to the testing configuration docs page (https://hatch.pypa.io/latest/config/internal/testing/), similar
    to how the description already mentions "View the testing configuration for more information" in the tutorial but not in the CLI help. Maybe also explicitly state that hatch-test env default dependencies are listed there

Metadata

Metadata

Assignees

No one assigned

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions