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

    Labels

    No labels
    No labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions