Improve docs on basetemp and retention

[soxofaan]

Improve coverage of current handling of --basetemp option and its lack of retention functionality.

• [ ] Include documentation when adding new features.
• [ ] Include new tests or update existing tests when applicable.
• Allow maintainers to push and squash when merging my commits.
• Add text like closes #XYZW to the PR description and/or commits (where XYZW is the issue number). See the github docs for more information.
• Create a new changelog file in the changelog folder, with a name like <ISSUE NUMBER>.<TYPE>.rst. See changelog/README.rst for details.
• Add yourself to AUTHORS in alphabetical order.

Addresses (part of) issue #10829:
the --basetemp option and the default retention feature can not be combined currently. This is completely unclear from the current docs. While I initially requested to allow the combination of retention with --basetemp in #10829, this PR just attempts better document the current behavior.

[soxofaan]

Note that this PR introduces the exposure of the PYTEST_DEBUG_TEMPROOT env var

pytest/src/_pytest/tmpdir.py

Lines 157 to 158 in 26215b8

	from_env = os.environ.get("PYTEST_DEBUG_TEMPROOT")
	temproot = Path(from_env or tempfile.gettempdir()).resolve()

I'm not sure if that is desired. Maybe it's only intended as internal implementation detail for testing purposes.

However, I think it's pretty valuable to have this a tool to finetune the "temproot" in practice (e.g. as discussed in #10829 as well)

[nicoddemus]

This is looks much better, thanks!

[soxofaan]

Note that this PR introduces the exposure of the PYTEST_DEBUG_TEMPROOT env var

a concern here is that this env var contains "DEBUG" in it's name, which makes it look like it's not ready for production use. As a user I'm not interested to use this for one-off debug use cases, I want to use this in real CI contexts.

Is there opportunity to rename this env var to, for example, PYTEST_TEMPROOT ?

[nicoddemus]

Regardless if we want to rename or not, we should document the existing var -- renaming it should be discussed in a separate issue.

[soxofaan]

I'm suggesting the rename here as it seems less cumbersome to do a rename before it making a publicly documented feature than the other way around.

[soxofaan]

FYI I'm just assuming PYTEST_DEBUG_TEMPROOT is an undocumented implementation detail, as I couldn't find any pointers in public online docs. But maybe there is already usage in the wild

[soxofaan]

but indeed, regardless, you still have to document something like

before pytest version x.y.z you have to use PYTEST_DEBUG_TEMPROOT instead of PYTEST_TEMPROOT.

[nicoddemus]

FYI I'm just assuming PYTEST_DEBUG_TEMPROOT is an undocumented implementation detail, as I couldn't find any pointers in public online docs. But maybe there is already usage in the wild

You are right in your assumption, but it seems it is used in the wild:

https://github.com/search?q=PYTEST_DEBUG_TEMPROOT&type=code

So we do need to document it regardless, even if we were to change it later (which I don't think is something worthwhile to do).

[nicoddemus]

Thanks @soxofaan, looks great!

I will leave it open for a few more days to give others a chance to chime in. 👍

[patchback]

Backport to 8.3.x: 💚 backport PR created

✅ Backport PR branch: patchback/backports/8.3.x/a1a491837b35b719d77b4f03be318b505d495386/pr-12912

Backported as #12928

🤖 @patchback
I'm built with octomachinery and
my source is open — https://github.com/sanitizers/patchback-github-app.