test_tmpdir.py

Overview

The [test_tmpdir.py](/projects/286/67363) file is a comprehensive test suite focused on validating the temporary directory handling features of the `pytest` testing framework, specifically around the `tmp_path` and `tmp_path_factory` fixtures. These fixtures provide temporary filesystem locations for tests to use, ensuring isolation and cleanup between test runs.

This file contains various tests that cover:

• Creation and management of temporary directories using tmp_path and tmp_path_factory.

• Behavior of temporary directory retention policies (e.g., keeping failed test directories).

• Handling of path naming, including relative vs absolute paths and invalid characters.

• Permission issues related to temporary directories and files, including read-only files.

• Symlink handling and cleanup locking mechanisms to prevent premature deletion.

• Fall-back behaviors for user detection in restricted environments (e.g., missing environment variables or invalid user IDs).

• Validation of the internal algorithms that create numbered temporary directories and cleanup old ones.

The tests often leverage the `pytester` utility fixture, which facilitates running pytest sessions programmatically and inspecting their outcomes.

Classes and Functions

FakeConfig

A minimal dataclass simulating a subset of the `Config` interface required by `TempPathFactory`.

Attributes:

• basetemp: str | Path — Base temporary directory path.

Properties and Methods:

• trace (property) — Returns self, placeholder for tracing.

• get(key) — Returns a no-op lambda function for any key.

• getini(name) — Returns configured values for tmp_path_retention_count (3) and tmp_path_retention_policy ("all"). Raises assertion error for unknown keys.

• option (property) — Returns self.

**Usage example:**

config = FakeConfig("/tmp/pytest")
print(config.getini("tmp_path_retention_count"))  # Output: 3

TestTmpPathHandler

Test class for verifying the behavior of `TempPathFactory` and `tmp_path` fixture handling.

Methods:

• test_mktemp(self, tmp_path: Path) -> None
  Tests creating numbered temporary directories using TempPathFactory.mktemp(). Ensures naming follows expected conventions with numeric suffixes.

• test_tmppath_relative_basetemp_absolute(self, tmp_path: Path, monkeypatch: MonkeyPatch) -> None
  Verifies that a relative basetemp path provided in the config is resolved to an absolute path based on the current working directory.

TestConfigTmpPath

Tests related to temporary directory retention policies and cleanup behavior configured via pytest options.

Key test methods:

• test_getbasetemp_custom_removes_old
  Ensures that if a custom basetemp directory exists with files from previous runs, those files are removed when pytest reruns.

• test_policy_failed_removes_only_passed_dir
  Tests the "failed" retention policy by running tests with both passing and failing cases, verifying only failed test directories remain.

• test_policy_failed_removes_basedir_when_all_passed
  Confirms that when all tests pass under the "failed" retention policy, the base directories are cleaned up fully.

• test_policy_failed_removes_dir_when_skipped_from_fixture
  Checks that directories for skipped tests are cleaned under "failed" policy.

• test_policy_all_keeps_dir_when_skipped_from_fixture
  Opposite of above, confirming that "all" policy retains directories even if tests skipped.

Parameterized Test: test_mktemp

A parameterized test checking valid and invalid directory base names when creating temp directories with `tmp_path_factory.mktemp()` with `numbered=False`.

• Parameters:

  • basename: str — Base directory name to create.

  • is_ok: bool — Expected success/failure of creation.

• Behavior:

  • Creates a pytest test file that attempts to create a temp directory with the given base name.

  • Runs pytest and validates whether creation succeeded or raised a ValueError.

Utility Function: attempt_symlink_to(path, to_path)

Attempts to create a symbolic link at `path` pointing to `to_path`. If the operation fails due to platform limitations or permissions (common on Windows), the test is skipped.

Classes Testing Directory Numbering and Cleanup

TestNumberedDir

Tests the behavior of creating numbered directories with a prefix and cleaning up old numbered directories.

• test_make — Creates 10 numbered directories with a prefix and verifies naming and symlink to "current" directory.

• test_cleanup_lock_create — Tests creation and exclusivity of cleanup lock files.

• test_lock_register_cleanup_removal — Tests registering cleanup functions that remove cleanup locks correctly.

• test_cleanup_keep, test_cleanup_keep_0 — Verifies that cleanup removes old directories keeping only a specified number.

• test_cleanup_locked — Tests the behavior when directories are locked for cleanup.

• test_cleanup_ignores_symlink — Ensures cleanup does not affect symlink directories.

• test_removal_accepts_lock — Verifies that deletion does not remove locked directories.

Class: TestRmRf

Tests the `rm_rf` function that forcibly removes files and directories, including handling read-only files and directories.

• test_rm_rf — Basic removal of directories with and without files.

• test_rm_rf_with_read_only_file — Ensures removal of directories containing read-only files.

• test_rm_rf_with_read_only_directory — Ensures removal of read-only directories.

• test_on_rm_rf_error — Validates error handling callback during removal, including ignoring certain errors and warnings.

Miscellaneous Tests

• test_tmp_path_always_is_realpath
  Verifies that tmp_path fixture always returns an absolute resolved realpath rather than a symlink path.

• test_tmp_path_too_long_on_parametrization
  Checks that long parameterized test arguments do not break tmp_path functionality.

• test_tmp_path_factory
  Confirms the session-scoped fixture usage of tmp_path_factory.

• test_tmp_path_fallback_tox_env
  Tests that tmp_path works even if environment variables normally used for username detection are missing.

• test_tmp_path_factory_handles_invalid_dir_characters
  Tests sanitization of invalid characters in directory names when creating basetemp.

• test_tmp_path_factory_create_directory_with_safe_permissions
  Ensures that pytest creates temporary directories with safe (private) Unix permissions.

• test_tmp_path_factory_fixes_up_world_readable_permissions
  Fixes permissions if existing temp directories have insecure world-readable permissions.

• test_get_user_uid_not_found and test_get_user
  Tests the get_user() function fallback behavior when user ID is not found or environment variables are missing.

Important Implementation Details and Algorithms

• Numbered Directory Creation:
  The function make_numbered_dir is used to create directories with a given prefix and a numeric suffix (e.g., fun-0, fun-1, ...). This ensures unique temporary directories can be created sequentially.

• Cleanup Lock:
  A lock file is created inside the numbered directory to prevent concurrent cleanup or deletion. This lock is checked to determine whether a directory is deletable. If the lock is valid, the directory is preserved.

• Retention Policies:
  The system supports different retention policies configured via pytest ini options:

  • "all": Keep all temporary directories.

  • "failed": Keep only directories related to tests that failed.

  • Retention count controls how many directories to keep when cleaning up.

• Read-only Files and Directories:
  The rm_rf function is robust against files or directories that are marked read-only by altering permissions before deletion.

• User Fallback Handling:
  The get_user function attempts to safely determine the current user but falls back to None if the environment or system calls fail, ensuring temporary directory creation does not fail due to user detection.

Interaction with Other System Components

• _pytest.tmpdir module:
  This file tests the features implemented in the _pytest.tmpdir module, especially the TempPathFactory class and related functionality.

• _pytest.pathlib module:
  Utilities like make_numbered_dir, cleanup_numbered_dir, create_cleanup_lock, and rm_rf are imported from _pytest.pathlib and are integral to managing temporary directories and cleanup.

• pytester fixture:
  Used extensively to execute pytest test runs programmatically and verify outcomes, simulating real user test runs.

• Configuration and Ini Options:
  The tests check options like tmp_path_retention_count and tmp_path_retention_policy configured via pytest ini files or CLI arguments.

• Monkeypatching:
  Used to manipulate environment variables and system functions to test edge cases and fallback behavior.

Visual Diagram

The following Mermaid class diagram summarizes the main test classes and their key methods in this file, illustrating their roles and relationships:

classDiagram
    class FakeConfig {
        +basetemp: str | Path
        +trace()
        +get(key)
        +getini(name)
        +option()
    }

    class TestTmpPathHandler {
        +test_mktemp(tmp_path: Path)
        +test_tmppath_relative_basetemp_absolute(tmp_path: Path, monkeypatch: MonkeyPatch)
    }

    class TestConfigTmpPath {
        +test_getbasetemp_custom_removes_old(pytester: Pytester)
        +test_policy_failed_removes_only_passed_dir(pytester: Pytester)
        +test_policy_failed_removes_basedir_when_all_passed(pytester: Pytester)
        +test_policy_failed_removes_dir_when_skipped_from_fixture(pytester: Pytester)
        +test_policy_all_keeps_dir_when_skipped_from_fixture(pytester: Pytester)
    }

    class TestNumberedDir {
        +test_make(tmp_path: Path)
        +test_cleanup_lock_create(tmp_path: Path)
        +test_lock_register_cleanup_removal(tmp_path: Path)
        +test_cleanup_keep(tmp_path: Path)
        +test_cleanup_keep_0(tmp_path: Path)
        +test_cleanup_locked(tmp_path: Path)
        +test_cleanup_ignores_symlink(tmp_path: Path)
        +test_removal_accepts_lock(tmp_path: Path)
    }

    class TestRmRf {
        +test_rm_rf(tmp_path: Path)
        +test_rm_rf_with_read_only_file(tmp_path: Path)
        +test_rm_rf_with_read_only_directory(tmp_path: Path)
        +test_on_rm_rf_error(tmp_path: Path)
        +chmod_r(path)
    }

    FakeConfig <|-- TestTmpPathHandler : uses
    TestConfigTmpPath --> pytester : uses
    TestNumberedDir --> pathlib : uses utilities
    TestRmRf --> pathlib : uses rm_rf and error handling

Summary

The [test_tmpdir.py](/projects/286/67363) file is a critical test suite ensuring that pytest's temporary directory management works reliably across various environments, configurations, and edge cases. It validates creation, cleanup, permission handling, and retention policies of temporary directories, providing confidence that tests using `tmp_path` and `tmp_path_factory` fixtures can safely operate on isolated filesystem locations without interference or resource leakage.